binaryio:   Functions for Reading and Writing Binary Data
1 Bytes
read-bytes*
write-null-terminated-bytes
read-null-terminated-bytes
2 Integers
integer->bytes
bytes->integer
integer-bytes-length
integer-bytes-length<=?
write-integer
read-integer
3 Floating-point
write-float
read-float
6.12

binaryio: Functions for Reading and Writing Binary Data

Ryan Culpepper <[email protected]>

This library provides functions for reading, writing, and converting binary data. It is designed for the use case of implementing network protocols, although this library focuses on low-level support, not high-level protocol specification.

 (require binaryio) package: binaryio-lib

This module combines the exports of binaryio/bytes, binaryio/integer, and binaryio/float.

1 Bytes

 (require binaryio/bytes) package: binaryio-lib

procedure

(read-bytes* len [in])  bytes?

  len : exact-nonnegative-integer?
  in : input-port? = (current-input-port)
Like read-bytes, but returns a byte string of exactly len bytes. If fewer than len bytes are available before the end of input, an exception is raised.

Examples:
> (define in (open-input-bytes #"abcde"))
> (read-bytes* 4 in)

#"abcd"

> (read-bytes* 2 in)

read-bytes*: unexpected end of input

  tried to read: 2 bytes

  available: 1 bytes

  received: #"e"

procedure

(write-null-terminated-bytes bstr    
  [out    
  start    
  end])  void?
  bstr : bytes?
  out : output-port? = (current-output-port)
  start : exact-nonnegative-integer? = 0
  end : exact-nonnegative-integer? = (bytes-length bstr)
Writes bytes to out from bstr from index start (inclusive) to end (exclusive), and then writes a null (0) byte terminator.

If bstr contains any null bytes between start and end, an error is raised.

procedure

(read-null-terminated-bytes [in])  bytes?

  in : input-port? = (current-input-port)
Reads from in until a null (0) byte is found, then returns the bytes read, excluding the null terminator. If no null terminator is found before the end of input, an error is raised.

Examples:
> (define-values (in out) (make-pipe))
> (write-null-terminated-bytes #"abcde" out)
> (read-null-terminated-bytes in)

#"abcde"

2 Integers

 (require binaryio/integer) package: binaryio-lib

procedure

(integer->bytes val    
  size    
  signed?    
  [big-endian?    
  dest    
  start])  bytes?
  val : exact-integer?
  size : exact-positive-integer?
  signed? : boolean?
  big-endian? : boolean? = #t
  dest : (and/c bytes? (not/c mutable?)) = (make-bytes size)
  start : exact-nonnegative-integer? = 0
Like integer->integer-bytes, except that arbitrary size arguments are supported, and big-endian? defaults to #t (network byte order) rather than the host byte order.

Examples:
> (integer->bytes -1 3 #t)

#"\377\377\377"

> (integer->bytes (expt 23 31) 18 #f)

#"\22\305U2\375\302\332\26_\5\6\235q\30~\253\6\247"

procedure

(bytes->integer bstr    
  signed?    
  [big-endian?    
  start    
  end])  exact-integer?
  bstr : bytes?
  signed? : boolean?
  big-endian? : boolean? = #t
  start : exact-nonnegative-integer? = 0
  end : exact-nonnegative-integer? = (bytes-length bstr)
Like integer-bytes->integer, except that arbitrary sizes—that is, (- end start)are supported, and big-endian? defaults to #t (network byte order) rather than the host byte order.

procedure

(integer-bytes-length val signed?)  exact-nonnegative-integer?

  val : exact-integer?
  signed? : boolean?
Returns the number of bytes needed to encode val, including the sign bit if signed? is true.

Examples:
> (integer-bytes-length 127 #t)

1

> (integer-bytes-length 128 #t)

2

procedure

(integer-bytes-length<=? val nbytes signed?)  boolean?

  val : exact-integer?
  nbytes : exact-nonnegative-integer?
  signed? : boolean?
Equivalent to (<= (integer-bytes-length val signed?) nbytes), but can be faster for small values of nbytes.

procedure

(write-integer val    
  size    
  signed?    
  [out    
  big-endian?])  void?
  val : exact-integer?
  size : exact-positive-integer?
  signed? : boolean?
  out : output-port? = (current-output-port)
  big-endian? : boolean? = #t
Writes the encoding of val to out.

Equivalent to (write-bytes (integer->bytes val size signed? big-endian?) out).

procedure

(read-integer size signed? [in big-endian?])  exact-integer?

  size : exact-positive-integer?
  signed? : boolean?
  in : input-port? = (current-input-port)
  big-endian? : boolean? = #t
Reads size bytes from in and decodes it as an integer. If fewer than size bytes are available before the end of input, an error is raised.

Equivalent to (bytes->integer (read-bytes* size in) signed? big-endian?).

3 Floating-point

 (require binaryio/float) package: binaryio-lib

procedure

(write-float val size [out big-endian?])  void?

  val : real?
  size : (or/c 4 8)
  out : output-port? = (current-output-port)
  big-endian? : boolean? = #t
Equivalent to (write-bytes (real->floating-point-bytes val size big-endian?) out).

procedure

(read-float size [in big-endian?])  real?

  size : (or/c 4 8)
  in : input-port? = (current-input-port)
  big-endian? : boolean? = #t
Equivalent to (floating-point-bytes->real (read-bytes* size in) big-endian?).