►The Racket Foreign Interface
▼3 C Types
On this page:
make-array-type
_  array
array?
array-ref
array-set!
array-ptr
array-length
array-type
in-array
_  array/  list
_  array/  vector
  top  contents    up   

3.8 C Array Types🔗ℹ

procedure

(make-array-type type count) → ctype?

  type : ctype?
  count : exact-nonnegative-integer?
The primitive type constructor for creating new C array types. Like C struct types, array types are new primitive types with no conversion functions associated. When used as a function argument or return type, array types behave like pointer types; otherwise, array types behave like struct types (i.e., a struct with as many fields as the array has elements), particularly when used for a field within a struct type.

Since an array is treated like a struct, casting a pointer type to an array type does not work. Instead, use ptr-ref with a pointer, an array type constructed with _array, and index 0 to convert a pointer to a Racket representation that works with array-ref and array-set!.

procedure

(_array type count ...+) → ctype?

  type : ctype?
  count : exact-nonnegative-integer?
Creates an array type whose Racket representation is an array that works with array-ref and array-set!. The array is not copied; the Racket representation is backed by the underlying C representation.

Supply multiple counts for a multidimensional array. Since C uses row-major order for arrays, (_array t n m) is equivalent to (_array (_array t m) n), which is different from an array of pointers to arrays.

When a value is used as an instance of an array type (e.g., as passed to a foreign function), checking ensures that the given value is an array of at least the expected length and whose elements have the same representation according to ctype->layout; the array can have additional elements, and it can have a different element type as long as that type matches the layout of the expected type.

procedure

(array? v) → boolean?

  v : any/c
Returns #t if v is a Racket representation of a C value via _array, #f otherwise.

procedure

(array-ref a i ...+) → any/c

  a : array?
  i : exact-nonnegative-integer?
Extracts an element from an array. Use multiple i indices for a multidimensional array access; using fewer indices than the array dimension produces a sub-array.

procedure

(array-set! a i ...+ v) → void?

  a : array?
  i : exact-nonnegative-integer?
  v : any/c
Sets an element in an array. Use multiple i indices for a multidimensional array update; using fewer indices than the array dimension sets a sub-array (i.e., v must be an array of the same size as the sub-array and v is copied into the sub-array).

procedure

(array-ptr a) → cpointer?

  a : array?
Extracts the pointer for an array’s storage.

procedure

(array-length a) → exact-nonnegative-integer?

  a : array?
Extracts the length of an array. For a multidimensional array, the result is still a single number; extract an element to get a sub-array to get the length of the next dimension, and so on.

procedure

(array-type a) → ctype?

  a : array?
Extracts the type of the array. For a multidimensional array, the result is the ctype of the nested array.

procedure

(in-array a [start stop step]) → sequence?

  a : array?
  start : exact-nonnegative-integer? = 0
  stop : (or/c exact-integer? #f) = #f
  step : (and/c exact-integer? (not/c zero?)) = 1
Returns a sequence equivalent to a when no optional arguments are supplied.

The optional arguments start, stop, and step are as in in-vector.

procedure

(_array/list type count ...+) → ctype?

  type : ctype?
  count : exact-nonnegative-integer?
Like _array, but the Racket representation is a list (or list of lists for a multidimensional array) of elements copied to and from an underlying C array.

procedure

(_array/vector type count ...+) → ctype?

  type : ctype?
  count : exact-nonnegative-integer?
Like _array, but the Racket representation is a vector (or vector of vectors for a multidimensional array) of elements copied to and from an underlying C array.

  top  contents    up