Chicken » Module 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 `f64vector`s preserve at least as much precision as `f32vector`s.

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

`#u8`read
`#u16`read
`#u32`read
`#s8`read
`#s16`read
`#s32`read
`#f32`read
`#f64`read

  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 `i`th 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 `i`th 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)