module Cf_message:sig
..end
Functional message buffer chains.
This module implements convenience functions useful when manipulating lists of substrings that represent portable inter-process communication messages. A list of substrings is very much like the "mbuf" chain commonly found in network protocol stacks, and this module facilitates composing and manipulating messages in this way.
typesubstring =
bytes * int * int
The type of messages, i.e. a list of substrings (a string, the position of the first character in the substring, and the length of the substring).
typet =
substring list
val normalize : t -> t
Use normalize m
to discard empty substrings from the list. Raises
Invalid_arg
if any of the substrings have a negative length or which
specify invalid substrings of the string component of the triple.
val create : string -> t
Use create s
to obtain a new message composed of a flattened message
containing the string s
. Returns the empty list when the string is the
empty string.
val length : t -> int
Use length m
to compute the length of the message m
.
val contents : t -> string
Use contents m
to create a new string containing the entire text of the
message m
.
val copy : t -> t
Use copy m
to create a new message with a deep copy of the contents of
m
, i.e. it is equivalent to create (contents m)
.
val flatten : t -> t
Use flatten m
to reduce a message list of two or more substrings to a
single substring. If m
is already a single substring or the empty list,
then m
itself is returned. Otherwise, the result is the same as what
copy m
would return.
val split : pos:int -> t -> t * t
Use split ~pos m
to return two new messages, the first containing all the
text in message m
before the position pos
, and the second containing
all the remaining text in message m
. The strings themselves are not
copied; only the list of substrings is manipulated. Raises
Invalid_argument
if the position is negative or beyond the length of the
message.
val truncate : pos:int -> t -> t
Use truncate ~pos m
to return a new message containing all the text in
message m
before the position pos
. The strings themselves are not
copied; only the list of substrings is manipulated. Raises
Invalid_argument
if the position is negative or beyond the length of the
message.
val shift : pos:int -> t -> t
Use shift ~pos m
to return a new message with all the text in message m
before the position pos
removed. This strings themselves are not copied;
only the list of substrings is manipulated. Raises Invalid_argument
if
the position is negative or beyond the length of the message.
val insert : pos:int -> m:t -> t -> t
Use insert ~pos ~m m1
to return a new message with all the text in
message m
inserted into the message m1
at the position pos
. The
strings themselves are not copied; only the list of substrings is
manipulated. Raises Invalid_argument
if the position is negative or
beyond the length of the message.
val push : t ->
substring Cf_deque.t -> substring Cf_deque.t
Use push m q
to push the message m
into the A
end of the substring
queue q
.
val pop : len:int ->
substring Cf_deque.t ->
t * substring Cf_deque.t
Use pop ~len q
to pop a message of length no larger than len
from the
B
end of the substring deque q
. The message and the remainder of the
deque are returned.
val shiftq : len:int -> substring Cf_deque.t -> substring Cf_deque.t
Use shiftq ~len q
to discard the first len
octets from the B
end of
the substring deque q
. The remainder of the deque is returned.
val drain : substring Cf_deque.t -> t
Use drain q
to convert the entire substring deque q
into a message.
val drain_seq : ?x:exn -> substring Cf_deque.t -> char Cf_seq.t
Use drain_seq q
to convert the substring deque q
into a character
sequence. If ?x
is provided then evaluating the sequence past the last
character in the message raises the exception. (This is more efficient
than applying Cf_seq.sentinel
to the result.)
val to_seq : ?x:exn -> t -> char Cf_seq.t
Use to_seq m
to obtain the sequence of characters in message m
.
The message is immediately normalized with normalize m
. If ?x
is
provided then evaluating the sequence past the last character in the
message raises the exception. (This is more efficient than applying
Cf_seq.sentinel
to the result.)
val to_function : ?x:exn -> t -> unit -> char
to_function m
returns a function that returns successive characters from
the message m
each time it is called, until it raises x
when there are
no more characters. If x
is not provided, then End_of_file
is raised.