This site is a static rendering of the Trac instance that was used by R7RS-WG1 for its work on R7RS-small (PDF), which was ratified in 2013. For more information, see Home. For a version of this page that may be more recent, see NumericVectorsCowan in WG2's repo for R7RS-large.

Numeric­Vectors­Cowan

cowan
2014-08-04 10:23:20
6history
source

This is a proposal for a simple numeric vector API. The conceit is that we provide what appear to be a set of specialized numeric-only vectors, but there really is only one underlying type, the bytevector. This makes it easy to see a single byte sequence in a variety of ways, not just as a homogeneous vector.

This design subsumes SRFI 4 with the exception of its type predicates. It differs from related designs such as SRFI 63, SRFI 66, and R6RS in that each procedure listed below actually represents many procedures, one for each defined representation type. This makes for a lot of procedures, but many of them can be easily inlined by even a very dumb compiler, providing high efficiency. The procedures provided are the numeric-vector analogues of the R7RS-small vector API.

Representation types

A <type> consists of a <principal type> followed by an <endianism>.

The <principal type> values are:

u8
unsigned 8-bit integer
s8
signed 8-bit integer
u16
unsigned 16-bit integer
s16
signed 16-bit integer
u32
unsigned 32-bit integer
s32
signed 32-bit integer
u64
unsigned 64-bit integer
s64
signed 64-bit integer
u128
unsigned 128-bit integer
s128
signed 128-bit integer
f32
32-bit float
f64
64-bit float
c64
64-bit complex number (two 32-bit floats, real followed by imaginary)
c128
128-bit complex number (two 64-bit floats, real followed by imaginary)

The <endianism> values are:

(empty)
Native representations (system-dependent)
le
Little-endian (for float and complex, IEEE format)
be
Big-endian (for float and complex, IEEE format)

Endianism is not applicable to the u8 and s8 types. Thus there are 3 * 14 - 4, or 38, representation types altogether.

Constructors

(make-<type>vector k [ fill ])

Returns a newly allocated bytevector of length k * b, where b is the number of bytes specified by <type>. Fill is converted to a binary value according to <type> and used to fill the bytevector; the default is implementation-defined. An error is signaled if fill cannot be accurately converted to <type>.

(<type>vector v ... )

Returns a newly allocated bytevector of length k * b, where k is the number of arguments to the procedure and b is the number of bytes specified by <type>. It is filled with the binary values resulting from encoding the v arguments according to <type>. An error is signaled if an argument cannot be accurately converted to <type>.

Predicates

There are no <type>vector? predicates, as bytevector? is sufficient.

(bytevector-empty? bytevector)

Returns #t iff bytevector has length 0. This procedure is not specialized for different numeric types.

Selectors

(<type>vector-ref bytevector k)

Returns a Scheme number corresponding to the binary value encoded according to <type> beginning at offset k * b in bytevector, where b is the number of bytes specified by <type>. This procedure treats bytevector as a uniformly typed vector.

(bytevector-<type>-ref bytevector k)

Returns a Scheme number corresponding to the binary value encoded according to <type> beginning at offset k in bytevector. This procedure treats bytevector as potentially containing more than one type.

Since bytevector-u8-ref is defined in the small language, it is excluded here.

Mutators

(<type>vector-set! bytevector k v)

Converts v to a binary value encoded according to <type> and places it into bytevector beginning at offset k * b, where b is the number of bytes specified by <type>. This procedure treats bytevector as a uniformly typed vector. An error is signaled if v cannot be accurately converted to <type>.

(bytevector-<type>-set! bytevector k v)

Converts v to a binary value encoded according to <type> and places it into bytevector beginning at offset k. This procedure treats bytevector as potentially containing more than one type. An error is signaled if v cannot be accurately converted to <type>.

Since bytevector-u8-set! is defined in the small language, it is excluded here.

Conversions

(vector-><type>vector vector [start [ end ] ])

(list-><type>vector list)

Returns a newly allocated bytevector which, when viewed as a <type>vector, has the same elements as vector or list. An error is signaled if an element of vector or list cannot be accurately converted to <type>.

(vector-><type>vector! bytevector at vector [start [ end ] ])

Writes the elements of vector from start to end into bytevector starting at at. An error is signaled if an element of vector cannot be accurately converted to <type>.

(list-><type>vector! list at)

Writes the elements of list into bytevector starting at at. An error is signaled if an element of vector or list cannot be accurately converted to <type>.

(<type>vector->vector bytevector [ start [ end ] ])

(<type>vector->list bytevector [ start [ end ] ])

Returns a newly allocated vector or list with the elements of bytevector from start to end when viewed as a <type>vector.

(<type>vector->vector! vector at bytevector [start [ end ] ])

Writes the elements of bytevector when viewed as a <type>vector from start to end into vector starting at at.

The whole numeric vector

(<type>vector-length bytevector)

Returns the length of bytevector divided by b, where b is the number of bytes specified by <type>, and rounded toward zero.

(<type>vector-copy [ [ start ] end ] )

These procedures are equivalent to calling bytevector-copy with the start and end arguments multiplied by b, where b is the number of bytes specified by <type>.

(<type>vector-copy! to at from [ [ start ] end ] )

These procedures are equivalent to calling bytevector-copy! with the start, end, and at arguments multiplied by b, where b is the number of bytes specified by <type>.

There are no <type>vector-append procedures, as bytevector-append is sufficient.

(bytevector-concat list-of-bytevector)

Returns the result of concatenating the bytevectors which are members of list-of-bytevectors. This procedure is not specialized for different numeric types.

(<type>vector-fill! bytevector fill [ [ start ] end ] )

Stores fill in the elements of bytevector viewed as a <type>vector from start to end. An error is signaled if fill cannot be accurately converted to <type>.

Mapping

(<type>vector-map proc bytevector1 bytevector2 ...)

Returns a newly allocated bytevector which, when viewed as a <type>vector, contains the results of applying proc to the elements of the bytevectors when viewed as <type>vectors.

(<type>vector-for-each proc bytevector1 bytevector2 ...)

Applies proc to the elements of the bytevectors when viewed as <type>vectors. Returns an unspecified value.

Extended numeric vector API

See the procedures of VectorsCowan, with the exceptions of the ones defined here.

Structured representation types

For mapping C structs onto bytevectors, see StructuresCowan or StructuresTaylan.