[[tags: manual]]

== Unit srfi-4

Homogeneous numeric vector datatypes.  Also see the [[http://srfi.schemers.org/srfi-4/srfi-4.html|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

<procedure>(u8vector->blob U8VECTOR)</procedure><br>
<procedure>(s8vector->blob S8VECTOR)</procedure><br>
<procedure>(u16vector->blob U16VECTOR)</procedure><br>
<procedure>(s16vector->blob S16VECTOR)</procedure><br>
<procedure>(u32vector->blob U32VECTOR)</procedure><br>
<procedure>(s32vector->blob S32VECTOR)</procedure><br>
<procedure>(f32vector->blob F32VECTOR)</procedure><br>
<procedure>(f64vector->blob F64VECTOR)</procedure><br>
<procedure>(u8vector->blob/shared U8VECTOR)</procedure><br>
<procedure>(s8vector->blob/shared S8VECTOR)</procedure><br>
<procedure>(u16vector->blob/shared U16VECTOR)</procedure><br>
<procedure>(s16vector->blob/shared S16VECTOR)</procedure><br>
<procedure>(u32vector->blob/shared U32VECTOR)</procedure><br>
<procedure>(s32vector->blob/shared S32VECTOR)</procedure><br>
<procedure>(f32vector->blob/shared F32VECTOR)</procedure><br>
<procedure>(f64vector->blob/shared F64VECTOR)</procedure><br>

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.

<procedure>(blob->u8vector BLOB)</procedure><br>
<procedure>(blob->s8vector BLOB)</procedure><br>
<procedure>(blob->u16vector BLOB)</procedure><br>
<procedure>(blob->s16vector BLOB)</procedure><br>
<procedure>(blob->u32vector BLOB)</procedure><br>
<procedure>(blob->s32vector BLOB)</procedure><br>
<procedure>(blob->f32vector BLOB)</procedure><br>
<procedure>(blob->f64vector BLOB)</procedure><br>
<procedure>(blob->u8vector/shared BLOB)</procedure><br>
<procedure>(blob->s8vector/shared BLOB)</procedure><br>
<procedure>(blob->u16vector/shared BLOB)</procedure><br>
<procedure>(blob->s16vector/shared BLOB)</procedure><br>
<procedure>(blob->u32vector/shared BLOB)</procedure><br>
<procedure>(blob->s32vector/shared BLOB)</procedure><br>
<procedure>(blob->f32vector/shared BLOB)</procedure><br>
<procedure>(blob->f64vector/shared BLOB)</procedure><br>

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.

=== Subvectors

<procedure>(subu8vector U8VECTOR FROM TO)</procedure><br>
<procedure>(subu16vector U16VECTOR FROM TO)</procedure><br>
<procedure>(subu32vector U32VECTOR FROM TO)</procedure><br>
<procedure>(subs8vector S8VECTOR FROM TO)</procedure><br>
<procedure>(subs16vector S16VECTOR FROM TO)</procedure><br>
<procedure>(subs32vector S32VECTOR FROM TO)</procedure><br>
<procedure>(subf32vector F32VECTOR FROM TO)</procedure><br>
<procedure>(subf64vector F64VECTOR FROM TO)</procedure><br>

Creates 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

<procedure>(read-u8vector LENGTH [PORT])</procedure>

Reads {{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.

<procedure>(read-u8vector! LENGTH U8VECTOR [PORT [START]])</procedure>

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.

<procedure>(write-u8vector U8VECTOR [PORT [START [END]]])</procedure>

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):

<table>
<tr><th>Datatype</th><th>Type of elements</th></tr>
<tr><td>{{s8vector}}</td><td>signed exact integer in the range -(2^7) to (2^7)-1</td></tr>
<tr><td>{{u8vector}}</td><td>unsigned exact integer in the range 0 to (2^8)-1</td></tr>
<tr><td>{{s16vector}}</td><td>signed exact integer in the range -(2^15) to (2^15)-1</td></tr>
<tr><td>{{u16vector}}</td><td>unsigned exact integer in the range 0 to (2^16)-1</td></tr>
<tr><td>{{s32vector}}</td><td>signed exact integer in the range -(2^31) to (2^31)-1</td></tr>
<tr><td>{{u32vector}}</td><td>unsigned exact integer in the range 0 to (2^32)-1</td></tr>
<tr><td>{{s64vector}}</td><td>signed exact integer in the range -(2^63) to (2^63)-1</td></tr>
<tr><td>{{u64vector}}</td><td>unsigned exact integer in the range 0 to (2^64)-1</td></tr></table>

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

<table>
<tr><th>Datatype</th><th>Type of elements</th></tr>
<tr><td>{{f32vector}}</td><td>inexact real</td></tr>
<tr><td>{{f64vector}}</td><td>inexact real</td></tr></table>

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

<read>#u8</read><br>
<read>#u16</read><br>
<read>#u32</read><br>
<read>#s8</read><br>
<read>#s16</read><br>
<read>#s32</read><br>
<read>#f32</read><br>
<read>#f64</read><br>

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)}}. Literal homogeneous vectors must be quoted just like heterogeneous vectors must be. 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

