12.1 binary.io - Binary I/O

Module: binary.io ¶

This module provides basic procedures to perform binary I/O of numeric data. Each datum can be read from or written to a port, and got from or put to a uniform vector (see Uniform vectors). For structured binary data I/O, more convenient pack utility is implemented on top of this module (see binary.pack - Packing binary data). You might want to use this module directly if you need speed or want a flexible control of endianness.

See also Uniform vectors, which provides binary block I/O.

Endianness

Most procedures of this module take an optional endian argument, specifying the byte order of the binary input. It must be either one of symbols big-endian, little-endian, or arm-little-endian. If the endian argument is omitted, the current value of the builtin parameter default-endian is used (see Endianness). (For 8-bit I/O procedures like read-u8 the endian argument has no effect, but is accepted for consistency).

I/O using port

Function: read-u8 :optional port endian ¶

Function: read-u16 :optional port endian ¶

Function: read-u32 :optional port endian ¶

Function: read-u64 :optional port endian ¶

{binary.io} Reads 8, 16, 32 or 64 bit unsigned integer from port with specified endian, respectively. If port is omitted, current input port is used. If port reaches EOF before a complete integer is read, EOF is returned.

Function: read-s8 :optional port endian ¶

Function: read-s16 :optional port endian ¶

Function: read-s32 :optional port endian ¶

Function: read-s64 :optional port endian ¶

{binary.io} Reads 8, 16, 32 or 64 bit 2’s complement signed integer from port with specified endian, respectively. If port is omitted, current input port is used. If port reaches EOF before a complete integer is read, EOF is returned.

Function: read-uint size :optional port endian ¶

Function: read-sint size :optional port endian ¶

{binary.io} More flexible version. Reads size-octet unsigned or signed integer from port with specified endian. If port reaches EOF before a complete integer is read, EOF is returned.

Function: read-ber-integer :optional port ¶

{binary.io} Reads BER compressed integer a la X.209. A BER compressed integer is an unsigned integer in base 128, most significant digit first, where the high bit is set on all but the final (least significant) byte.

Function: write-u8 val :optional port endian ¶

Function: write-u16 val :optional port endian ¶

Function: write-u32 val :optional port endian ¶

Function: write-u64 val :optional port endian ¶

{binary.io} Writes a nonnegative integer val as 8, 16, 32 or 64 bit unsigned integer to port with specified endian, respectively. Val must be within the range of integers representable by the specified bits. When port is omitted, current output port is used.

Function: write-s8 val :optional port endian ¶

Function: write-s16 val :optional port endian ¶

Function: write-s32 val :optional port endian ¶

Function: write-s64 val :optional port endian ¶

{binary.io} Writes an integer val as 8, 16, 32 or 64 bit as 2’s complement signed integer to port with specified endian, respectively. Val must be within the range of integers representable by the specified bits. When port is omitted, current output port is used.

Function: write-uint size val :optional port endian ¶

Function: write-sint size val :optional port endian ¶

{binary.io} More flexible version. Writes an integer val as unsigned or signed integer of size bytes to port with specified endian. When port is omitted, current output port is used.

Function: write-ber-integer val :optional port ¶

{binary.io} Writes a nonnegative integer val in BER compressed integer to port. See read-ber-integer above for BER format.

Function: read-f16 :optional port endian ¶

Function: read-f32 :optional port endian ¶

Function: read-f64 :optional port endian ¶

{binary.io} Reads 16, 32, or 64-bit floating point numbers, respectively. 32bit is IEEE754 single-precision, and 64bit is IEEE754 double-precision numbers. 16-bit floating point number consists of 1-bit sign, 5-bit exponent and 10-bit mantissa, as used in some HDR image format.

If port is omitted, current input port is used. If port reaches EOF before a complete number is read, EOF is returned.

Function: write-f16 val :optional port endian ¶

Function: write-f32 val :optional port endian ¶

Function: write-f64 val :optional port endian ¶

{binary.io} Writes a real number val to port in 16, 32, or 64-bit floating point number, respectively. If port is omitted, current output port is used.

I/O using uniform vectors

In the following routines, the argument uv can be any type of uniform vector; if it is not a u8vector, it is treated as if (uvector-alias <u8vector> uv) is called—that is, it reads directly from the memory image that holds the uvector’s content. The pos argument specifies the byte position from the beginning of the memory area (it is always byte position, regardless of the uniform vector’s element size).

