Next: , Previous: Vectors, Up: Compound Data Types

#### 5.6.4 Uniform Numeric Vectors

A uniform numeric vector is a vector whose elements are all of a single numeric type. Guile offers uniform numeric vectors for signed and unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of floating point values, and complex floating-point numbers of these two sizes.

Strings could be regarded as uniform vectors of characters, See Strings. Likewise, bit vectors could be regarded as uniform vectors of bits, See Bit Vectors. Both are sufficiently different from uniform numeric vectors that the procedures described here do not apply to these two data types. However, both strings and bit vectors are generalized vectors, See Generalized Vectors, and arrays, See Arrays.

Uniform numeric vectors are the special case of one dimensional uniform numeric arrays.

Uniform numeric vectors can be useful since they consume less memory than the non-uniform, general vectors. Also, since the types they can store correspond directly to C types, it is easier to work with them efficiently on a low level. Consider image processing as an example, where you want to apply a filter to some image. While you could store the pixels of an image in a general vector and write a general convolution function, things are much more efficient with uniform vectors: the convolution function knows that all pixels are unsigned 8-bit values (say), and can use a very tight inner loop.

That is, when it is written in C. Functions for efficiently working with uniform numeric vectors from C are listed at the end of this section.

Procedures similar to the vector procedures (see Vectors) are provided for handling these uniform vectors, but they are distinct datatypes and the two cannot be inter-mixed. If you want to work primarily with uniform numeric vectors, but want to offer support for general vectors as a convenience, you can use one of the `scm_any_to_*` functions. They will coerce lists and vectors to the given type of uniform vector. Alternatively, you can write two versions of your code: one that is fast and works only with uniform numeric vectors, and one that works with any kind of vector but is slower.

One set of the procedures listed below is a generic one: it works with all types of uniform numeric vectors. In addition to that, there is a set of procedures for each type that only works with that type. Unless you really need to the generality of the first set, it is best to use the more specific functions. They might not be that much faster, but their use can serve as a kind of declaration and makes it easier to optimize later on.

The generic set of procedures uses `uniform` in its names, the specific ones use the tag from the following table.

`u8`
unsigned 8-bit integers
`s8`
signed 8-bit integers
`u16`
unsigned 16-bit integers
`s16`
signed 16-bit integers
`u32`
unsigned 32-bit integers
`s32`
signed 32-bit integers
`u64`
unsigned 64-bit integers
`s64`
signed 64-bit integers
`f32`
the C type `float`
`f64`
the C type `double`
`c32`
complex numbers in rectangular form with the real and imaginary part being a `float`
`c64`
complex numbers in rectangular form with the real and imaginary part being a `double`

The external representation (ie. read syntax) for these vectors is similar to normal Scheme vectors, but with an additional tag from the table above indiciating the vector's type. For example,

```     #u16(1 2 3)
#f64(3.1415 2.71)
```

Note that the read syntax for floating-point here conflicts with `#f` for false. In Standard Scheme one can write `(1 #f3)` for a three element list `(1 #f 3)`, but for Guile `(1 #f3)` is invalid. `(1 #f 3)` is almost certainly what one should write anyway to make the intention clear, so this is rarely a problem.

— Scheme Procedure: uniform-vector? obj
— Scheme Procedure: u8vector? obj
— Scheme Procedure: s8vector? obj
— Scheme Procedure: u16vector? obj
— Scheme Procedure: s16vector? obj
— Scheme Procedure: u32vector? obj
— Scheme Procedure: s32vector? obj
— Scheme Procedure: u64vector? obj
— Scheme Procedure: s64vector? obj
— Scheme Procedure: f32vector? obj
— Scheme Procedure: f64vector? obj
— Scheme Procedure: c32vector? obj
— Scheme Procedure: c64vector? obj
— C Function: scm_uniform_vector_p (obj)
— C Function: scm_u8vector_p (obj)
— C Function: scm_s8vector_p (obj)
— C Function: scm_u16vector_p (obj)
— C Function: scm_s16vector_p (obj)
— C Function: scm_u32vector_p (obj)
— C Function: scm_s32vector_p (obj)
— C Function: scm_u64vector_p (obj)
— C Function: scm_s64vector_p (obj)
— C Function: scm_f32vector_p (obj)
— C Function: scm_f64vector_p (obj)
— C Function: scm_c32vector_p (obj)
— C Function: scm_c64vector_p (obj)

