Data_encoding.Binary
type read_error =
| 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. *) | |||
| Extra_bytes | (* Decoding requires fewer bytes than were provided. *) | |||
| No_case_matched | (* Unknown case in a | |||
| Unexpected_tag of int | (* Unknown case in a | |||
| Invalid_int of {
} | (* An integer is out of range. E.g., an integer is beyond a user-provided range. *) | |||
| Invalid_float of {
} | (* A float is out of range. *) | |||
| Trailing_zero | (* An arbitrary-precision number (N or Z) leads to a null byte. *) | |||
| Size_limit_exceeded | (* A value is encoded with more bytes than is allowed by the encoding. E.g., the constraints of a | |||
| List_too_long | (* A list contains more elements than is specified in its | |||
| Array_too_long | (* An array contains more elements than is specified in its | |||
| Exception_raised_in_user_function of string | (* A function provided by the user raised an exception. E.g., a function in a | |||
| User_invariant_guard of string | (* A user-provided guard returned an |
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 t
type write_error =
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 t
exception Write_error of write_error
val length : 'a Encoding.t -> 'a -> int
Compute the expected length of the binary representation of a value.
val 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
val 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 _
.
val read :
'a Encoding.t ->
string ->
int ->
int ->
( int * 'a, read_error ) Stdlib.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
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),len
bytes to decode the value,conv
or delayed
) raises an exception,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
.
val 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.
val 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.
type 'ret status =
| Success of {
} | (* Fully decoded value, together with the total amount of bytes reads, and the remaining unread stream. *) | |||
| Await of Stdlib.Bytes.t -> 'ret status | (* Partially decoded value. *) | |||
| Error of read_error | (* Failure. The stream is garbled and it should be dropped. *) |
Return type for the function read_stream
.
val read_stream : ?init:Binary_stream.t -> 'a Encoding.t -> 'a status
Streamed equivalent of read
.
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 :
'a Encoding.t ->
'a ->
writer_state ->
( int, write_error ) Stdlib.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.
val write_opt : 'a Encoding.t -> 'a -> writer_state -> int option
val write_exn : 'a Encoding.t -> 'a -> writer_state -> int
val of_bytes :
'a Encoding.t ->
Stdlib.Bytes.t ->
( 'a, read_error ) Stdlib.result
of_bytes enc buf
is equivalent to read enc buf 0 (length buf)
. The function fails if the buffer is not fully read.
val of_bytes_opt : 'a Encoding.t -> Stdlib.Bytes.t -> 'a option
val of_bytes_exn : 'a Encoding.t -> Stdlib.Bytes.t -> 'a
of_bytes_exn enc buf
is equivalent to of_bytes
, except
val of_string : 'a 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 Encoding.t -> string -> 'a option
val of_string_exn : 'a Encoding.t -> string -> 'a
val to_bytes :
?buffer_size:int ->
'a Encoding.t ->
'a ->
( Stdlib.Bytes.t, write_error ) Stdlib.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
.
val to_bytes_opt :
?buffer_size:int ->
'a Encoding.t ->
'a ->
Stdlib.Bytes.t option
val to_bytes_exn : ?buffer_size:int -> 'a Encoding.t -> 'a -> Stdlib.Bytes.t
to_bytes_exn enc v
is equivalent to to_bytes enc v
, except
val to_string :
?buffer_size:int ->
'a 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.
val to_string_opt : ?buffer_size:int -> 'a Encoding.t -> 'a -> string option
val to_string_exn : ?buffer_size:int -> 'a Encoding.t -> 'a -> string
val describe : 'a Encoding.t -> Binary_schema.t
module Slicer : sig ... end