Blob­API

This is a proposal for a WG2 bytevector API. The conceit is that everything is a separate procedure with minimal arguments; this makes for a lot of procedures, but each one can be easily inlined by even a very dumb compiler, providing high efficiency.

Numeric procedures

(bytevector-<type>-ref bytevector n)

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

(<type>vector-ref bytevector n)

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

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

Converts v to a binary value encoded according to type and places it into bytevector beginning at offset n. This procedure treats bytevector as potentially containing more than one type.

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

Converts v to a binary value encoded according to type and places it into bytevector beginning at offset n * b, where b is the size of the binary value in bytes. This procedure treats bytevector as a uniformly typed vector.

(<type>vector-length bytevector)

Returns a Scheme number corresponding to the length of bytevectordivided by the size of the binary value in bytes.

(vector-><type>vector vector)

Returns a vector with the same elements as <type>vector.

(<type>vector->vector <type>vector)

Returns a <type>vector with the same elements as vector. It is an error if an element cannot be accurately converted to <type>.

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

String procedures

(bytevector-<encoding>-ref bytevector n l)

Returns a Scheme string corresponding to the binary value encoded according to encoding beginning at offset n in bytevector and continuing for l bytes.

(bytevector-<encoding>-set! blob n v)

Converts v to a binary string encoded according to encoding and places it into bytevector beginning at offset n. Returns the number of bytes encoded.

String encodings

utf8

UTF-8 encoding

utf16

UTF-16 encoding (respects BOM if present, defaults to native encoding otherwise)

utf16be

UTF-16BE encoding (treats BOM as a normal character)

utf16le

UTF-16LE encoding (treats BOM as a normal character)

Equality, map, for-each, fold, unfold

TBD