Return `#t` if obj is a homogeneous numeric vector of the indicated type.

— Scheme Procedure: make-u8vector n [value]
— Scheme Procedure: make-s8vector n [value]
— Scheme Procedure: make-u16vector n [value]
— Scheme Procedure: make-s16vector n [value]
— Scheme Procedure: make-u32vector n [value]
— Scheme Procedure: make-s32vector n [value]
— Scheme Procedure: make-u64vector n [value]
— Scheme Procedure: make-s64vector n [value]
— Scheme Procedure: make-f32vector n [value]
— Scheme Procedure: make-f64vector n [value]
— Scheme Procedure: make-c32vector n [value]
— Scheme Procedure: make-c64vector n [value]
— C Function: scm_make_u8vector n [value]
— C Function: scm_make_s8vector n [value]
— C Function: scm_make_u16vector n [value]
— C Function: scm_make_s16vector n [value]
— C Function: scm_make_u32vector n [value]
— C Function: scm_make_s32vector n [value]
— C Function: scm_make_u64vector n [value]
— C Function: scm_make_s64vector n [value]
— C Function: scm_make_f32vector n [value]
— C Function: scm_make_f64vector n [value]
— C Function: scm_make_c32vector n [value]
— C Function: scm_make_c64vector n [value]

Return a newly allocated homogeneous numeric vector holding n elements of the indicated type. If value is given, the vector is initialized with that value, otherwise the contents are unspecified.

— Scheme Procedure: u8vector value ...
— Scheme Procedure: s8vector value ...
— Scheme Procedure: u16vector value ...
— Scheme Procedure: s16vector value ...
— Scheme Procedure: u32vector value ...
— Scheme Procedure: s32vector value ...
— Scheme Procedure: u64vector value ...
— Scheme Procedure: s64vector value ...
— Scheme Procedure: f32vector value ...
— Scheme Procedure: f64vector value ...
— Scheme Procedure: c32vector value ...
— Scheme Procedure: c64vector value ...
— C Function: scm_u8vector (values)
— C Function: scm_s8vector (values)
— C Function: scm_u16vector (values)
— C Function: scm_s16vector (values)
— C Function: scm_u32vector (values)
— C Function: scm_s32vector (values)
— C Function: scm_u64vector (values)
— C Function: scm_s64vector (values)
— C Function: scm_f32vector (values)
— C Function: scm_f64vector (values)
— C Function: scm_c32vector (values)
— C Function: scm_c64vector (values)

Return a newly allocated homogeneous numeric vector of the indicated type, holding the given parameter values. The vector length is the number of parameters given.

— Scheme Procedure: uniform-vector-length vec
— Scheme Procedure: u8vector-length vec
— Scheme Procedure: s8vector-length vec
— Scheme Procedure: u16vector-length vec
— Scheme Procedure: s16vector-length vec
— Scheme Procedure: u32vector-length vec
— Scheme Procedure: s32vector-length vec
— Scheme Procedure: u64vector-length vec
— Scheme Procedure: s64vector-length vec
— Scheme Procedure: f32vector-length vec
— Scheme Procedure: f64vector-length vec
— Scheme Procedure: c32vector-length vec
— Scheme Procedure: c64vector-length vec
— C Function: scm_uniform_vector_length (vec)
— C Function: scm_u8vector_length (vec)
— C Function: scm_s8vector_length (vec)
— C Function: scm_u16vector_length (vec)
— C Function: scm_s16vector_length (vec)
— C Function: scm_u32vector_length (vec)
— C Function: scm_s32vector_length (vec)
— C Function: scm_u64vector_length (vec)
— C Function: scm_s64vector_length (vec)
— C Function: scm_f32vector_length (vec)
— C Function: scm_f64vector_length (vec)
— C Function: scm_c32vector_length (vec)
— C Function: scm_c64vector_length (vec)

