# Module Cf_message

    module Cf_message: sig .. end

Functional message buffer chains.

Overview

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.

Types

    type substring = 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).

    type t = substring list

Functions

    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.