For Gauche 0.9.15Search (procedure/syntax/module):

Next: , Previous: , Up: Library modules - Utilities   [Contents][Index]

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.


Next: , Previous: , Up: Library modules - Utilities   [Contents][Index]


For Gauche 0.9.15Search (procedure/syntax/module):