Return the number of elements in vec.

— Scheme Procedure: uniform-vector-ref vec i
— Scheme Procedure: u8vector-ref vec i
— Scheme Procedure: s8vector-ref vec i
— Scheme Procedure: u16vector-ref vec i
— Scheme Procedure: s16vector-ref vec i
— Scheme Procedure: u32vector-ref vec i
— Scheme Procedure: s32vector-ref vec i
— Scheme Procedure: u64vector-ref vec i
— Scheme Procedure: s64vector-ref vec i
— Scheme Procedure: f32vector-ref vec i
— Scheme Procedure: f64vector-ref vec i
— Scheme Procedure: c32vector-ref vec i
— Scheme Procedure: c64vector-ref vec i
— C Function: scm_uniform_vector_ref (vec i)
— C Function: scm_u8vector_ref (vec i)
— C Function: scm_s8vector_ref (vec i)
— C Function: scm_u16vector_ref (vec i)
— C Function: scm_s16vector_ref (vec i)
— C Function: scm_u32vector_ref (vec i)
— C Function: scm_s32vector_ref (vec i)
— C Function: scm_u64vector_ref (vec i)
— C Function: scm_s64vector_ref (vec i)
— C Function: scm_f32vector_ref (vec i)
— C Function: scm_f64vector_ref (vec i)
— C Function: scm_c32vector_ref (vec i)
— C Function: scm_c64vector_ref (vec i)

Return the element at index i in vec. The first element in vec is index 0.

— Scheme Procedure: uniform-vector-set! vec i value
— Scheme Procedure: u8vector-set! vec i value
— Scheme Procedure: s8vector-set! vec i value
— Scheme Procedure: u16vector-set! vec i value
— Scheme Procedure: s16vector-set! vec i value
— Scheme Procedure: u32vector-set! vec i value
— Scheme Procedure: s32vector-set! vec i value
— Scheme Procedure: u64vector-set! vec i value
— Scheme Procedure: s64vector-set! vec i value
— Scheme Procedure: f32vector-set! vec i value
— Scheme Procedure: f64vector-set! vec i value
— Scheme Procedure: c32vector-set! vec i value
— Scheme Procedure: c64vector-set! vec i value
— C Function: scm_uniform_vector_set_x (vec i value)
— C Function: scm_u8vector_set_x (vec i value)
— C Function: scm_s8vector_set_x (vec i value)
— C Function: scm_u16vector_set_x (vec i value)
— C Function: scm_s16vector_set_x (vec i value)
— C Function: scm_u32vector_set_x (vec i value)
— C Function: scm_s32vector_set_x (vec i value)
— C Function: scm_u64vector_set_x (vec i value)
— C Function: scm_s64vector_set_x (vec i value)
— C Function: scm_f32vector_set_x (vec i value)
— C Function: scm_f64vector_set_x (vec i value)
— C Function: scm_c32vector_set_x (vec i value)
— C Function: scm_c64vector_set_x (vec i value)

Set the element at index i in vec to value. The first element in vec is index 0. The return value is unspecified.

— Scheme Procedure: uniform-vector->list vec
— Scheme Procedure: u8vector->list vec
— Scheme Procedure: s8vector->list vec
— Scheme Procedure: u16vector->list vec
— Scheme Procedure: s16vector->list vec
— Scheme Procedure: u32vector->list vec
— Scheme Procedure: s32vector->list vec
— Scheme Procedure: u64vector->list vec
— Scheme Procedure: s64vector->list vec
— Scheme Procedure: f32vector->list vec
— Scheme Procedure: f64vector->list vec
— Scheme Procedure: c32vector->list vec
— Scheme Procedure: c64vector->list vec
— C Function: scm_uniform_vector_to_list (vec)
— C Function: scm_u8vector_to_list (vec)
— C Function: scm_s8vector_to_list (vec)
— C Function: scm_u16vector_to_list (vec)
— C Function: scm_s16vector_to_list (vec)
— C Function: scm_u32vector_to_list (vec)
— C Function: scm_s32vector_to_list (vec)
— C Function: scm_u64vector_to_list (vec)
— C Function: scm_s64vector_to_list (vec)
— C Function: scm_f32vector_to_list (vec)
— C Function: scm_f64vector_to_list (vec)
— C Function: scm_c32vector_to_list (vec)
— C Function: scm_c64vector_to_list (vec)

Return a newly allocated list holding all elements of vec.

— Scheme Procedure: list->u8vector lst
— Scheme Procedure: list->s8vector lst
— Scheme Procedure: list->u16vector lst
— Scheme Procedure: list->s16vector lst
— Scheme Procedure: list->u32vector lst
— Scheme Procedure: list->s32vector lst
— Scheme Procedure: list->u64vector lst
— Scheme Procedure: list->s64vector lst
— Scheme Procedure: list->f32vector lst
— Scheme Procedure: list->f64vector lst
— Scheme Procedure: list->c32vector lst
— Scheme Procedure: list->c64vector lst
— C Function: scm_list_to_u8vector (lst)
— C Function: scm_list_to_s8vector (lst)
— C Function: scm_list_to_u16vector (lst)
— C Function: scm_list_to_s16vector (lst)
— C Function: scm_list_to_u32vector (lst)
— C Function: scm_list_to_s32vector (lst)
— C Function: scm_list_to_u64vector (lst)
— C Function: scm_list_to_s64vector (lst)
— C Function: scm_list_to_f32vector (lst)
— C Function: scm_list_to_f64vector (lst)
— C Function: scm_list_to_c32vector (lst)
— C Function: scm_list_to_c64vector (lst)

Return a newly allocated homogeneous numeric vector of the indicated type, initialized with the elements of the list lst.

— Scheme Procedure: any->u8vector obj
— Scheme Procedure: any->s8vector obj
— Scheme Procedure: any->u16vector obj
— Scheme Procedure: any->s16vector obj
— Scheme Procedure: any->u32vector obj
— Scheme Procedure: any->s32vector obj
— Scheme Procedure: any->u64vector obj
— Scheme Procedure: any->s64vector obj
— Scheme Procedure: any->f32vector obj
— Scheme Procedure: any->f64vector obj
— Scheme Procedure: any->c32vector obj
— Scheme Procedure: any->c64vector obj
— C Function: scm_any_to_u8vector (obj)
— C Function: scm_any_to_s8vector (obj)
— C Function: scm_any_to_u16vector (obj)
— C Function: scm_any_to_s16vector (obj)
— C Function: scm_any_to_u32vector (obj)
— C Function: scm_any_to_s32vector (obj)
— C Function: scm_any_to_u64vector (obj)
— C Function: scm_any_to_s64vector (obj)
— C Function: scm_any_to_f32vector (obj)
— C Function: scm_any_to_f64vector (obj)
— C Function: scm_any_to_c32vector (obj)
— C Function: scm_any_to_c64vector (obj)

Return a (maybe newly allocated) uniform numeric vector of the indicated type, initialized with the elements of obj, which must be a list, a vector, or a uniform vector. When obj is already a suitable uniform numeric vector, it is returned unchanged.

— C Function: int scm_is_uniform_vector (SCM uvec)

Return non-zero when uvec is a uniform numeric vector, zero otherwise.

— C Function: SCM scm_take_u8vector (const scm_t_uint8 *data, size_t len)
— C Function: SCM scm_take_s8vector (const scm_t_int8 *data, size_t len)
— C Function: SCM scm_take_u16vector (const scm_t_uint16 *data, size_t len)
— C Function: SCM scm_take_s168vector (const scm_t_int16 *data, size_t len)
— C Function: SCM scm_take_u32vector (const scm_t_uint32 *data, size_t len)
— C Function: SCM scm_take_s328vector (const scm_t_int32 *data, size_t len)
— C Function: SCM scm_take_u64vector (const scm_t_uint64 *data, size_t len)
— C Function: SCM scm_take_s64vector (const scm_t_int64 *data, size_t len)
— C Function: SCM scm_take_f32vector (const float *data, size_t len)
— C Function: SCM scm_take_f64vector (const double *data, size_t len)
— C Function: SCM scm_take_c32vector (const float *data, size_t len)
— C Function: SCM scm_take_c64vector (const double *data, size_t len)

Return a new uniform numeric vector of the indicated type and length that uses the memory pointed to by data to store its elements. This memory will eventually be freed with `free`. The argument len specifies the number of elements in data, not its size in bytes.

The `c32` and `c64` variants take a pointer to a C array of `float`s or `double`s. The real parts of the complex numbers are at even indices in that array, the corresponding imaginary parts are at the following odd index.

— C Function: size_t scm_c_uniform_vector_length (SCM uvec)

Return the number of elements of uvec as a `size_t`.

— C Function: const void * scm_uniform_vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: const scm_t_uint8 * scm_u8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: const scm_t_int8 * scm_s8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: const scm_t_uint16 * scm_u16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: const scm_t_int16 * scm_s16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: const scm_t_uint32 * scm_u32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: const scm_t_int32 * scm_s32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: const scm_t_uint64 * scm_u64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: const scm_t_int64 * scm_s64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: const float * scm_f23vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: const double * scm_f64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: const float * scm_c32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: const double * scm_c64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)

Like `scm_vector_elements` (see Vector Accessing from C), but returns a pointer to the elements of a uniform numeric vector of the indicated kind.

— C Function: void * scm_uniform_vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: scm_t_uint8 * scm_u8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: scm_t_int8 * scm_s8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: scm_t_uint16 * scm_u16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: scm_t_int16 * scm_s16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: scm_t_uint32 * scm_u32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: scm_t_int32 * scm_s32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: scm_t_uint64 * scm_u64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: scm_t_int64 * scm_s64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: float * scm_f23vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: double * scm_f64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: float * scm_c32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
— C Function: double * scm_c64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)

Like `scm_vector_writable_elements` (see Vector Accessing from C), but returns a pointer to the elements of a uniform numeric vector of the indicated kind.

— Scheme Procedure: uniform-vector-read! uvec [port_or_fd [start [end]]]
— C Function: scm_uniform_vector_read_x (uvec, port_or_fd, start, end)

Fill the elements of uvec by reading raw bytes from port-or-fdes, using host byte order.

The optional arguments start (inclusive) and end (exclusive) allow a specified region to be read, leaving the remainder of the vector unchanged.

When port-or-fdes is a port, all specified elements of uvec are attempted to be read, potentially blocking while waiting formore input or end-of-file. When port-or-fd is an integer, a single call to read(2) is made.

An error is signalled when the last element has only been partially filled before reaching end-of-file or in the single call to read(2).

`uniform-vector-read!` returns the number of elements read.

port-or-fdes may be omitted, in which case it defaults to the value returned by `(current-input-port)`.

— Scheme Procedure: uniform-vector-write uvec [port_or_fd [start [end]]]
— C Function: scm_uniform_vector_write (uvec, port_or_fd, start, end)

Write the elements of uvec as raw bytes to port-or-fdes, in the host byte order.

The optional arguments start (inclusive) and end (exclusive) allow a specified region to be written.

When port-or-fdes is a port, all specified elements of uvec are attempted to be written, potentially blocking while waiting for more room. When port-or-fd is an integer, a single call to write(2) is made.

An error is signalled when the last element has only been partially written in the single call to write(2).

The number of objects actually written is returned. port-or-fdes may be omitted, in which case it defaults to the value returned by `(current-output-port)`.