<procedure>(u8vector? OBJ)</procedure><br>
<procedure>(s8vector? OBJ)</procedure><br>
<procedure>(u16vector? OBJ)</procedure><br>
<procedure>(s16vector? OBJ)</procedure><br>
<procedure>(u32vector? OBJ)</procedure><br>
<procedure>(s32vector? OBJ)</procedure><br>
<procedure>(f32vector? OBJ)</procedure><br>
<procedure>(f64vector? OBJ)</procedure><br>

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

=== Constructors

<procedure>(make-u8vector N [U8VALUE NONGC FINALIZE])</procedure><br>
<procedure>(make-s8vector N [S8VALUE NONGC FINALIZE])</procedure><br>
<procedure>(make-u16vector N [U16VALUE NONGC FINALIZE])</procedure><br>
<procedure>(make-s16vector N [S16VALUE NONGC FINALIZE])</procedure><br>
<procedure>(make-u32vector N [U32VALUE NONGC FINALIZE])</procedure><br>
<procedure>(make-s32vector N [S32VALUE NONGC FINALIZE])</procedure><br>
<procedure>(make-f32vector N [F32VALUE NONGC FINALIZE])</procedure><br>
<procedure>(make-f64vector N [F64VALUE NONGC FINALIZE])</procedure><br>

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 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.

<procedure>(u8vector U8VALUE ...)</procedure><br>
<procedure>(s8vector S8VALUE ...)</procedure><br>
<procedure>(u16vector U16VALUE ...)</procedure><br>
<procedure>(s16vector S16VALUE ...)</procedure><br>
<procedure>(u32vector U32VALUE ...)</procedure><br>
<procedure>(s32vector S32VALUE ...)</procedure><br>
<procedure>(f32vector F32VALUE ...)</procedure><br>
<procedure>(f64vector F64VALUE ...)</procedure><br>

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

=== Length

<procedure>(u8vector-length U8VECTOR)</procedure><br>
<procedure>(s8vector-length S8VECTOR)</procedure><br>
<procedure>(u16vector-length U16VECTOR)</procedure><br>
<procedure>(s16vector-length S16VECTOR)</procedure><br>
<procedure>(u32vector-length U32VECTOR)</procedure><br>
<procedure>(s32vector-length S32VECTOR)</procedure><br>
<procedure>(f32vector-length F32VECTOR)</procedure><br>
<procedure>(f64vector-length F64VECTOR)</procedure><br>

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

=== Getters

<procedure>(u8vector-ref U8VECTOR I)</procedure><br>
<procedure>(s8vector-ref S8VECTOR i)</procedure><br>
<procedure>(u16vector-ref U16VECTOR I)</procedure><br>
<procedure>(s16vector-ref S16VECTOR I)</procedure><br>
<procedure>(u32vector-ref U32VECTOR I)</procedure><br>
<procedure>(s32vector-ref S32VECTOR I)</procedure><br>
<procedure>(f32vector-ref F32VECTOR I)</procedure><br>
<procedure>(f64vector-ref F64VECTOR I)</procedure><br>

Return 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

<procedure>(u8vector-set! U8VECTOR I U8VALUE)</procedure><br>
<procedure>(s8vector-set! S8VECTOR I S8VALUE)</procedure><br>
<procedure>(u16vector-set! U16VECTOR I U16VALUE)</procedure><br>
<procedure>(s16vector-set! S16VECTOR I S16VALUE)</procedure><br>
<procedure>(u32vector-set! U32VECTOR I U32VALUE)</procedure><br>
<procedure>(s32vector-set! S32VECTOR I S32VALUE)</procedure><br>
<procedure>(f32vector-set! F32VECTOR I F32VALUE)</procedure><br>
<procedure>(f64vector-set! F64VECTOR I F64VALUE)</procedure><br>

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

<procedure>(u8vector->list U8VECTOR)</procedure><br>
<procedure>(s8vector->list S8VECTOR)</procedure><br>
<procedure>(u16vector->list U16VECTOR)</procedure><br>
<procedure>(s16vector->list S16VECTOR)</procedure><br>
<procedure>(u32vector->list U32VECTOR)</procedure><br>
<procedure>(s32vector->list S32VECTOR)</procedure><br>
<procedure>(f32vector->list F32VECTOR)</procedure><br>
<procedure>(f64vector->list F64VECTOR)</procedure><br>

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

<procedure>(list->u8vector U8LIST)</procedure><br>
<procedure>(list->s8vector S8LIST)</procedure><br>
<procedure>(list->u16vector U16LIST)</procedure><br>
<procedure>(list->s16vector S16LIST)</procedure><br>
<procedure>(list->u32vector U32LIST)</procedure><br>
<procedure>(list->s32vector S32LIST)</procedure><br>
<procedure>(list->f32vector F32LIST)</procedure><br>
<procedure>(list->f64vector F64LIST)</procedure><br>

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.

---
Previous: [[Unit srfi-1]]

Next: [[Unit srfi-13]]
