Module Data_encoding.Binary

All the errors that might be returned while reading a binary value

Read_error e is an exception wrapping the read_error e. It is used only by function suffixed by _exn where the suffix-less function would have returned Error e.

All the errors that might be returned while writing a binary value

Compute the expected length of the binary representation of a value.

• raises Write_error

  in case some size/length invariants are broken.

Returns the size of the binary representation that the given encoding might produce, only when this size does not depends of the value itself.

E.g., fixed_length (tup2 int64 (Fixed.string 2)) is Some _

E.g., fixed_length (result int64 (Fixed.string 2)) is None

E.g., fixed_length (list (tup2 int64 (Fixed.string 2))) is None

Returns the maximum size of the binary representation that the given encoding might produce, only when this maximum size does not depends of the value itself.

E.g., maximum_length (tup2 int64 (Fixed.string 2)) is Some _

E.g., maximum_length (result int64 (Fixed.string 2)) is Some _

E.g., maximum_length (list (tup2 int64 (Fixed.string 2))) is None

Note that the function assumes that recursive encodings (build using mu) are used for recursive data types. As a result, maximum_length will return None if given a recursive encoding.

If there are static guarantees about the maximum size of the representation for values of a given type, you can wrap your encoding in check_size. This will cause maximum_length to return Some _.

read enc buf ofs len tries to reconstruct a value from the bytes in buf starting at offset ofs and reading at most len bytes. This function also returns the offset of the first unread bytes in the buf.

The function will fail (returning Error _) if

• the bytes in buf designated by ofs and len are not compatible with the encoding enc (e.g., an integer is out the range specified in the encoding, or a union's tag is not recognised),
• it needs to read more than len bytes to decode the value,
• a user-provided function (such as that of a conv or delayed) raises an exception,
• etc. In which case the returned error contains minimal diagnosis information about the discrepancy between the bytes and the encoding.

Other reading functions (of_string, of_bytes) may fail for the same reasons.

The returned value contains no pointer back to buf (as a whole or as sub-strings), even in the case where the encoding is or includes Fixed.string or Fixed.bytes.

read_opt is like read but in case of failure, the error is ignored and None is returned instead.

read_exn is like read but in case of failure, the error is wrapped in Read_error which is raised.

Return type for the function read_stream.

Streamed equivalent of read.

• raises [Invalid_argument]

  if called with a variable-size encoding.

  read_stream e is Await k and you can use k to feed the first bytes to be decoded.

  If you feed invalid bytes (i.e., bytes that do not match e) to k, it returns Error.

  If you feed bytes that form a valid strict prefix for e, then it returns Await k, and you can use k to feed it more bytes.

  If you feed it sufficient bytes to decode a whole value described by e, then it returns Success s where s.result is the decoded value, s.size is the number of bytes that were read to decode this value, and s.stream is the left-over stream.

  The leftover stream may contain more bytes which you may treat however you like depending on your application. You may ignore padding bytes reserved for extensions (in which case you can simply ignore the stream). You may use the leftover stream to call read_stream again to decode the rest of the value.

  read_stream ~init e is the same as let (Await k) = read_stream e in k b where b are the leftover bytes of init.

  E.g., reading multiple values from a socket or some such source of bytes that becomes available as time goes by.

  let iter socket encoding f =
     let rec loop = function
        | Success {result; size; stream} ->
           log "read %d bytes" size;
           f result (* apply iterator function on each decoded value *);
           loop (read_stream ~init:stream e) (* continue with leftover *)
        | Await k ->
           loop (k (read_more_bytes_from socket))
        | Error e ->
           log "error: %a" pp_read_error e
     in
     loop (read_stream e)

The internal state that writers handle. It is presented explicitly as an abstract type so that you must use the constructor to obtain it. The constructor (make_writer_state) performs basic bound checks.

make_writer_state buffer ~offset ~allowed_bytes is None if allowed_bytes < 0, None if allowed_bytes > length buffer - offset, Some _ otherwise.

write enc v state where Some state is make_writer_state buffer ~offset ~allowed_bytes writes the binary enc representation of v onto buffer starting at offset. The function will fail (returning Error _) if the encoding would use more than allowed_bytes.

The function returns the offset of first unwritten bytes, or returns Error _ in case of failure. In the latter case, some data might have been written on the buffer.

of_bytes enc buf is equivalent to read enc buf 0 (length buf). The function fails if the buffer is not fully read.

of_bytes_exn enc buf is equivalent to of_bytes, except

• raises [Read_error]

  instead of returning None in case of error.

of_string enc buf is like of_bytes enc buf but it reads bytes from a string.

to_bytes enc v is the equivalent of write env buf 0 len where buf is a newly allocated buffer. The parameter buffer_size controls the initial size of buf.

• raises [Invalid_argument]

  if buffer_size < 0.

to_bytes_exn enc v is equivalent to to_bytes enc v, except

• raises [Write_error]

  instead of returning None in case of error.

to_string enc v is like to_bytes but it returns a string.

Note: to_string enc v is always equal to Bytes.to_string (to_bytes enc v) but more efficient.

• raises [Invalid_argument]

  if buffer_size < 0.

• raises [Write_error]

  instead of returning None in case of error.