chickadee » srfi-4

Module srfi-4

Homogeneous numeric vector datatypes. Also see the original SRFI-4 document.

When loaded, the feature identifier srfi-4 is defined.

CHICKEN implementation specifics and extensions

• Procedures for blob conversion, subvectors and vector I/O are provided.
• SRFI-17 setters for XXXvector-ref are defined.
• Constructors allow allocating the storage in non garbage collected memory.

Blob conversions

As a SRFI-4 vector is basically just a blob wrapped by a SRFI-4 type "header object" to structure its contents, there are several procedures which can convert between blobs and SRFI-4 vectors.

u8vector->blob U8VECTORprocedure

s8vector->blob S8VECTORprocedure

u16vector->blob U16VECTORprocedure

s16vector->blob S16VECTORprocedure

u32vector->blob U32VECTORprocedure

s32vector->blob S32VECTORprocedure

u64vector->blob U64VECTORprocedure

s64vector->blob S64VECTORprocedure

f32vector->blob F32VECTORprocedure

f64vector->blob F64VECTORprocedure

u8vector->blob/shared U8VECTORprocedure

s8vector->blob/shared S8VECTORprocedure

u16vector->blob/shared U16VECTORprocedure

s16vector->blob/shared S16VECTORprocedure

u32vector->blob/shared U32VECTORprocedure

s32vector->blob/shared S32VECTORprocedure

u64vector->blob/shared U64VECTORprocedure

s64vector->blob/shared S64VECTORprocedure

f32vector->blob/shared F32VECTORprocedure

f64vector->blob/shared F64VECTORprocedure

Each of these procedures return the contents of the given vector as a 'packed' blob. The byte order in that vector is platform-dependent (for example little-endian on an Intel processor). The /shared variants return a blob that shares memory with the contents of the vector, the others will copy the contents of the SRFI-4 vector's internal blob object.

blob->u8vector BLOBprocedure

blob->s8vector BLOBprocedure

blob->u16vector BLOBprocedure

blob->s16vector BLOBprocedure

blob->u32vector BLOBprocedure

blob->s32vector BLOBprocedure

blob->u64vector BLOBprocedure

blob->s64vector BLOBprocedure

blob->f32vector BLOBprocedure

blob->f64vector BLOBprocedure

blob->u8vector/shared BLOBprocedure

blob->s8vector/shared BLOBprocedure

blob->u16vector/shared BLOBprocedure

blob->s16vector/shared BLOBprocedure

blob->u32vector/shared BLOBprocedure

blob->s32vector/shared BLOBprocedure

blob->u64vector/shared BLOBprocedure

blob->s64vector/shared BLOBprocedure

blob->f32vector/shared BLOBprocedure

blob->f64vector/shared BLOBprocedure

Each of these procedures return a vector where the argument BLOB is taken as a 'packed' representation of the contents of the vector. The /shared variants return a vector that shares memory with the contents of the blob, the others will copy the blob.

Subvectors

subu8vector U8VECTOR FROM TOprocedure

subu16vector U16VECTOR FROM TOprocedure

subu32vector U32VECTOR FROM TOprocedure

subu64vector U32VECTOR FROM TOprocedure

subs8vector S8VECTOR FROM TOprocedure

subs16vector S16VECTOR FROM TOprocedure

subs32vector S32VECTOR FROM TOprocedure

subs64vector S32VECTOR FROM TOprocedure

subf32vector F32VECTOR FROM TOprocedure

subf64vector F64VECTOR FROM TOprocedure

Creates a fresh number vector of the same type as the argument vector with the elements at the positions FROM up to but not including TO.

Vector I/O

read-u8vector #!optional LENGTH PORTprocedure

Reads LENGTH bytes from the PORT and returns a fresh u8vector, or as many as are available before end-of-file is encountered. PORT defaults to the value of (current-input-port). If no bytes are available before the end-of-file, #!eof is returned.

If LENGTH is #f, the vector will be filled completely until end-of-file is reached.

read-u8vector! LENGTH U8VECTOR #!optional PORT STARTprocedure

Reads LENGTH bytes from the PORT writing the read input into U8VECTOR beginning at START (or 0 if not given). PORT defaults to the value of (current-input-port).

If LENGTH is #f, the vector will be filled completely until end-of-file is reached. This procedure returns the number of bytes read.

write-u8vector U8VECTOR #!optional PORT START ENDprocedure

Writes the bytes U8VECTOR between the indices START (inclusive) and END (exclusive) to PORT.

PORT defaults to the value of (current-output-port).

SRFI-4 specification

