▼binaryio:   Functions for Reading and Writing Binary Data
On this page:
make-binary-reader
binary-reader?
make-binary-reader-error-handler
binary-reader-error-handler?
b-get-limit
b-at-limit?
b-at-limit/  eof?
b-push-limit
b-pop-limit
b-call/  save-limit
b-check-exhausted
b-read-bytes
b-read-bytes!
b-read-byte
b-read-integer
b-read-float
b-read-be-int
b-read-be-uint
b-read-le-int
b-read-le-uint
b-read-nul-terminated-bytes
b-read-bytes-line+  eol
b-read-bytes-line
8.12
  top  contents    up   

4 Binary Reader🔗ℹ

 (require binaryio/reader) package: binaryio-lib

Added in version 1.1 of package binaryio-lib.

procedure

(make-binary-reader in 
  [#:limit limit 
  #:error-handler error-handler]) 
 → binary-reader?
  in : input-port?
  limit : (or/c exact-nonnegative-integer? #f) = #f
  error-handler : (binary-reader-error-handler? #f) = #f
Creates a new binary reader that reads from in with an initial limit of limit bytes.

The binary reader wraps the input port with the following additional features:

  • Convenience functions for reading binary encodings of integers and floating-point numbers of different lengths, endianness, etc.

  • The error-handler hook for customizing error message. See make-binary-reader-error-handler for details.

  • Automatic handling of short reads. If in returns eof or fewer bytes than requested in a read operation on the binary reader, the error-handler is used to raise an error. Thus, for example, the caller of (b-read-bytes br len) can rely on receiving a bytestring of exactly len bytes.

  • A stack of limits, maintained with b-push-limit and b-pop-limit. On every read operation, the limits are decremented by the number of bytes read. If a read operation requests more bytes than the current limit, the error-handler is used to raise an error.

Binary readers are not thread-safe. Be careful when interleaving uses of a binary reader with direct uses of its input port. For example, direct reads from in do not count against limits imposed on the binary reader.

procedure

(binary-reader? v) → boolean?

  v : any/c
Returns #t if v is a binary reader created by make-binary-reader, #f otherwise.

procedure

(make-binary-reader-error-handler 
  [#:error error-callback 
  #:show-data? show-data?-callback]) 
 → binary-reader-error-handler?
  error-callback : (or/c #f (->* [binary-reader? symbol? string?] [] #:rest list? none/c))
   = #f
  show-data?-callback : (or/c #f (-> binary-reader? symbol? boolean?))
   = #f
Creates an error handler object for customizing the reporting of binary reader errors.

procedure

(binary-reader-error-handler? v) → boolean?

  v : any/c
Returns #t if v is an error handler object created by make-binary-reader-error-handler, #f otherwise.

procedure

(b-get-limit br) → (or/c exact-nonnegative-integer? #f)

  br : binary-reader?
Returns br’s current limit. The value #f means no limit; the idiom (or (b-get-limit br) +inf.0) may be useful for comparisons.

procedure

(b-at-limit? br) → boolean?

  br : binary-reader?
Returns #t if (b-get-limit br) is zero.

procedure

(b-at-limit/eof? br) → boolean?

  br : binary-reader?
Returns #t if (b-get-limit br) is zero or if peeking on the underlying input port returns eof.

procedure

(b-push-limit br limit) → void?

  br : binary-reader?
  limit : exact-nonnegative-integer?
Pushes a new limit on br. If the new limit is larger than the current limit, an exception is raised.

procedure

(b-pop-limit br) → void?

  br : binary-reader?
Pops the current limit from br and restores the previous limit, decremented by the number of bytes read since the current limit was pushed.

procedure

(b-call/save-limit br proc) → any

  br : binary-reader?
  proc : (-> any)
Saves the current limit stack of br and calls proc, restoring br’s limit stack when the call to proc returns normally or escapes.

Added in version 1.2 of package binaryio-lib.

procedure

(b-check-exhausted br what) → void?

  br : binary-reader?
  what : (or/c string? #f)
Raises an exception unless (b-at-limit/eof? br) is true. If what is a string, the text “after reading what” is included.

procedure

(b-read-bytes br len) → bytes?

  br : binary-reader?
  len : exact-nonnegative-integer?

procedure

(b-read-bytes! br bs [start end]) → exact-nonnegative-integer?

  br : binary-reader?
  bs : bytes?
  start : exact-nonnegative-integer? = 0
  end : exact-nonnegative-integer? = (bytes-length bs)

procedure

(b-read-byte br) → byte?

  br : binary-reader?

procedure

(b-read-integer br size signed? [big-endian?]) → exact-integer?

  br : binary-reader?
  size : exact-positive-integer?
  signed? : boolean?
  big-endian? : boolean? = #t

procedure

(b-read-float br size [big-endian?]) → real?

  br : binary-reader?
  size : (or/c 4 8)
  big-endian? : boolean? = #t
Read operations on binary readers. Note that b-read-bytes etc never return eof; if fewer bytes than requested are available before the end of input, the binary reader’s short-read handler is called to raise an exception. If br’s current limit is smaller than the number of bytes requested, br’s long-read handler is called to raise an exception.

procedure

(b-read-be-int br size) → exact-integer?

  br : binary-reader?
  size : exact-positive-integer?

procedure

(b-read-be-uint br size) → exact-nonnegative-integer?

  br : binary-reader?
  size : exact-positive-integer?

procedure

(b-read-le-int br size) → exact-integer?

  br : binary-reader?
  size : exact-positive-integer?

procedure

(b-read-le-uint br size) → exact-integer?

  br : binary-reader?
  size : exact-positive-integer?
Specialized versions of b-read-integer for reading big-endian and little-endian encodings of signed and unsigned integers, respectively.

procedure

(b-read-nul-terminated-bytes br) → bytes?

  br : binary-reader?
Reads bytes until a NUL byte is found, and returns the accumulated bytes without the NUL terminator. If no NUL terminator is found before the current limit or the end of input is reached, the binary reader’s error handler is used to raise an error.

procedure

(b-read-bytes-line+eol br eol-mode) → 
bytes? bytes?
  br : binary-reader?
  eol-mode : (or/c 'linefeed 'return 'return-linefeed 'any 'any-one)
Reades bytes until a line ending is found, as determined by eol-mode. Returns the line contents and the line ending as separate byte strings. If no line ending is found before the current limit or the end of input is reached, the binary reader’s error handler is used to raise an error.

Added in version 1.2 of package binaryio-lib.

procedure

(b-read-bytes-line br eol-mode) → bytes?

  br : binary-reader?
  eol-mode : (or/c 'linefeed 'return 'return-linefeed 'any 'any-one)
Like b-read-bytes-line+eol but does not return the line ending.

Added in version 1.2 of package binaryio-lib.

  top  contents    up