Bytes
This library provides primitives for operating on u8vectors as well as some utility functions.
To use the bindings from this module:
(import :std/misc/bytes)
endianness
(endianness big|little|native) -> endianness symbol
(def big 'big)
(def little 'little)
(def native 'native)
(def native-endianness ...)
Specifies the endianness for integer and floating point operations on u8vectors.
The supported endianness can be big, little, or native; native-endianness is bound
at runtime to the native architecture endianness.
u8vector-s8-ref
(u8vector-s8-ref v i) -> int
v := u8vector
i := integer; offset index in v
Retrieves the signed byte from v in position i, decoding from a 2's complement representation.
u8vector-s8-set!
(u8vector-s8-set! v i n) -> unspecified
v := u8vector
i := integer; offset index in v
n := signed byte
Sets the signed byte in v at position i from the value n, encoding to 2's complement representation.
u8vector-uint-ref
(u8vector-uint-ref v i endianness size) -> exact nonnegative integer
v := u8vector
i := integer; offset index in v
endianness := endianness symbol; the endianness of the binary representation of the integer
size := integer; the size of the integer in bytes
Retrieves an unsigned integer from its binary representation from v, starting at index i.
u8vector-uint-set!
(u8vector-uint-set! v i n endianness size) -> unspecified
v := u8vector
i := integer; offset index in v
n := exact nonnegative integer; the value to set
endianness := endianness symbol; the endianness of the binary representation of the integer
size := integer; the size of the integer in bytes
Encodes the unsigned integer n in its binary representation in v, starting at offset i.
u8vector-sint-ref
(u8vector-sint-ref v i endianness size) -> exact integer
v := u8vector
i := integer; offset index in v
endianness := endianness symbol; the endianness of the binary representation of the integer
size := integer; the size of the integer in bytes
Retrieves a signed integer from its binary representation from v, starting at index i.
u8vector-sint-set!
(u8vector-sint-set! v i n endianness size) -> unspecified
v := u8vector
i := integer; offset index in v
n := exact integer; the value to set
endianness := endianness symbol; the endianness of the binary representation of the integer
size := integer; the size of the integer in bytes
Encodes the signed integer n in its binary representation in v, starting at offset i.
u8vector->uint-list
(u8vector->uint-list v endianness size) -> list of exact nonnegative integers
v := u8vector
endianness := endianness symbol; the endianness of the binary representation of each integer
size := integer; the size of each integer in bytes
Decodes a u8vector v into a list of exact nonnegative integers.
uint-list->u8vector
(uint-list->u8vector lst endianness size) -> u8vcetor
lst := list of exact nonnegative integers
endianness := endianness symbol; the endianness of the binary representation of each integer
size := integer; the size of each integer in bytes
Encodes a list of unsigned integers to a u8vector.
u8vector->sint-list
(u8vector->sint-list v endianness size) -> list of exact integers
v := u8vector
endianness := endianness symbol; the endianness of the binary representation of each integer
size := integer; the size of each integer in bytes
Decodes a u8vector v into a list of exact integers.
sint-list->u8vector
(uint-list->u8vector lst endianness size) -> u8vector
lst := list of exact integers
endianness := endianness symbol; the endianness of the binary representation of each integer
size := integer; the size of each integer in bytes
Encodes a list of signed integers to a u8vector.
Operations on Machine-size Integers
(u8vector-u16-ref v i endianness) -> u16
(u8vector-u16-native-ref v i) -> u16
(u8vector-u16-ref-set! v i n endianness) -> unspecified
(u8vector-u16-native-set! v i n) -> unspecified
(u8vector-s16-ref v i endianness) -> s16
(u8vector-s16-native-ref v i) -> s16
(u8vector-s16-ref-set! v i n endianness) -> unspecified
(u8vector-s16-native-set! v i n) -> unspecified
(u8vector-u32-ref v i endianness) -> u32
(u8vector-u32-native-ref v i) -> u32
(u8vector-u32-ref-set! v i n endianness) -> unspecified
(u8vector-u32-native-set! v i n) -> unspecified
(u8vector-s32-ref v i endianness) -> s32
(u8vector-s32-native-ref v i) -> s32
(u8vector-s32-ref-set! v i n endianness) -> unspecified
(u8vector-s32-native-set! v i n) -> unspecified
(u8vector-u64-ref v i endianness) -> u64
(u8vector-u64-native-ref v i) -> u64
(u8vector-u64-ref-set! v i n endianness) -> unspecified
(u8vector-u64-native-set! v i n) -> unspecified
(u8vector-s64-ref v i endianness) -> s64
(u8vector-s64-native-ref v i) -> s64
(u8vector-s64-ref-set! v i n endianness) -> unspecified
(u8vector-s64-native-set! v i n) -> unspecified
Operations for encoding and decoding machine-sized integers. When the endianness matches the native endianness, then a faster native implementation is used.
Operations on Floating Point Numbers
(u8vector-float-ref v i endianness) -> flonum
(u8vector-float-native-ref v i) -> flonum
(u8vector-float-set! v i x endianness) -> unspecified
(u8vector-float-native-set! v i x) -> unspecified
(u8vector-double-ref v i endianness) -> flonum
(u8vector-double-native-ref v i) -> flonum
(u8vector-double-set! v i x endianness) -> unspecified
(u8vector-double-native-set! v i x) -> unspecified
Operations for encoding and decoding floating point numbers using the IEEE-754 representation.
u8vector-swap!
(u8vector-swap! v i j) -> unspecified
v := u8vector
i := integer element position
j := integer element position
Swaps elements i and j of u8vector v.
Examples:
> (def u (u8vector 1 2))
> (u8vector-swap! u 0 1)
> u
#u8(2 1)
u8vector-reverse!
(u8vector-reverse! v) -> void
v := u8vector
Reverses the elements of u8vector v in-place. Mutates the vector.
Examples:
> (def u (u8vector 1 2 3 4 5))
> (u8vector-reverse! u)
> u
#u8(5 4 3 2 1)
u8vector-reverse
(u8vector-reverse v) -> u8vector
v := u8vector
Reverses the elements of u8vector v. Produces a new u8vector.
Examples:
> (def u (u8vector 1 2 3 4 5))
> (u8vector-reverse u)
#u8(5 4 3 2 1)
u8vector->bytestring
(u8vector->bytestring v (delim #\space)) -> bytestring
v := u8vector
delim := char
Constructs a string of bytes in hexadecimal from u8vector v.
Each byte is formatted as two uppercase hex characters
and separated using the specified delimiter character; the delimiter can
be #f to specify simple concatenation.
Examples:
> (u8vector->bytestring (u8vector 255 127 11 1 0))
"FF 7F 0B 01 00"
> (displayln (u8vector->bytestring (u8vector 255 127 11 1 0)))
FF 7F 0B 01 00
> (u8vector->bytestring (u8vector 1 2 3) #f)
"010203"
bytestring->u8vector
(bytestring->u8vector bs (delim #\space)) -> u8vector
bs := bytestring
delim := char
Constructs a u8vector from bytestring bs.
This function expects a string of bytes delimited by delim, which can be #f to indicate
no delimiter. Each byte consists of two hexadecimal characters.
Examples:
> (bytestring->u8vector "FF AB 00")
#u8(255 171 0)
> (u8vector->bytestring (bytestring->u8vector "FF AB 00"))
"FF AB 00"
> (string->bytes "FF AB 00")
#u8(70 70 32 65 66 32 48 48)
u8vector->uint
(u8vector->uint v (endianness big)) -> uint
v := u8vector
endianness := endianness symbol
Decodes a u8vector as an unsigned integer.
uint->u8vector
(uint->u8vector n (endianness big)) -> u8vector
n := exact nonnegative integer
endianness := endianness symbol
Encodes an unsigned integer to its binary representation.
Examples:
> (u8vector->uint #u8(0 1))
1
> (u8vector->uint (make-u8vector 2 #xFF))
65535
> (u8vector->uint (make-u8vector 8 #xFF))
18446744073709551615
> (equal? (- (expt 2 64) 1) (u8vector->uint (make-u8vector 8 #xFF)))
#t
Aliases
The following aliases are defined, using the canonical Scheme naming of u8vectors as bytevectors.
(defalias bytevector-u8-ref u8vector-ref)
(defalias bytevector-u8-set! u8vector-set!)
(defalias bytevector-s8-ref u8vector-s8-ref)
(defalias bytevector-s8-set! u8vector-s8-set!)
(defalias bytevector-uint-ref u8vector-uint-ref)
(defalias bytevector-uint-set! u8vector-uint-set!)
(defalias bytevector-sint-ref u8vector-sint-ref)
(defalias bytevector-sint-set! u8vector-sint-set!)
(defalias bytevector->uint-list u8vector->uint-list)
(defalias bytevector->sint-list u8vector->sint-list)
(defalias uint-list->bytevector uint-list->u8vector)
(defalias sint-list->bytevector sint-list->u8vector)
(defalias bytevector-u16-ref u8vector-u16-ref)
(defalias bytevector-u16-native-ref u8vector-u16-native-ref)
(defalias bytevector-u16-set! u8vector-u16-set!)
(defalias bytevector-u16-native-set! u8vector-u16-native-set!)
(defalias bytevector-s16-ref u8vector-s16-ref)
(defalias bytevector-s16-native-ref u8vector-s16-native-ref)
(defalias bytevector-s16-set! u8vector-s16-set!)
(defalias bytevector-s16-native-set! u8vector-s16-native-set!)
(defalias bytevector-u32-ref u8vector-u32-ref)
(defalias bytevector-u32-native-ref u8vector-u32-native-ref)
(defalias bytevector-u32-set! u8vector-u32-set!)
(defalias bytevector-u32-native-set! u8vector-u32-native-set!)
(defalias bytevector-s32-ref u8vector-s32-ref)
(defalias bytevector-s32-native-ref u8vector-s32-native-ref)
(defalias bytevector-s32-set! u8vector-s32-set!)
(defalias bytevector-s32-native-set! u8vector-s32-native-set!)
(defalias bytevector-u64-ref u8vector-u64-ref)
(defalias bytevector-u64-native-ref u8vector-u64-native-ref)
(defalias bytevector-u64-set! u8vector-u64-set!)
(defalias bytevector-u64-native-set! u8vector-u64-native-set!)
(defalias bytevector-s64-ref u8vector-s64-ref)
(defalias bytevector-s64-native-ref u8vector-s64-native-ref)
(defalias bytevector-s64-set! u8vector-s64-set!)
(defalias bytevector-s64-native-set! u8vector-s64-native-set!)
(defalias bytevector-ieee-single-ref u8vector-float-ref)
(defalias bytevector-ieee-single-set! u8vector-float-set!)
(defalias bytevector-ieee-single-native-ref u8vector-float-native-ref)
(defalias bytevector-ieee-single-native-set! u8vector-float-native-set!)
(defalias bytevector-ieee-double-ref u8vector-double-ref)
(defalias bytevector-ieee-double-set! u8vector-double-set!)
(defalias bytevector-ieee-double-native-ref u8vector-double-native-ref)
(defalias bytevector-ieee-double-native-set! u8vector-double-native-set!)
(defalias bytevector-swap! u8vector-swap!)
(defalias bytevector-reverse! u8vector-reverse!)
(defalias bytevector-reverse u8vector-reverse)
(defalias bytevector->bytestring u8vector->bytestring)
(defalias bytestring->bytevector bytestring->u8vector)
(defalias bytevector->uint u8vector->uint)
(defalias uint->bytevector uint->u8vector)
Low Level Unsafe Operations
The following low level unsafe operations are also exported.
(&u8vector-s8-ref v i) -> s8
(&u8vector-s8-set! v i n) -> unspecified
(&u8vector-uint-ref/be v i size) -> uint
(&u8vector-uint-ref/le v i size) -> uint
(&u8vector-uint-set!/be v i n size) -> unspecified
(&u8vector-uint-set!/le v i n size) -> unspecified
(&u8vector-sint-ref/be v i size) -> sint
(&u8vector-sint-ref/le v i size) -> sint
(&u8vector-sint-set!/be v i n size) -> unspecified
(&u8vector-sint-set!/le v i n size) -> unspecified
(&u8vector-u16-ref/native v i) -> u16
(&u8vector-u16-set!/native v i n) -> unspecified
(&u8vector-s16-ref/native v i) -> s16
(&u8vector-s16-set!/native v i n) -> unspecified
(&u8vector-u32-ref/native v i) -> u32
(&u8vector-u32-set!/native v i n) -> unspecified
(&u8vector-s32-ref/native v i) -> s32
(&u8vector-s32-set!/native v i n) -> unspecified
(&u8vector-u64-ref/native v i) -> u64
(&u8vector-u64-set!/native v i n) -> unspecified
(&u8vector-s64-ref/native v i) -> s64
(&u8vector-s64-set!/native v i n) -> unspecified
(&u8vector-float-ref/native v i) -> flonum
(&u8vector-float-set!/native v i x) -> unspecified
(&u8vector-double-ref/native v i) -> flonum
(&u8vector-double-set!/native v i x) -> unspecified
(&u8vector-swap! v i j) -> unspecified