ac26fe7554
Also, updates some of the mzlib files to point at `racket/*' libraries rather than to `scheme/*' ones.
91 lines
2.7 KiB
Racket
91 lines
2.7 KiB
Racket
#lang scribble/doc
|
|
@(require "utils.rkt")
|
|
|
|
@title[#:tag "foreign:cvector"]{Safe C Vectors}
|
|
|
|
@defmodule*[(ffi/cvector ffi/unsafe/cvector)
|
|
#:use-sources (ffi/unsafe/cvector)]{The
|
|
@racketmodname[ffi/unsafe/cvector] library exports the bindings of
|
|
this section. The @racketmodname[ffi/cvector] library exports the same
|
|
bindings, except for the unsafe @racket[make-cvector*] operation.}
|
|
|
|
The @racket[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 @racket[_bytes], @racket[_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
|
|
@racket[_list] and @racket[_vector] custom types, except that
|
|
@racket[_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 @racket[type] and
|
|
@racket[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 @racket[type], initialized to the
|
|
given list of @racket[val]s.}
|
|
|
|
|
|
@defproc[(cvector? [v any/c]) boolean?]{
|
|
|
|
Returns @racket[#t] if @racket[v] is a C vector, @racket[#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 @racket[k]th element of the @racket[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 @racket[k]th element of the @racket[cvec] C vector to
|
|
@racket[val]. The @racket[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 @racket[cvec] C vector object to a list of values.}
|
|
|
|
|
|
@defproc[(list->cvector [lst list?] [type ctype?]) cvector?]{
|
|
|
|
Converts the list @racket[lst] to a C vector of the given
|
|
@racket[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 @racket[type] and @racket[length] are known.}
|
|
|
|
|