Function: get-u8 uv pos :optional endian ¶

Function: get-u16 uv pos :optional endian ¶

Function: get-u32 uv pos :optional endian ¶

Function: get-u64 uv pos :optional endian ¶

Function: get-s8 uv pos :optional endian ¶

Function: get-s16 uv pos :optional endian ¶

Function: get-s32 uv pos :optional endian ¶

Function: get-s64 uv pos :optional endian ¶

Function: get-f16 uv pos :optional endian ¶

Function: get-f32 uv pos :optional endian ¶

Function: get-f64 uv pos :optional endian ¶

{binary.io} Reads a number of a specific format from a uniform vector uv, starting at a byte position pos. An error is signaled if the specified position makes reference outside of the uniform vector’s content. Returns the read number.

Function: get-u16be uv pos ¶

Function: get-u16le uv pos ¶

Function: get-u32be uv pos ¶

Function: get-u32le uv pos ¶

Function: get-u64be uv pos ¶

Function: get-u64le uv pos ¶

Function: get-s16be uv pos ¶

Function: get-s16le uv pos ¶

Function: get-s32be uv pos ¶

Function: get-s32le uv pos ¶

Function: get-s64be uv pos ¶

Function: get-s64le uv pos ¶

Function: get-f16be uv pos ¶

Function: get-f16le uv pos ¶

Function: get-f32be uv pos ¶

Function: get-f32le uv pos ¶

Function: get-f64be uv pos ¶

Function: get-f64le uv pos ¶

{binary.io} These are big-endian (be) or little-endian (le) specific versions of get-* procedures. In speed-sensitive code, you might want to use these to avoid the overhead of optional-argument handling.

Function: get-uint size uv pos :optional endian ¶

Function: get-sint size uv pos :optional endian ¶

{binary.io} Read size octets from uvector uv, starting from pos-th octet, as an unsigned or signed integer, respectively.

(get-uint 3 '#u8(1 2 3 4) 1 'big-endian)
  ⇒ 131884 ; #x020304

(get-sint 3 '#u9(1 2 3 #xff) 1 'little-endian)
  ⇒ -64766 ; sign extended #xff0302

Function: put-u8! uv pos val :optional endian ¶

Function: put-u16! uv pos val :optional endian ¶

Function: put-u32! uv pos val :optional endian ¶

Function: put-u64! uv pos val :optional endian ¶

Function: put-s8! uv pos val :optional endian ¶

Function: put-s16! uv pos val :optional endian ¶

Function: put-s32! uv pos val :optional endian ¶

Function: put-s64! uv pos val :optional endian ¶

Function: put-f16! uv pos val :optional endian ¶

Function: put-f32! uv pos val :optional endian ¶

Function: put-f64! uv pos val :optional endian ¶

{binary.io} Writes a number val into a uniform vector uv in a specific format, starting at a byte position pos. An error is signaled if the specified position makes reference outside of the uniform vector’s content.

Function: put-u16be! uv pos val ¶

Function: put-u16le! uv pos val ¶

Function: put-u32be! uv pos val ¶

Function: put-u32le! uv pos val ¶

Function: put-u64be! uv pos val ¶

Function: put-u64le! uv pos val ¶

Function: put-s16be! uv pos val ¶

Function: put-s16le! uv pos val ¶

Function: put-s32be! uv pos val ¶

Function: put-s32le! uv pos val ¶

Function: put-s64be! uv pos val ¶

Function: put-s64le! uv pos val ¶

Function: put-f16be! uv pos val ¶

Function: put-f16le! uv pos val ¶

Function: put-f32be! uv pos val ¶

Function: put-f32le! uv pos val ¶

Function: put-f64be! uv pos val ¶

Function: put-f64le! uv pos val ¶

{binary.io} These are big-endian (be) or little-endian (le) specific versions of put-* procedures. In speed-sensitive code, you might want to use these to avoid the overhead of optional-argument handling.

Function: put-uint! size uv pos val :optional endian ¶

Function: put-sint! size uv pos val :optional endian ¶

{binary.io} Write an unsigned or signed integer val into an uvector uv starting from pos-th octet, for size octets, respectively.

Compatibility notes

read-u8 etc. were called read-binary-uint8 etc., and read-f32 and read-f64 were called read-binary-float and read-binary-double, respectively. These old names are still supported for the backward compatibility but their use is deprecated. The reason of the changes is for brevity and for consistency with the uniform vectors.