3.8 C Array Types

► |  | The Racket Foreign Interface

1 | Overview
2 | Loading Foreign Libraries
3 | C Types
4 | Pointer Functions
5 | Derived Utilities
6 | Miscellaneous Support
7 | Unexported Primitive Functions
| Bibliography
| Index

▼ | 3 | C Types

3.1 | Type Constructors
3.2 | Numeric Types
3.3 | Other Atomic Types
3.4 | String Types
3.5 | Pointer Types
3.6 | Function Types
3.7 | C Struct Types
3.8 | C Array Types
3.9 | C Union Types
3.10 | Enumerations and Masks

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 ← prev up next →

#### 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 ← prev up next →