package data-encoding

  1. Overview
  2. Docs
Library of JSON and binary encoding combinators

Install 

dune-project
 Dependency

gitlab.com Readme Changelog Edit opam file Versions (14)

Authors

  1. N
    Nomadic Labs

Maintainers

  1. C
    contact@nomadic-labs.com

Sources

data-encoding-v0.4.tar.gz
md5=7b687e25619637d40d2bbcd2c21b00c2
sha512=65e33b1a56e9058a2e9c7f3dc18cb72c21270e0e5b9584fe856285d16e4cb8e98adac826373d4109a5e080486ec31cdd9870b402249ac5d55c7b0de6ffb68b0a

doc/data-encoding/Data_encoding/Binary/index.html

Module Data_encoding.BinarySource

Sourcetype read_error =
  1. | Not_enough_data
    (*

    Decoding requires more bytes than are available in the source of the data. E.g., there are fewer bytes available in the reading buffer than is required by the length field of a dynamically-sized string.

    *)
  2. | Extra_bytes
    (*

    Decoding requires fewer bytes than were provided.

    *)
  3. | No_case_matched
    (*

    Unknown case in a string_enum.

    *)
  4. | Unexpected_tag of int
    (*

    Unknown case in a union or matching.

    *)
  5. | Invalid_int of {
    1. min : int;
    2. v : int;
    3. max : int;
    }
    (*

    An integer is out of range. E.g., an integer is beyond a user-provided range.

    *)
  6. | Invalid_float of {
    1. min : float;
    2. v : float;
    3. max : float;
    }
    (*

    A float is out of range.

    *)
  7. | Trailing_zero
    (*

    An arbitrary-precision number (N or Z) leads to a null byte.

    *)
  8. | Size_limit_exceeded
    (*

    A value is encoded with more bytes than is allowed by the encoding. E.g., the constraints of a check_size are being broken.

    *)
  9. | List_too_long
    (*

    A list contains more elements than is specified in its max_length parameter.

    *)
  10. | Array_too_long
    (*

    An array contains more elements than is specified in its max_length parameter.

    *)
  11. | Exception_raised_in_user_function of string
    (*

    A function provided by the user raised an exception. E.g., a function in a conv encoding or a delayed encoding raised.

    *)
  12. | User_invariant_guard of string
    (*

    A user-provided guard returned an Error _. E.g., in a conv_with_guard.

    *)

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

Sourceexception Read_error of read_error

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.

Sourceval pp_read_error : Format.formatter -> read_error -> unit
Sourceval read_error_encoding : read_error t
Sourcetype write_error =
  1. | Size_limit_exceeded
  2. | No_case_matched
  3. | Invalid_int of {
    1. min : int;
    2. v : int;
    3. max : int;
    }
  4. | Invalid_float of {
    1. min : float;
    2. v : float;
    3. max : float;
    }
  5. | Invalid_bytes_length of {
    1. expected : int;
    2. found : int;
    }
  6. | Invalid_string_length of {
    1. expected : int;
    2. found : int;
    }
  7. | Invalid_natural
  8. | List_too_long
  9. | Array_too_long
  10. | Exception_raised_in_user_function of string

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

Sourceval pp_write_error : Format.formatter -> write_error -> unit
Sourceval write_error_encoding : write_error t
Sourceexception Write_error of write_error
Sourceval length : 'a Encoding.t -> 'a -> int

Compute the expected length of the binary representation of a value

Sourceval fixed_length : 'a Encoding.t -> int option

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

Sourceval maximum_length : 'a Encoding.t -> int option

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 _.

Sourceval read : 'a Encoding.t -> string -> int -> int -> (int * 'a, read_error) result

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.

Sourceval read_opt : 'a Encoding.t -> string -> int -> int -> (int * 'a) option

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

Sourceval read_exn : 'a Encoding.t -> string -> int -> int -> int * 'a

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

Sourcetype 'ret status =
  1. | Success of {
    1. result : 'ret;
    2. size : int;
    3. stream : Data_encoding__.Binary_stream.t;
    }
    (*

    Fully decoded value, together with the total amount of bytes reads, and the remaining unread stream.

    *)
  2. | Await of Bytes.t -> 'ret status
    (*

    Partially decoded value.

    *)
  3. | Error of read_error
    (*

    Failure. The stream is garbled and it should be dropped.

    *)

Return type for the function read_stream.

Sourceval read_stream : ?init:Data_encoding__.Binary_stream.t -> 'a Encoding.t -> 'a status

Streamed equivalent of read. This variant cannot be called on variable-size encodings.

Sourcetype writer_state

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.

Sourceval make_writer_state : bytes -> offset:int -> allowed_bytes:int -> writer_state option

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

Sourceval write : 'a Encoding.t -> 'a -> writer_state -> (int, write_error) result

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.

Sourceval write_opt : 'a Encoding.t -> 'a -> writer_state -> int option
Sourceval write_exn : 'a Encoding.t -> 'a -> writer_state -> int
Sourceval of_bytes : 'a Encoding.t -> Bytes.t -> ('a, read_error) result

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

Sourceval of_bytes_opt : 'a Encoding.t -> Bytes.t -> 'a option
Sourceval of_bytes_exn : 'a Encoding.t -> Bytes.t -> 'a

of_bytes_exn enc buf is equivalent to of_bytes, except

  • raises [Read_error]

    instead of returning None in case of error.

Sourceval of_string : 'a Encoding.t -> string -> ('a, read_error) result

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

Sourceval of_string_opt : 'a Encoding.t -> string -> 'a option
Sourceval of_string_exn : 'a Encoding.t -> string -> 'a
Sourceval to_bytes : ?buffer_size:int -> 'a Encoding.t -> 'a -> (Bytes.t, write_error) result

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.

Sourceval to_bytes_opt : ?buffer_size:int -> 'a Encoding.t -> 'a -> Bytes.t option
Sourceval to_bytes_exn : ?buffer_size:int -> 'a Encoding.t -> 'a -> Bytes.t

to_bytes_exn enc v is equivalent to to_bytes enc v, except

  • raises [Write_error]

    instead of returning None in case of error.

Sourceval to_string : ?buffer_size:int -> 'a Encoding.t -> 'a -> (string, write_error) result

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.

Sourceval to_string_opt : ?buffer_size:int -> 'a Encoding.t -> 'a -> string option
Sourceval to_string_exn : ?buffer_size:int -> 'a Encoding.t -> 'a -> string
  • raises [Write_error]

    instead of returning None in case of error.

Sourceval describe : 'a Encoding.t -> Binary_schema.t
Sourcemodule Slicer : sig ... end