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