TOC »
Module (chicken number-vector)
Homogeneous numeric vector datatypes. This module provides a superset of SRFI-4. The module srfi-4 is also available for compatibility reasons.
When loaded, the feature identifier srfi-4 is defined.
CHICKEN implementation specifics and extensions to SRFI-4
- Procedures for bytevector 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.
- Vectors for 64 and 128-bit complex numbers are provided.
This module provides 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.
And there are two datatypes of inexact complex homogeneous vectors (which will be called complex vectors):
| Datatype | Type of elements |
|---|---|
| c64vector | |
| c128vector | |
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
- #c64read
- #c128read
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
- c64vector? OBJprocedure
- c128vector? 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, f64vector, c64vector or c128vector.
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
- (make-c64vector N [C64VALUE NONGC FINALIZE])procedure
- (make-c128vector N [C128VALUE 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 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
- u64vector U64VALUE ...procedure
- s64vector S64VALUE ...procedure
- f32vector F32VALUE ...procedure
- f64vector F64VALUE ...procedure
- c64vector C64VALUE ...procedure
- c128vector C128VALUE ...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
- c64vector-length C64VECTORprocedure
- c128vector-length C128VECTORprocedure
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
- c64vector-ref C64VECTOR Iprocedure
- c128vector-ref C128VECTOR 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
- c64vector-set! C64VECTOR I C64VALUEprocedure
- c128vector-set! C128VECTOR I C128VALUEprocedure
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
- c64vector->list C64VECTORprocedure
- c128vector->list C128VECTORprocedure
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
- list->c64vector C64LISTprocedure
- list->c128vector C128LISTprocedure
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.
Blob conversions
As a number vector is basically just a bytevector wrapped into a record type, there are several procedures which can convert between bytevectors and number vectors.
Note that built-in bytevectors are identical to u8vectors.
- s8vector->bytevector S8VECTORprocedure
- u16vector->bytevector U16VECTORprocedure
- s16vector->bytevector S16VECTORprocedure
- u32vector->bytevector U32VECTORprocedure
- s32vector->bytevector S32VECTORprocedure
- u64vector->bytevector U64VECTORprocedure
- s64vector->bytevector S64VECTORprocedure
- f32vector->bytevector F32VECTORprocedure
- f64vector->bytevector F64VECTORprocedure
- c64vector->bytevector C64VECTORprocedure
- c128vector->bytevector C128VECTORprocedure
Each of these procedures return the contents of the given vector as a 'packed' bytevector. The byte order in that vector is platform-dependent (for example little-endian on an Intel processor). The /shared variants return a bytevector that shares memory with the contents of the vector, the others will copy the contents of the vector's internal bytevector object.
- bytevector->s8vector BYTEVECTORprocedure
- bytevector->u16vector BYTEVECTORprocedure
- bytevector->s16vector BYTEVECTORprocedure
- bytevector->u32vector BYTEVECTORprocedure
- bytevector->s32vector BYTEVECTORprocedure
- bytevector->u64vector BYTEVECTORprocedure
- bytevector->s64vector BYTEVECTORprocedure
- bytevector->f32vector BYTEVECTORprocedure
- bytevector->f64vector BYTEVECTORprocedure
- bytevector->c64vector BYTEVECTORprocedure
- bytevector->c128vector BYTEVECTORprocedure
Each of these procedures return a vector where the argument BYTEVECTOR 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 bytevector, the others will copy the bytevector.
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
- subc64vector C64VECTOR FROM TOprocedure
- subc128vector C128VECTOR 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.
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 (chicken type)