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 | Serializable C Struct Types
5.5 | Static Callout and Callback Cores
5.6 | Defining Bindings
5.7 | Allocation and Finalization
5.8 | Custodian Shutdown Registration
5.9 | Atomic Execution
5.10 | Speculatively Atomic Execution
5.11 | Thread Scheduling
5.12 | Ports
5.13 | Process-Wide and Place-Wide Registration
5.14 | Operating System Threads
5.15 | Garbage Collection Callbacks
5.16 | Objective-C FFI
5.17 | Cocoa Foundation
5.18 | COM (Common Object Model)
5.19 | File Security-Guard Checks
5.20 | Windows API Helpers
5.21 | Virtual Machine Primitives

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

### 5.2 Safe C Vectors🔗ℹ

(require ffi/cvector) | package: base
(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 contents ← prev up next →