91 lines
2.7 KiB
Racket
91 lines
2.7 KiB
Racket
#lang scribble/doc
|
|
@(require "utils.ss")
|
|
|
|
@title[#:tag "foreign:cvector"]{Safe C Vectors}
|
|
|
|
@defmodule*[(ffi/cvector ffi/unsafe/cvector)
|
|
#:use-sources (ffi/unsafe/cvector)]{The
|
|
@schememodname[ffi/unsafe/cvector] library exports the bindings of
|
|
this section. The @schememodname[ffi/cvector] library exports the same
|
|
bindings, except for the unsafe @scheme[make-cvector*] operation.}
|
|
|
|
The @scheme[cvector] form can be used as a type C vectors (i.e., a
|
|
pointer to a memory block).
|
|
|
|
@defform*[[(_cvector mode type maybe-len)
|
|
_cvector]]{
|
|
|
|
Like @scheme[_bytes], @scheme[_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
|
|
@scheme[_list] and @scheme[_vector] custom types, except that
|
|
@scheme[_cvector] is more efficient; no Racket list or vector is
|
|
needed.}
|
|
|
|
@defproc[(make-cvector [type ctype?] [length exact-nonnegative-integer?]) cvector?]{
|
|
|
|
Allocates a C vector using the given @scheme[type] and
|
|
@scheme[length]. The resulting vector is not guaranteed to
|
|
contain any particular values.}
|
|
|
|
|
|
@defproc[(cvector [type ctype?] [val any/c] ...) cvector?]{
|
|
|
|
Creates a C vector of the given @scheme[type], initialized to the
|
|
given list of @scheme[val]s.}
|
|
|
|
|
|
@defproc[(cvector? [v any/c]) boolean?]{
|
|
|
|
Returns @scheme[#t] if @scheme[v] is a C vector, @scheme[#f] otherwise.}
|
|
|
|
|
|
@defproc[(cvector-length [cvec cvector?]) exact-nonnegative-integer?]{
|
|
|
|
Returns the length of a C vector.}
|
|
|
|
|
|
@defproc[(cvector-type [cvec cvector?]) ctype?]{
|
|
|
|
Returns the C type object of a C vector.}
|
|
|
|
|
|
@defproc[(cvector-ptr [cvec cvector?]) cpointer?]{
|
|
|
|
Returns the pointer that points at the beginning block of the given C vector.}
|
|
|
|
|
|
@defproc[(cvector-ref [cvec cvector?] [k exact-nonnegative-integer?]) any]{
|
|
|
|
References the @scheme[k]th element of the @scheme[cvec] C vector.
|
|
The result has the type that the C vector uses.}
|
|
|
|
|
|
@defproc[(cvector-set! [cvec cvector?] [k exact-nonnegative-integer?] [val any]) void?]{
|
|
|
|
Sets the @scheme[k]th element of the @scheme[cvec] C vector to
|
|
@scheme[val]. The @scheme[val] argument should be a value that can be
|
|
used with the type that the C vector uses.}
|
|
|
|
|
|
@defproc[(cvector->list [cvec cvector?]) list?]{
|
|
|
|
Converts the @scheme[cvec] C vector object to a list of values.}
|
|
|
|
|
|
@defproc[(list->cvector [lst list?] [type ctype?]) cvector?]{
|
|
|
|
Converts the list @scheme[lst] to a C vector of the given
|
|
@scheme[type].}
|
|
|
|
|
|
@defproc[(make-cvector* [cptr any/c] [type ctype?]
|
|
[length exact-nonnegative-integer?])
|
|
cvector?]{
|
|
|
|
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 @scheme[type] and @scheme[length] are known.}
|
|
|
|
|