## Unit srfi-4

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

## TOC »

## CHICKEN implementation

- 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.
- 64-bit integer vectors (
`u64vector`and`s64vector`) are not supported.

### Blob conversions

`u8vector->blob``U8VECTOR`procedure`s8vector->blob``S8VECTOR`procedure`u16vector->blob``U16VECTOR`procedure`s16vector->blob``S16VECTOR`procedure`u32vector->blob``U32VECTOR`procedure`s32vector->blob``S32VECTOR`procedure`f32vector->blob``F32VECTOR`procedure`f64vector->blob``F64VECTOR`procedureEach 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.

`blob->u8vector``BLOB`procedure`blob->s8vector``BLOB`procedure`blob->u16vector``BLOB`procedure`blob->s16vector``BLOB`procedure`blob->u32vector``BLOB`procedure`blob->s32vector``BLOB`procedure`blob->f32vector``BLOB`procedure`blob->f64vector``BLOB`procedureEach 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.

### Subvectors

`subu8vector``U8VECTOR``FROM``TO`procedure`subu16vector``U16VECTOR``FROM``TO`procedure`subu32vector``U32VECTOR``FROM``TO`procedure`subs8vector``S8VECTOR``FROM``TO`procedure`subs16vector``S16VECTOR``FROM``TO`procedure`subs32vector``S32VECTOR``FROM``TO`procedure`subf32vector``F32VECTOR``FROM``TO`procedure`subf64vector``F64VECTOR``FROM``TO`procedureCreates a 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``PORT`procedureReads

`LENGTH`bytes from the`PORT`and returns a fresh`u8vector`or less if end-of-file is encountered.`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.

`read-u8vector!``LENGTH``U8VECTOR``#!optional``PORT``START`procedureReads

`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``END`procedureWrites 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^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`readThe 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

### Predicates

`u8vector?``OBJ`procedure`s8vector?``OBJ`procedure`u16vector?``OBJ`procedure`s16vector?``OBJ`procedure`u32vector?``OBJ`procedure`s32vector?``OBJ`procedure`f32vector?``OBJ`procedure`f64vector?``OBJ`procedureReturn

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

`number-vector?``OBJ`procedureReturn

`#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`,`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-f32vector N [F32VALUE NONGC FINALIZE])`procedure`(make-f64vector N [F64VALUE NONGC FINALIZE])`procedureReturn 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 but individual elements of the vector are guaranteed to be in the range of values permitted for that type of vector.

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`f32vector``F32VALUE``...`procedure`f64vector``F64VALUE``...`procedureReturn a newly-allocated SRFI-4 homogeneous number vector of the specified type, composed of the arguments.

### Length

`u8vector-length``U8VECTOR`procedure`s8vector-length``S8VECTOR`procedure`u16vector-length``U16VECTOR`procedure`s16vector-length``S16VECTOR`procedure`u32vector-length``U32VECTOR`procedure`s32vector-length``S32VECTOR`procedure`f32vector-length``F32VECTOR`procedure`f64vector-length``F64VECTOR`procedureReturns the length of the SRFI-4 homogeneous number VECTOR.

### Getters

`u8vector-ref``U8VECTOR``I`procedure`s8vector-ref``S8VECTOR``i`procedure`u16vector-ref``U16VECTOR``I`procedure`s16vector-ref``S16VECTOR``I`procedure`u32vector-ref``U32VECTOR``I`procedure`s32vector-ref``S32VECTOR``I`procedure`f32vector-ref``F32VECTOR``I`procedure`f64vector-ref``F64VECTOR``I`procedureReturn the value of the

*i*th 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``U8VALUE`procedure`s8vector-set!``S8VECTOR``I``S8VALUE`procedure`u16vector-set!``U16VECTOR``I``U16VALUE`procedure`s16vector-set!``S16VECTOR``I``S16VALUE`procedure`u32vector-set!``U32VECTOR``I``U32VALUE`procedure`s32vector-set!``S32VECTOR``I``S32VALUE`procedure`f32vector-set!``F32VECTOR``I``F32VALUE`procedure`f64vector-set!``F64VECTOR``I``F64VALUE`procedureSet 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``U8VECTOR`procedure`s8vector->list``S8VECTOR`procedure`u16vector->list``U16VECTOR`procedure`s16vector->list``S16VECTOR`procedure`u32vector->list``U32VECTOR`procedure`s32vector->list``S32VECTOR`procedure`f32vector->list``F32VECTOR`procedure`f64vector->list``F64VECTOR`procedureReturn a list consisting of the elements of SRFI-4 homogeneous number VECTOR.

`list->u8vector``U8LIST`procedure`list->s8vector``S8LIST`procedure`list->u16vector``U16LIST`procedure`list->s16vector``S16LIST`procedure`list->u32vector``U32LIST`procedure`list->s32vector``S32LIST`procedure`list->f32vector``F32LIST`procedure`list->f64vector``F64LIST`procedureReturn 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``NVECTOR`procedureRelease 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: Unit srfi-1

Next: Unit srfi-13