package tezos-protocol-environment

  1. Overview
  2. Docs
package tezos-protocol-environment
Legend:
Library
Module
Module type
Parameter
Class
Class type
type read_error = Data_encoding.Binary.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

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

val pp_read_error : Stdlib.Format.formatter -> read_error -> unit
val read_error_encoding : read_error Data_encoding.t
type write_error = Data_encoding.Binary.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_invalid_length
  9. | Array_invalid_length
  10. | Exception_raised_in_user_function of string

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

val pp_write_error : Stdlib.Format.formatter -> write_error -> unit
val write_error_encoding : write_error Data_encoding.t
exception Write_error of write_error
val length : 'a Data_encoding.Encoding.t -> 'a -> int

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

  • raises Write_error

    in case some size/length invariants are broken.

val fixed_length : 'a Data_encoding.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

val maximum_length : 'a Data_encoding.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 _.

val read_opt : 'a Data_encoding.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.

val read_exn : 'a Data_encoding.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.

type 'ret status = 'ret Data_encoding.Binary.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 Stdlib.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.

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.

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

val write_opt : 'a Data_encoding.Encoding.t -> 'a -> writer_state -> int option
val write_exn : 'a Data_encoding.Encoding.t -> 'a -> writer_state -> int
val of_bytes_opt : 'a Data_encoding.Encoding.t -> Stdlib.Bytes.t -> 'a option
val of_bytes_exn : 'a Data_encoding.Encoding.t -> Stdlib.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.

val of_string : 'a Data_encoding.Encoding.t -> string -> ('a, read_error) Stdlib.result

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

val of_string_opt : 'a Data_encoding.Encoding.t -> string -> 'a option
val of_string_exn : 'a Data_encoding.Encoding.t -> string -> 'a
val to_bytes_opt : ?buffer_size:int -> 'a Data_encoding.Encoding.t -> 'a -> Stdlib.Bytes.t option
val to_string : ?buffer_size:int -> 'a Data_encoding.Encoding.t -> 'a -> (string, write_error) Stdlib.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.

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

    instead of returning None in case of error.

module Slicer = Data_encoding.Binary.Slicer
val read : 'a Data_encoding.Encoding.t -> bytes -> int -> int -> (int * 'a) option
val write : 'a Data_encoding.Encoding.t -> 'a -> bytes -> int -> int -> int option
val of_bytes : 'a Data_encoding.Encoding.t -> Stdlib.Bytes.t -> 'a option
val to_bytes : 'a Data_encoding.Encoding.t -> 'a -> Stdlib.Bytes.t option
val to_bytes_exn : 'a Data_encoding.Encoding.t -> 'a -> Stdlib.Bytes.t
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct