replace-foreign-array

replace-foreign-array Function

Summary

Copies the contents of one foreign or Lisp array into another.

Package

fli

Signature

replace-foreign-array to from &key start1 start2 end1 end2 allow-sign-mismatch => to

Arguments

`to`⇩	A foreign array, foreign pointer or a Lisp array.
`from`⇩	A foreign array, foreign pointer or a Lisp array.
`start1`⇩, `start2`⇩, `end1`⇩, `end2`⇩
	Integers.
`allow-sign-mismatch`⇩	A boolean, default value `nil`.

Values

`to`	A foreign array, foreign pointer or a Lisp array.

Description

The function replace-foreign-array copies the contents of the array specified by from into another array specified by to. The arrays element types must have the same size and both be either signed or unsigned. When allow-sign-mismatch is nil (the default), the array element types must also match for sign, that is they must be either both signed or both unsigned. When allow-sign-mismatch is non-nil, the array element types do not need to match.

The argument to is destructively modified by copying successive elements into it from from. Elements of the subsequence of from bounded by start2 and end2 are copied into the subsequence of to bounded by start1 and end1. If these subsequences are not of the same length, then the shorter length determines how many elements are copied; the extra elements near the end of the longer subsequence are not involved in the operation.

Each of to and from can be one of the following:

A Lisp array	The start and end are handled in the same way as Common Lisp sequence functions. The array must be "raw", which means either an integer array of length 8, 16, 32 or 64 bits, or an array of one of cl:base-char, lw:bmp-char, cl:single-float and cl:double-float. For matching with the other argument, the latter are considered as "unsigned", with size 8, 16, 32 and 64 bits respectively. Note that arrays with element type cl:character are not allowed.
A foreign array	The start and end are handled in the same way as Common Lisp sequence functions.
A pointer to a foreign array
	The start and end are handled in the same way as Common Lisp sequence functions.
A pointer to any other foreign object
	In this case, the pointer is assumed to point to an array of such objects. Start and end are used as indices into that array, but without any bounds checking.

Compatibility note:

In LispWorks 6.1 and earlier versions you can use an array of lw:simple-char, that is lw:text-string, because lw:simple-char was limited to the range that is now lw:bmp-char and had width of 16.

In LispWorks 7.0 and later versions lw:simple-char is a synonym for cl:character, and thus arrays of lw:simple-char (that is, lw:text-string) cannot be used in replace-foreign-array.

Examples

This example demonstrates copying from a foreign pointer to a Lisp array.

An initial array filled with 42:

(setq lisp-array 
      (make-array 10 
                  :element-type '(unsigned-byte 8)
                  :initial-element 42))

A foreign pointer to 10 consecutive unsigned chars:

(setq foreign-array
      (fli:allocate-foreign-object 
       :type '(:unsigned :char)
       :nelems 10
       :initial-contents '(1 2 3 4 5 6 7 8 9 10)))

Copy some of the unsigned char into the Lisp array. Without :start2 and :end2, only the first unsigned char would be copied:

(fli:replace-foreign-array 
 lisp-array foreign-array
 :start1 3
 :start2 5 :end2 8)
=>
#(42 42 42 6 7 8 42 42 42 42)

This example demonstrates copying from a foreign array to a Lisp array.

A pointer to a foreign array of 10 unsigned chars:

(setq foreign-array
      (fli:allocate-foreign-object 
       :type 
       '(:c-array (:unsigned :char) 10)))
 
(dotimes (i 10) 
  (setf (fli:foreign-aref foreign-array i) (1+ i)))

Copy part of the foreign array into the Lisp array:

(fli:replace-foreign-array 
 lisp-array foreign-array :start1 7)
=>
#(42 42 42 6 7 8 42 1 2 3)