7.1.6 Byte

(require 'byte)

Some algorithms are expressed in terms of arrays of small integers. Using Scheme strings to implement these arrays is not portable vis-a-vis the correspondence between integers and characters and non-ascii character sets. These functions abstract the notion of a byte.

Function: byte-ref bytes k

k must be a valid index of bytes. byte-ref returns byte k of bytes using zero-origin indexing.

Procedure: byte-set! bytes k byte

k must be a valid index of bytes, and byte must be a small nonnegative integer. byte-set! stores byte in element k of bytes and returns an unspecified value.

Function: make-bytes k byte

Function: make-bytes k

make-bytes returns a newly allocated byte-array of length k. If byte is given, then all elements of the byte-array are initialized to byte, otherwise the contents of the byte-array are unspecified.

Function: bytes-length bytes

bytes-length returns length of byte-array bytes.

Function: bytes byte …

Returns a newly allocated byte-array composed of the small nonnegative arguments.

Function: list->bytes bytes

list->bytes returns a newly allocated byte-array formed from the small nonnegative integers in the list bytes.

Function: bytes->list bytes

bytes->list returns a newly allocated list of the bytes that make up the given byte-array.

Bytes->list and list->bytes are inverses so far as equal? is concerned.

Function: bytes->string bytes

Returns a new string formed from applying integer->char to each byte in bytes->string. Note that this may signal an error for bytes having values between 128 and 255.

Function: string->bytes string

Returns a new byte-array formed from applying char->integer to each character in string->bytes. Note that this may signal an error if an integer is larger than 255.

Function: bytes-copy bytes

Returns a newly allocated copy of the given bytes.

Function: subbytes bytes start end

bytes must be a bytes, and start and end must be exact integers satisfying

0 <= start <= end <= (bytes-length bytes).

subbytes returns a newly allocated bytes formed from the bytes of bytes beginning with index start (inclusive) and ending with index end (exclusive).

Procedure: bytes-reverse! bytes

Reverses the order of byte-array bytes.

Function: bytes-reverse bytes

Returns a newly allocated bytes-array consisting of the elements of bytes in reverse order.

Input and output of bytes should be with ports opened in binary mode (see Input/Output). Calling open-file with ’rb or ’wb modes argument will return a binary port if the Scheme implementation supports it.

Function: write-byte byte port

Function: write-byte byte

Writes the byte byte (not an external representation of the byte) to the given port and returns an unspecified value. The port argument may be omitted, in which case it defaults to the value returned by current-output-port.

Function: read-byte port

Function: read-byte

Returns the next byte available from the input port, updating the port to point to the following byte. If no more bytes are available, an end-of-file object is returned. port may be omitted, in which case it defaults to the value returned by current-input-port.

When reading and writing binary numbers with read-bytes and write-bytes, the sign of the length argument determines the endianness (order) of bytes. Positive treats them as big-endian, the first byte input or output is highest order. Negative treats them as little-endian, the first byte input or output is the lowest order.

Once read in, SLIB treats byte sequences as big-endian. The multi-byte sequences produced and used by number conversion routines see Byte/Number Conversions are always big-endian.

Function: read-bytes n port

Function: read-bytes n

read-bytes returns a newly allocated bytes-array filled with (abs n) bytes read from port. If n is positive, then the first byte read is stored at index 0; otherwise the last byte read is stored at index 0. Note that the length of the returned byte-array will be less than (abs n) if port reaches end-of-file.

port may be omitted, in which case it defaults to the value returned by current-input-port.

Function: write-bytes bytes n port

Function: write-bytes bytes n

write-bytes writes (abs n) bytes to output-port port. If n is positive, then the first byte written is index 0 of bytes; otherwise the last byte written is index 0 of bytes. write-bytes returns an unspecified value.

port may be omitted, in which case it defaults to the value returned by current-output-port.

subbytes-read! and subbytes-write provide lower-level procedures for reading and writing blocks of bytes. The relative size of start and end determines the order of writing.

Procedure: subbytes-read! bts start end port

Procedure: subbytes-read! bts start end

Fills bts with up to (abs (- start end)) bytes read from port. The first byte read is stored at index bts. subbytes-read! returns the number of bytes read.

port may be omitted, in which case it defaults to the value returned by current-input-port.

Function: subbytes-write bts start end port

Function: subbytes-write bts start end

subbytes-write writes (abs (- start end)) bytes to output-port port. The first byte written is index start of bts. subbytes-write returns the number of bytes written.

port may be omitted, in which case it defaults to the value returned by current-output-port.