package core_kernel

  1. Overview
  2. Docs
package core_kernel
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module Unpack_buffer.Unpack_oneSource

If unpack_one : ('a, 'state) unpack, then unpack_one ~state ~buf ~pos ~len must unpack at most one value of type 'a from buf starting at pos, and not using more than len characters. unpack_one must return one the following:

  • `Ok (value, n) -- unpacking succeeded and consumed n bytes, where 0 <= n <= len. It is possible to have n = 0, e.g. for sexp unpacking, which can only tell it has reached the end of an atom when it encounters the following punctuation character, which if it is left paren, is the start of the following sexp.
  • `Not_enough_data (state, n) -- unpacking encountered a valid proper prefix of a packed value, and consumed n bytes, where 0 <= n <= len. state can be supplied to a future call to unpack_one to continue unpacking.
  • `Invalid_data -- unpacking encountered an invalidly packed value.

A naive unpack_one that only succeeds on a fully packed value could lead to quadratic behavior if a packed value's bytes are input using a linear number of calls to feed.

Sourcetype ('a, 'state) unpack_result = [
  1. | `Ok of 'a * int
  2. | `Not_enough_data of 'state * int
  3. | `Invalid_data of Core.Error.t
]
Sourcetype ('a, 'state) unpack = state:'state -> buf:Core.Bigstring.t -> pos:int -> len:int -> ('a, 'state) unpack_result
Sourcetype 'a t =
  1. | T : {
    1. initial_state : 'state;
    2. unpack : ('a, 'state) unpack;
    } -> 'a t
include Core.Monad.S with type 'a t := 'a t
Sourceval (>>=) : 'a t -> ('a -> 'b t) -> 'b t

t >>= f returns a computation that sequences the computations represented by two monad elements. The resulting computation first does t to yield a value v, and then runs the computation returned by f v.

Sourceval (>>|) : 'a t -> ('a -> 'b) -> 'b t

t >>| f is t >>= (fun a -> return (f a)).

Sourcemodule Monad_infix : sig ... end
Sourceval bind : 'a t -> f:('a -> 'b t) -> 'b t

bind t ~f = t >>= f

Sourceval return : 'a -> 'a t

return v returns the (trivial) computation that returns v.

Sourceval map : 'a t -> f:('a -> 'b) -> 'b t

map t ~f is t >>| f.

Sourceval join : 'a t t -> 'a t

join t is t >>= (fun t' -> t').

Sourceval ignore_m : 'a t -> unit t

ignore_m t is map t ~f:(fun _ -> ()). ignore_m used to be called ignore, but we decided that was a bad name, because it shadowed the widely used Stdlib.ignore. Some monads still do let ignore = ignore_m for historical reasons.

Sourceval all : 'a t list -> 'a list t
Sourceval all_unit : unit t list -> unit t

Like all, but ensures that every monadic value in the list produces a unit value, all of which are discarded rather than being collected into a list.

Sourcemodule Let_syntax : sig ... end

These are convenient to have in scope when programming with a monad:

Sourceval create : initial_state:'state -> unpack:('a, 'state) unpack -> 'a t
Sourceval create_bin_prot : 'a Core.Bin_prot.Type_class.reader -> 'a t

create_bin_prot reader returns an unpacker that reads the "size-prefixed" bin_prot encoding, in which a value is encoded by first writing the length of the bin_prot data as a 64-bit int, and then writing the data itself.

Reads "size-prefixed" bin-blobs, much like create_bin_prot _, but preserves the size information and doesn't deserialize the blob. This allows deserialization to be deferred and the remainder of the sequence can be unpacked if an individual blob can't be deserialized.

Sourceval sexp : Core.Sexp.t t

Beware that when unpacking sexps, one cannot tell if one is at the end of an atom until one hits punctuation. So, one should always feed a space (" ") to a sexp unpack buffer after feeding a batch of complete sexps, to ensure that the final sexp is unpacked.

Sourceval char : char t
Sourcemodule type Equal = sig ... end
Sourceval expect : 'a t -> (module Equal with type t = 'a) -> 'a -> unit t

expect t equal a returns an unpacker that unpacks using t and then returns `Ok if the unpacked value equals a, or `Invalid_data otherwise.

Sourceval expect_char : char -> unit t

expect_char is expect char (module Char)

Sourceval newline : unit t