SRFI-4 describes a set of datatypes for vectors whose elements are of the same numeric type (signed or unsigned exact integer or inexact real of a given precision). These datatypes support operations analogous to the Scheme vector type, but they are distinct datatypes. An external representation is specified which must be supported by the read and write procedures and by the program parser (i.e. programs can contain references to literal homogeneous vectors).

Datatypes

There are 8 datatypes of exact integer homogeneous vectors (which will be called integer vectors):

Datatype	Type of elements
s8vector	signed exact integer in the range -(2^7) to (2^7)-1
u8vector	unsigned exact integer in the range 0 to (2^8)-1
s16vector	signed exact integer in the range -(2^15) to (2^15)-1
u16vector	unsigned exact integer in the range 0 to (2^16)-1
s32vector	signed exact integer in the range -(2^31) to (2^31)-1
u32vector	unsigned exact integer in the range 0 to (2^32)-1
s64vector	signed exact integer in the range -(2^31) to (2^31)-1
u64vector	unsigned exact integer in the range 0 to (2^64)-1
s64vector	signed exact integer in the range -(2^63) to (2^63)-1
u64vector	unsigned exact integer in the range 0 to (2^64)-1

There are 2 datatypes of inexact real homogeneous vectors (which will be called float vectors):

Datatype	Type of elements
f32vector	inexact real
f64vector	inexact real

The only difference between the two float vector types is that f64vectors preserve at least as much precision as f32vectors.

Each homogeneous vector datatype has an external representation which is supported by the read and write procedures and by the program parser. Each datatype also has a set of associated predefined procedures analogous to those available for Scheme's heterogeneous vectors.

External representation

#u8read

#u16read

#u32read

#s8read

#s16read

#s32read

#f32read

#f64read

The external representation of instances of the datatype XXXvector is #XXX( ...elements... ).

For example,

#u8(0 #e1e2 #xff)  ; a u8vector of length 3 containing 0, 100, 255
#f64(-1.5)         ; a f64vector of length 1 containing -1.5.

This external representation is also available in program source code. For example,

