5.2 Safe C Vectors

► |  | 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

▼ | 5 | Derived Utilities

5.1 | Safe Homogenous Vectors
5.2 | Safe C Vectors
5.3 | Tagged C Pointer Types
5.4 | Defining Bindings
5.5 | Allocation and Finalization
5.6 | Custodian Shutdown Registration
5.7 | Atomic Execution
5.8 | Speculatively Atomic Execution
5.9 | Objective-C FFI
5.10 | Cocoa Foundation
5.11 | COM (Common Object Model)
5.12 | File Security-Guard Checks
5.13 | Windows API Helpers

On this page:

_ cvector
make-cvector
cvector
cvector?
cvector-length
cvector-type
cvector-ptr
cvector-ref
cvector-set!
cvector->list
list->cvector
make-cvector*

top ← prev up next →

#### 5.2`` Safe C Vectors

(require ffi/cvector)
(require ffi/unsafe/cvector)

The ffi/unsafe/cvector library exports the bindings of this section. The ffi/cvector library exports the same bindings, except for the unsafe make-cvector* operation.

The cvector form can be used as a type C vectors (i.e., a pointer to a memory block).

> syntax (_cvector mode type maybe-len)
> _cvector

Like _bytes, _cvector can be used as a simple type that corresponds to a pointer that is managed as a safe C vector on the Racket side. The longer form behaves similarly to the _list and _vector custom types, except that _cvector is more efficient; no Racket list or vector is needed.

> procedure (make-cvector type length) → cvector?
> type : ctype?
> length : exact-nonnegative-integer?

Allocates a C vector using the given type and length. The resulting vector is not guaranteed to contain any particular values.

> procedure (cvector type val ...) → cvector?
> type : ctype?
> val : any/c

Creates a C vector of the given type, initialized to the given list of vals.

> procedure (cvector? v) → boolean?
> v : any/c

Returns #t if v is a C vector, #f otherwise.

> procedure (cvector-length cvec) → exact-nonnegative-integer?
> cvec : cvector?

Returns the length of a C vector.

> procedure (cvector-type cvec) → ctype?
> cvec : cvector?

Returns the C type object of a C vector.

> procedure (cvector-ptr cvec) → cpointer?
> cvec : cvector?

Returns the pointer that points at the beginning block of the given C vector.

> procedure (cvector-ref cvec k) → any
> cvec : cvector?
> k : exact-nonnegative-integer?

References the kth element of the cvec C vector. The result has the type that the C vector uses.

> procedure (cvector-set! cvec k val) → void?
> cvec : cvector?
> k : exact-nonnegative-integer?
> val : any

Sets the kth element of the cvec C vector to val. The val argument should be a value that can be used with the type that the C vector uses.

> procedure (cvector->list cvec) → list?
> cvec : cvector?

Converts the cvec C vector object to a list of values.

> procedure (list->cvector lst type) → cvector?
> lst : list?
> type : ctype?

Converts the list lst to a C vector of the given type.

> procedure (make-cvector* cptr type length) → cvector?
> cptr : any/c
> type : ctype?
> length : exact-nonnegative-integer?

Constructs a C vector using an existing pointer object. This operation is not safe, so it is intended to be used in specific situations where the type and length are known.
top ← prev up next →