(set! x '#u8(1 2 3))

will set x to the object #u8(1 2 3). Since CHICKEN 4.9.0, literal homogeneous vectors do not have to be quoted. Homogeneous vectors can appear in quasiquotations but must not contain unquote or unquote-splicing forms. I.e.,

`(,x #u8(1 2))        ; legal
`#u8(1 ,x 2)          ; illegal

Elements may also be characters or strings, in that case they are interpreted as a sequence of numerical character codes. For example,

'#u8(#\x7f "EL" #\F 2 1)

is equivalent to

'#u8(#\x7f #\x45 #\x4c #\x46 2 1)

Character literals inside numeric vectors expand into the UTF-8 sequence of the characters they represent, for strings the contained characters are interpreted in whatever encoding is used for the text file or stream in which the literal appears.

Note that #u8"..." can be used as an abbreviation for the special case #u8("...").

Predicates

u8vector? OBJprocedure

s8vector? OBJprocedure

u16vector? OBJprocedure

s16vector? OBJprocedure

u32vector? OBJprocedure

s32vector? OBJprocedure

u64vector? OBJprocedure

s64vector? OBJprocedure

f32vector? OBJprocedure

f64vector? OBJprocedure

Return #t if obj is an object of the specified type or #f if not.

number-vector? OBJprocedure

Return #t if obj is a number vector, #f if not. A "number vector" is any of the homogeneous number vector types defined by SRFI-4, ie it's one of u8vector, s8vector, u16vector, s16vector, u32vector, s32vector, u64vector, s64vector, f32vector or f64vector).

Constructors

(make-u8vector N [U8VALUE NONGC FINALIZE])procedure

(make-s8vector N [S8VALUE NONGC FINALIZE])procedure

(make-u16vector N [U16VALUE NONGC FINALIZE])procedure

(make-s16vector N [S16VALUE NONGC FINALIZE])procedure

(make-u32vector N [U32VALUE NONGC FINALIZE])procedure

(make-s32vector N [S32VALUE NONGC FINALIZE])procedure

(make-u64vector N [U64VALUE NONGC FINALIZE])procedure

(make-s64vector N [S64VALUE NONGC FINALIZE])procedure

(make-f32vector N [F32VALUE NONGC FINALIZE])procedure

(make-f64vector N [F64VALUE NONGC FINALIZE])procedure

Return a newly-allocated SRFI-4 homogeneous number vector of length N.

If the optional fill VALUE is specified, it specifies the initial value for each slot in the vector. If not, the content of the vector is unspecified as the underlying memory is uninitialized. Particularly this means that entries in f32vector or f64vector may be i.e. a NaN-value.

The type of the fill value must be compatible with the elements of the vector datatype. It is an error if otherwise -- for example, if an inexact integer is passed to make-u8vector.

On CHICKEN, these procedures have been extended to allow allocating the storage in non-garbage collected memory, as follows:

The optional arguments NONGC and FINALIZE define whether the vector should be allocated in a memory area not subject to garbage collection and whether the associated storage should be automatically freed (using finalization) when there are no references from Scheme variables and data. NONGC defaults to #f (the vector will be located in normal garbage collected memory) and FINALIZE defaults to #t. Note that the FINALIZE argument is only used when NONGC is true.

u8vector U8VALUE ...procedure

s8vector S8VALUE ...procedure

u16vector U16VALUE ...procedure

s16vector S16VALUE ...procedure

u32vector U32VALUE ...procedure

s32vector S32VALUE ...procedure

u64vector U64VALUE ...procedure

s64vector S64VALUE ...procedure

f32vector F32VALUE ...procedure

f64vector F64VALUE ...procedure

Return a newly-allocated SRFI-4 homogeneous number vector of the specified type, composed of the arguments.

Length

u8vector-length U8VECTORprocedure

s8vector-length S8VECTORprocedure

u16vector-length U16VECTORprocedure

s16vector-length S16VECTORprocedure

u32vector-length U32VECTORprocedure

s32vector-length S32VECTORprocedure

u64vector-length U64VECTORprocedure

s64vector-length S64VECTORprocedure

f32vector-length F32VECTORprocedure

f64vector-length F64VECTORprocedure

Returns the length of the SRFI-4 homogeneous number VECTOR.

Getters

u8vector-ref U8VECTOR Iprocedure

s8vector-ref S8VECTOR iprocedure

u16vector-ref U16VECTOR Iprocedure

s16vector-ref S16VECTOR Iprocedure

u32vector-ref U32VECTOR Iprocedure

s32vector-ref S32VECTOR Iprocedure

u64vector-ref U64VECTOR Iprocedure

s64vector-ref S64VECTOR Iprocedure

f32vector-ref F32VECTOR Iprocedure

f64vector-ref F64VECTOR Iprocedure

Return the value of the ith element of the SRFI-4 homogeneous number vector, where I is a nonnegative exact integer less than the length of the vector.

Setters

u8vector-set! U8VECTOR I U8VALUEprocedure

s8vector-set! S8VECTOR I S8VALUEprocedure

u16vector-set! U16VECTOR I U16VALUEprocedure

s16vector-set! S16VECTOR I S16VALUEprocedure

u32vector-set! U32VECTOR I U32VALUEprocedure

s32vector-set! S32VECTOR I S32VALUEprocedure

u64vector-set! U64VECTOR I U64VALUEprocedure

s64vector-set! S64VECTOR I S64VALUEprocedure

f32vector-set! F32VECTOR I F32VALUEprocedure

f64vector-set! F64VECTOR I F64VALUEprocedure

Set the ith element of the SRFI-4 homogeneous number VECTOR to VALUE. I is a nonnegative exact integer less than the length of the vector and VALUE must be the same type as the elements of the vector datatype.

Additionally, SRFI-17 setters are defined on all xxxvector-ref procedures. For example, to set the ith element of SRFI-4 u8vector to u8value:

(set! (u8vector-ref u8vector i) u8value)

Conversions

u8vector->list U8VECTORprocedure

s8vector->list S8VECTORprocedure

u16vector->list U16VECTORprocedure

s16vector->list S16VECTORprocedure

u32vector->list U32VECTORprocedure

s32vector->list S32VECTORprocedure

u64vector->list U64VECTORprocedure

s64vector->list S64VECTORprocedure

f32vector->list F32VECTORprocedure

f64vector->list F64VECTORprocedure

Return a list consisting of the elements of SRFI-4 homogeneous number VECTOR.

list->u8vector U8LISTprocedure

list->s8vector S8LISTprocedure

list->u16vector U16LISTprocedure

list->s16vector S16LISTprocedure

list->u32vector U32LISTprocedure

list->s32vector S32LISTprocedure

list->u64vector U64LISTprocedure

list->s64vector S64LISTprocedure

list->f32vector F32LISTprocedure

list->f64vector F64LISTprocedure

Return a newly-allocated SRFI-4 homogeneous number VECTOR consisting of the elements of LIST. Each element of LIST must be compatible with the datatype of VECTOR.

Release number vectors allocated in static memory

release-number-vector NVECTORprocedure

Release the storage of a SRFI-4 vector that was allocated in non-garbage collected memory (for example using the NONGC argument for one of the make-XXXvector constructor procedures). The effect of calling this procedure with a number vector allocated in normal garbage collected memory is undefined.

---

Previous: Module r4rs

Next: Module (chicken base)