mirror of
https://github.com/ocaml-tracing/ocaml-opentelemetry.git
synced 2026-05-06 01:15:11 -04:00
105 lines
68 KiB
HTML
105 lines
68 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Cstruct (cstruct.Cstruct)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 3.1.0"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../../index.html">Index</a> » <a href="../index.html">cstruct</a> » Cstruct</nav><header class="odoc-preamble"><h1>Module <code><span>Cstruct</span></code></h1><p>Manipulate external memory buffers as C-like structures.</p><p>Cstruct is a library and ppx rewriter to make it easier to access C-like structures directly from OCaml. It supports both reading and writing to these memory buffers, and they are accessed via the <code>Bigarray</code> module.</p><p>The library interface below is intended to be used in conjunction with the ppx rewriter that is also supplied with this library (in the <code>cstruct-ppx</code> ocamlfind package).</p><p>An example description for the pcap packet format is:</p><pre class="language-ocaml"><code>[%%cstruct
|
||
type pcap_header = {
|
||
magic_number: uint32_t; (* magic number *)
|
||
version_major: uint16_t; (* major version number *)
|
||
version_minor: uint16_t; (* minor version number *)
|
||
thiszone: uint32_t; (* GMT to local correction *)
|
||
sigfigs: uint32_t; (* accuracy of timestamps *)
|
||
snaplen: uint32_t; (* max length of captured packets, in octets *)
|
||
network: uint32_t; (* data link type *)
|
||
} [@@little_endian]
|
||
]
|
||
[%%cstruct
|
||
type pcap_packet = {
|
||
ts_sec: uint32_t; (* timestamp seconds *)
|
||
ts_usec: uint32_t; (* timestamp microseconds *)
|
||
incl_len: uint32_t; (* number of octets of packet saved in file *)
|
||
orig_len: uint32_t; (* actual length of packet *)
|
||
} [@@little_endian]
|
||
]
|
||
[%%cstruct
|
||
type ethernet = {
|
||
dst: uint8_t; [@len 6];
|
||
src: uint8_t; [@len 6];
|
||
ethertype: uint16_t;
|
||
} [@@big_endian]
|
||
]
|
||
[%%cstruct
|
||
type ipv4 = {
|
||
hlen_version: uint8_t;
|
||
tos: uint8_t;
|
||
len: uint16_t;
|
||
id: uint16_t;
|
||
off: uint16_t;
|
||
ttl: uint8_t;
|
||
proto: uint8_t;
|
||
csum: uint16_t;
|
||
src: uint8_t; [@len 4];
|
||
dst: uint8_t; [@len 4]
|
||
} [@@big_endian]
|
||
]</code></pre><p>These will expand to get and set functions for every field, with types appropriate to the particular definition. For instance:</p><pre class="language-ocaml"><code>val get_pcap_packet_ts_sec : Cstruct.t -> Cstruct.uint32
|
||
val set_pcap_packet_ts_sec : Cstruct.t -> Cstruct.uint32 -> unit
|
||
val get_pcap_packet_ts_usec : Cstruct.t -> Cstruct.uint32
|
||
val set_pcap_packet_ts_usec : Cstruct.t -> Cstruct.uint32 -> unit
|
||
val get_pcap_packet_incl_len : Cstruct.t -> Cstruct.uint32
|
||
val set_pcap_packet_incl_len : Cstruct.t -> Cstruct.uint32 -> unit
|
||
val get_pcap_packet_orig_len : Cstruct.t -> Cstruct.uint32
|
||
val set_pcap_packet_orig_len : Cstruct.t -> Cstruct.uint32 -> unit
|
||
val hexdump_pcap_packet_to_buffer : Buffer.t -> Cstruct.t -> unit</code></pre><p>The buffers generate a different set of functions. For the <code>ethernet</code> definitions, we have:</p><pre class="language-ocaml"><code>val sizeof_ethernet : int
|
||
val get_ethernet_dst : Cstruct.t -> Cstruct.t
|
||
val copy_ethernet_dst : Cstruct.t -> string
|
||
val set_ethernet_dst : string -> int -> Cstruct.t -> unit
|
||
val blit_ethernet_dst : Cstruct.t -> int -> Cstruct.t -> unit
|
||
val get_ethernet_src : Cstruct.t -> Cstruct.t
|
||
val copy_ethernet_src : Cstruct.t -> string</code></pre><p>You can also declare C-like enums:</p><pre class="language-ocaml"><code>[%%cenum
|
||
type foo32 =
|
||
| ONE32
|
||
| TWO32 [@id 0xfffffffel]
|
||
| THREE32
|
||
[@@uint32_t]
|
||
]
|
||
[%%cenum
|
||
type bar16 =
|
||
| ONE [@id 1]
|
||
| TWO
|
||
| FOUR [@id 4
|
||
| FIVE
|
||
[@@uint16_t]
|
||
]</code></pre><p>This generates signatures of the form:</p><pre class="language-ocaml"><code>type foo32 = | ONE32 | TWO32 | THREE32
|
||
val int_to_foo32 : int32 -> foo32 option
|
||
val foo32_to_int : foo32 -> int32
|
||
val foo32_to_string : foo32 -> string
|
||
val string_to_foo32 : string -> foo32 option
|
||
type bar16 = | ONE | TWO | FOUR | FIVE
|
||
val int_to_bar16 : int -> bar16 option
|
||
val bar16_to_int : bar16 -> int
|
||
val bar16_to_string : bar16 -> string
|
||
val string_to_bar16 : string -> bar16 option</code></pre></header><div class="odoc-tocs"><nav class="odoc-toc odoc-local-toc"><ul><li><a href="#base-types">Base types</a></li><li><a href="#creation-and-conversion">Creation and conversion</a></li><li><a href="#comparison">Comparison</a></li><li><a href="#getters-and-setters">Getters and Setters</a></li><li><a href="#debugging">Debugging</a></li><li><a href="#list-of-buffers">List of buffers</a></li><li><a href="#iterations">Iterations</a></li><li><a href="#helpers-to-parse.">Helpers to parse.</a></li></ul></nav></div><div class="odoc-content"><h3 id="base-types"><a href="#base-types" class="anchor"></a>Base types</h3><div class="odoc-spec"><div class="spec type anchored" id="type-buffer"><a href="#type-buffer" class="anchor"></a><code><span><span class="keyword">type</span> buffer</span><span> =
|
||
<span><span>(char, <a href="../../ocaml/Stdlib/Bigarray/index.html#type-int8_unsigned_elt">Stdlib.Bigarray.int8_unsigned_elt</a>, <a href="../../ocaml/Stdlib/Bigarray/index.html#type-c_layout">Stdlib.Bigarray.c_layout</a>)</span>
|
||
<a href="../../ocaml/Stdlib/Bigarray/Array1/index.html#type-t">Stdlib.Bigarray.Array1.t</a></span></span></code></div><div class="spec-doc"><p>Type of a buffer. A cstruct is composed of an underlying buffer and position/length within this buffer.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-t"><a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> t</span><span> = <span class="keyword">private</span> </span><span>{</span></code><ol><li id="type-t.buffer" class="def record field anchored"><a href="#type-t.buffer" class="anchor"></a><code><span>buffer : <a href="#type-buffer">buffer</a>;</span></code></li><li id="type-t.off" class="def record field anchored"><a href="#type-t.off" class="anchor"></a><code><span>off : int;</span></code></li><li id="type-t.len" class="def record field anchored"><a href="#type-t.len" class="anchor"></a><code><span>len : int;</span></code></li></ol><code><span>}</span></code></div><div class="spec-doc"><p>Type of a cstruct.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-byte"><a href="#type-byte" class="anchor"></a><code><span><span class="keyword">type</span> byte</span><span> = char</span></code></div><div class="spec-doc"><p>A single byte type</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-byte"><a href="#val-byte" class="anchor"></a><code><span><span class="keyword">val</span> byte : <span>int <span class="arrow">-></span></span> <a href="#type-byte">byte</a></span></code></div><div class="spec-doc"><p><code>byte v</code> convert <code>v</code> to a single byte.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>v</code> is negative or greater than 255.</p></li></ul></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-uint8"><a href="#type-uint8" class="anchor"></a><code><span><span class="keyword">type</span> uint8</span><span> = int</span></code></div><div class="spec-doc"><p>8-bit unsigned integer. The representation is currently an unboxed OCaml integer.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-uint16"><a href="#type-uint16" class="anchor"></a><code><span><span class="keyword">type</span> uint16</span><span> = int</span></code></div><div class="spec-doc"><p>16-bit unsigned integer. The representation is currently an unboxed OCaml integer.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-uint32"><a href="#type-uint32" class="anchor"></a><code><span><span class="keyword">type</span> uint32</span><span> = int32</span></code></div><div class="spec-doc"><p>32-bit unsigned integer. The representation is currently a boxed OCaml int32.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-uint64"><a href="#type-uint64" class="anchor"></a><code><span><span class="keyword">type</span> uint64</span><span> = int64</span></code></div><div class="spec-doc"><p>64-bit unsigned integer. The representation is currently a boxed OCaml int64.</p></div></div><h3 id="creation-and-conversion"><a href="#creation-and-conversion" class="anchor"></a>Creation and conversion</h3><div class="odoc-spec"><div class="spec value anchored" id="val-empty"><a href="#val-empty" class="anchor"></a><code><span><span class="keyword">val</span> empty : <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>empty</code> is the cstruct of length 0.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-of_bigarray"><a href="#val-of_bigarray" class="anchor"></a><code><span><span class="keyword">val</span> of_bigarray : <span><span class="optlabel">?off</span>:int <span class="arrow">-></span></span> <span><span class="optlabel">?len</span>:int <span class="arrow">-></span></span> <span><a href="#type-buffer">buffer</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>of_bigarray ~off ~len b</code> is the cstruct contained in <code>b</code> starting at offset <code>off</code> (default <code>0</code>) of length <code>len</code> (default <code>Bigarray.Array1.dim b - off</code>).</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_bigarray"><a href="#val-to_bigarray" class="anchor"></a><code><span><span class="keyword">val</span> to_bigarray : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-buffer">buffer</a></span></code></div><div class="spec-doc"><p><code>to_bigarray t</code> converts a <a href="#type-t"><code>t</code></a> into a <a href="#type-buffer"><code>buffer</code></a> Bigarray, using the Bigarray slicing to allocate a fresh array that preserves sharing of the underlying buffer.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-create"><a href="#val-create" class="anchor"></a><code><span><span class="keyword">val</span> create : <span>int <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>create len</code> is a fresh cstruct of size <code>len</code> with an offset of 0, filled with zero bytes.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-create_unsafe"><a href="#val-create_unsafe" class="anchor"></a><code><span><span class="keyword">val</span> create_unsafe : <span>int <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>create_unsafe len</code> is a cstruct of size <code>len</code> with an offset of 0.</p><p>Note that the returned cstruct will contain arbitrary data, likely including the contents of previously-deallocated cstructs.</p><p>Beware!</p><p>Forgetting to replace this data could cause your application to leak sensitive information.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-of_string"><a href="#val-of_string" class="anchor"></a><code><span><span class="keyword">val</span> of_string : <span><span class="optlabel">?allocator</span>:<span>(<span>int <span class="arrow">-></span></span> <a href="#type-t">t</a>)</span> <span class="arrow">-></span></span> <span><span class="optlabel">?off</span>:int <span class="arrow">-></span></span> <span><span class="optlabel">?len</span>:int <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>of_string ~allocator ~off ~len str</code> is the cstruct representation of <code>str</code> slice located at offset <code>off</code> (default <code>0</code>) and of length <code>len</code> (default <code>String.length str - off</code>), with the underlying buffer allocated by <code>alloc</code>. If <code>allocator</code> is not provided, <code>create</code> is used.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>off</code> or <code>len</code> is negative, or <code>String.length str - off</code> < <code>len</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-of_bytes"><a href="#val-of_bytes" class="anchor"></a><code><span><span class="keyword">val</span> of_bytes : <span><span class="optlabel">?allocator</span>:<span>(<span>int <span class="arrow">-></span></span> <a href="#type-t">t</a>)</span> <span class="arrow">-></span></span> <span><span class="optlabel">?off</span>:int <span class="arrow">-></span></span> <span><span class="optlabel">?len</span>:int <span class="arrow">-></span></span> <span>bytes <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>of_bytes ~allocator byt</code> is the cstruct representation of <code>byt</code> slice located at offset <code>off</code> (default <code>0</code>) and of length <code>len</code> (default <code>Bytes.length byt - off</code>), with the underlying buffer allocated by <code>alloc</code>. If <code>allocator</code> is not provided, <code>create</code> is used.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>off</code> or <code>len</code> is negative, or <code>Bytes.length str - off</code> < <code>len</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-of_hex"><a href="#val-of_hex" class="anchor"></a><code><span><span class="keyword">val</span> of_hex : <span><span class="optlabel">?off</span>:int <span class="arrow">-></span></span> <span><span class="optlabel">?len</span>:int <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>of_hex ~off ~len str</code> is the cstruct <code>cs</code>. Every pair of hex-encoded characters in <code>str</code> starting at offset <code>off</code> (default <code>0</code>) of length <code>len</code> (default <code>String.length str - off</code>) are converted to one byte in <code>cs</code>. Whitespaces (space, newline, tab, carriage return) in <code>str</code> are skipped.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the input string contains invalid characters or has an odd numbers of non-whitespace characters, or if <code>off</code> or <code>len</code> are negative, or <code>String.length str - off</code> < <code>len</code>.</p></li></ul></div></div><h3 id="comparison"><a href="#comparison" class="anchor"></a>Comparison</h3><div class="odoc-spec"><div class="spec value anchored" id="val-equal"><a href="#val-equal" class="anchor"></a><code><span><span class="keyword">val</span> equal : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>equal t1 t2</code> is <code>true</code> iff <code>t1</code> and <code>t2</code> correspond to the same sequence of bytes.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-compare"><a href="#val-compare" class="anchor"></a><code><span><span class="keyword">val</span> compare : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>compare t1 t2</code> gives an unspecified total ordering over <a href="#type-t"><code>t</code></a>.</p></div></div><h3 id="getters-and-setters"><a href="#getters-and-setters" class="anchor"></a>Getters and Setters</h3><div class="odoc-spec"><div class="spec value anchored" id="val-byte_to_int"><a href="#val-byte_to_int" class="anchor"></a><code><span><span class="keyword">val</span> byte_to_int : <span><a href="#type-byte">byte</a> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p>Convert a byte to an integer</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-check_bounds"><a href="#val-check_bounds" class="anchor"></a><code><span><span class="keyword">val</span> check_bounds : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>check_bounds cstr len</code> is <code>true</code> if <code>len</code> is a non-negative integer and <code>cstr.buffer</code>'s size is greater or equal than <code>len</code> <code>false</code> otherwise.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-check_alignment"><a href="#val-check_alignment" class="anchor"></a><code><span><span class="keyword">val</span> check_alignment : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>check_alignment cstr alignment</code> is <code>true</code> if the first byte stored within <code>cstr</code> is at a memory address where <code>address mod alignment = 0</code>, <code>false</code> otherwise. Typical uses are to check a buffer is aligned to a page or disk sector boundary.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>alignment</code> is not a positive integer.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-get_char"><a href="#val-get_char" class="anchor"></a><code><span><span class="keyword">val</span> get_char : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> char</span></code></div><div class="spec-doc"><p><code>get_char t off</code> returns the character contained in the cstruct at offset <code>off</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the offset exceeds cstruct length.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-get_uint8"><a href="#val-get_uint8" class="anchor"></a><code><span><span class="keyword">val</span> get_uint8 : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <a href="#type-uint8">uint8</a></span></code></div><div class="spec-doc"><p><code>get_uint8 t off</code> returns the byte contained in the cstruct at offset <code>off</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the offset exceeds cstruct length.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-set_char"><a href="#val-set_char" class="anchor"></a><code><span><span class="keyword">val</span> set_char : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span>char <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>set_char t off c</code> sets the byte contained in the cstruct at offset <code>off</code> to character <code>c</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the offset exceeds cstruct length.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-set_uint8"><a href="#val-set_uint8" class="anchor"></a><code><span><span class="keyword">val</span> set_uint8 : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span><a href="#type-uint8">uint8</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>set_uint8 t off c</code> sets the byte contained in the cstruct at offset <code>off</code> to byte <code>c</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the offset exceeds cstruct length.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-sub"><a href="#val-sub" class="anchor"></a><code><span><span class="keyword">val</span> sub : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>sub cstr off len</code> is <code>{ t with off = t.off + off; len }</code></p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the offset exceeds cstruct length.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-sub_copy"><a href="#val-sub_copy" class="anchor"></a><code><span><span class="keyword">val</span> sub_copy : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>sub_copy cstr off len</code> is a new copy of <code>sub cstr off len</code>, that does not share the underlying buffer of <code>cstr</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the offset exceeds cstruct length.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-shift"><a href="#val-shift" class="anchor"></a><code><span><span class="keyword">val</span> shift : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>shift cstr len</code> is <code>{ cstr with off=t.off+len; len=t.len-len }</code></p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the offset exceeds cstruct length.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-copy"><a href="#val-copy" class="anchor"></a><code><span><span class="keyword">val</span> copy : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p><code>copy cstr off len</code> is the string representation of the segment of <code>t</code> starting at <code>off</code> of size <code>len</code>. It is equivalent to <code>Cstruct.to_string cstr ~off ~len</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>off</code> and <code>len</code> do not designate a valid segment of <code>t</code>.</p></li></ul><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> this is just like [to_string] without defaults, were you looking for [sub_copy]?</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-blit"><a href="#val-blit" class="anchor"></a><code><span><span class="keyword">val</span> blit : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>blit src srcoff dst dstoff len</code> copies <code>len</code> characters from cstruct <code>src</code>, starting at index <code>srcoff</code>, to cstruct <code>dst</code>, starting at index <code>dstoff</code>. It works correctly even if <code>src</code> and <code>dst</code> are the same string, and the source and destination intervals overlap.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>srcoff</code> and <code>len</code> do not designate a valid segment of <code>src</code>, or if <code>dstoff</code> and <code>len</code> do not designate a valid segment of <code>dst</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-blit_from_string"><a href="#val-blit_from_string" class="anchor"></a><code><span><span class="keyword">val</span> blit_from_string : <span>string <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>blit_from_string src srcoff dst dstoff len</code> copies <code>len</code> characters from string <code>src</code>, starting at index <code>srcoff</code>, to cstruct <code>dst</code>, starting at index <code>dstoff</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>srcoff</code> and <code>len</code> do not designate a valid substring of <code>src</code>, or if <code>dstoff</code> and <code>len</code> do not designate a valid segment of <code>dst</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-blit_from_bytes"><a href="#val-blit_from_bytes" class="anchor"></a><code><span><span class="keyword">val</span> blit_from_bytes : <span>bytes <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>blit_from_bytes src srcoff dst dstoff len</code> copies <code>len</code> characters from bytes <code>src</code>, starting at index <code>srcoff</code>, to cstruct <code>dst</code>, starting at index <code>dstoff</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>srcoff</code> and <code>len</code> do not designate a valid subsequence of <code>src</code>, or if <code>dstoff</code> and <code>len</code> do not designate a valid segment of <code>dst</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-blit_to_bytes"><a href="#val-blit_to_bytes" class="anchor"></a><code><span><span class="keyword">val</span> blit_to_bytes : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span>bytes <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>blit_to_bytes src srcoff dst dstoff len</code> copies <code>len</code> characters from cstruct <code>src</code>, starting at index <code>srcoff</code>, to the <code>dst</code> buffer, starting at index <code>dstoff</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>srcoff</code> and <code>len</code> do not designate a valid segment of <code>src</code>, or if <code>dstoff</code> and <code>len</code> do not designate a valid segment of <code>dst</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-memset"><a href="#val-memset" class="anchor"></a><code><span><span class="keyword">val</span> memset : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>memset t x</code> sets all the bytes of <code>t</code> to <code>x land 0xff</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-split"><a href="#val-split" class="anchor"></a><code><span><span class="keyword">val</span> split : <span><span class="optlabel">?start</span>:int <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <a href="#type-t">t</a> * <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>split ~start cstr len</code> is a tuple containing the cstruct extracted from <code>cstr</code> at offset <code>start</code> (default: 0) of length <code>len</code> as first element, and the rest of <code>cstr</code> as second element.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>start</code> exceeds the cstruct length, or if there is a bounds violation of the cstruct via <code>len+start</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_string"><a href="#val-to_string" class="anchor"></a><code><span><span class="keyword">val</span> to_string : <span><span class="optlabel">?off</span>:int <span class="arrow">-></span></span> <span><span class="optlabel">?len</span>:int <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p><code>to_string ~off ~len t</code> will allocate a fresh OCaml <code>string</code> and copy the contents of the cstruct starting at offset <code>off</code> (default <code>0</code>) of length <code>len</code> (default <code>Cstruct.length t - off</code>) into it, and return that string.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>off</code> or <code>len</code> is negative, or <code>Cstruct.length t - off</code> < <code>len</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_hex_string"><a href="#val-to_hex_string" class="anchor"></a><code><span><span class="keyword">val</span> to_hex_string : <span><span class="optlabel">?off</span>:int <span class="arrow">-></span></span> <span><span class="optlabel">?len</span>:int <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p><code>to_hex_string ~off ~len t</code> is a fresh OCaml <code>string</code> containing the hex representation of <code>sub t off len</code>. It is therefore of length <code>2 * len</code>. This string can be read back into a Cstruct using <a href="#val-of_hex"><code>of_hex</code></a>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>off</code> or <code>len</code> is negative, or if <code>Cstruct.length t - off < len</code>.</p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 6.2</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_bytes"><a href="#val-to_bytes" class="anchor"></a><code><span><span class="keyword">val</span> to_bytes : <span><span class="optlabel">?off</span>:int <span class="arrow">-></span></span> <span><span class="optlabel">?len</span>:int <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> bytes</span></code></div><div class="spec-doc"><p><code>to_bytes ~off ~len t</code> will allocate a fresh OCaml <code>bytes</code> and copy the contents of the cstruct starting at offset <code>off</code> (default <code>0</code>) of length <code>len</code> (default <code>Cstruct.length t - off</code>) into it, and return that bytes.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>off</code> or <code>len</code> is negative, or <code>Cstruct.length str - off</code> < <code>len</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-BE"><a href="#module-BE" class="anchor"></a><code><span><span class="keyword">module</span> <a href="BE/index.html">BE</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>Get/set big-endian integers of various sizes. The second argument of those functions is the position relative to the current offset of the cstruct.</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-LE"><a href="#module-LE" class="anchor"></a><code><span><span class="keyword">module</span> <a href="LE/index.html">LE</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>Get/set little-endian integers of various sizes. The second argument of those functions is the position relative to the current offset of the cstruct.</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-HE"><a href="#module-HE" class="anchor"></a><code><span><span class="keyword">module</span> <a href="HE/index.html">HE</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>Get/set host-endian integers of various sizes. The second argument of those functions is the position relative to the current offset of the cstruct.</p></div></div><h3 id="debugging"><a href="#debugging" class="anchor"></a>Debugging</h3><div class="odoc-spec"><div class="spec value anchored" id="val-hexdump"><a href="#val-hexdump" class="anchor"></a><code><span><span class="keyword">val</span> hexdump : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>When the going gets tough, the tough hexdump their cstructs and peer at it until the bug disappears. This will directly prettyprint the contents of the cstruct to the standard output.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-hexdump_to_buffer"><a href="#val-hexdump_to_buffer" class="anchor"></a><code><span><span class="keyword">val</span> hexdump_to_buffer : <span><a href="../../ocaml/Stdlib/Buffer/index.html#type-t">Stdlib.Buffer.t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>hexdump_to_buffer buf c</code> will append the pretty-printed hexdump of the cstruct <code>c</code> to the buffer <code>buf</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-hexdump_pp"><a href="#val-hexdump_pp" class="anchor"></a><code><span><span class="keyword">val</span> hexdump_pp : <span><a href="../../ocaml/Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>hexdump_pp f c</code> pretty-prints a hexdump of <code>c</code> to <code>f</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-debug"><a href="#val-debug" class="anchor"></a><code><span><span class="keyword">val</span> debug : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p><code>debug t</code> will print out the internal details of a cstruct such as its base offset and the length, and raise an assertion failure if invariants have been violated. Not intended for casual use.</p></div></div><h3 id="list-of-buffers"><a href="#list-of-buffers" class="anchor"></a>List of buffers</h3><div class="odoc-spec"><div class="spec value anchored" id="val-lenv"><a href="#val-lenv" class="anchor"></a><code><span><span class="keyword">val</span> lenv : <span><span><a href="#type-t">t</a> list</span> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>lenv cstrs</code> is the combined length of all cstructs in <code>cstrs</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if computing the sum overflows.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-copyv"><a href="#val-copyv" class="anchor"></a><code><span><span class="keyword">val</span> copyv : <span><span><a href="#type-t">t</a> list</span> <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p><code>copyv cstrs</code> is the string representation of the concatenation of all cstructs in <code>cstrs</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the length of the result would exceed <code>Sys.max_string_length</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-fillv"><a href="#val-fillv" class="anchor"></a><code><span><span class="keyword">val</span> fillv : <span><span class="label">src</span>:<span><a href="#type-t">t</a> list</span> <span class="arrow">-></span></span> <span><span class="label">dst</span>:<a href="#type-t">t</a> <span class="arrow">-></span></span> int * <span><a href="#type-t">t</a> list</span></span></code></div><div class="spec-doc"><p><code>fillv ~src ~dst</code> copies from <code>src</code> to <code>dst</code> until <code>src</code> is exhausted or <code>dst</code> is full. Returns the number of bytes copied and the remaining data from <code>src</code>, if any. This is useful if you want buffer data into fixed-sized chunks.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-shiftv"><a href="#val-shiftv" class="anchor"></a><code><span><span class="keyword">val</span> shiftv : <span><span><a href="#type-t">t</a> list</span> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span><a href="#type-t">t</a> list</span></span></code></div><div class="spec-doc"><p><code>shiftv ts n</code> is <code>ts</code> without the first <code>n</code> bytes. It has the property that <code>equal (concat (shiftv ts n)) (shift (concat ts) n)</code>. This operation is fairly fast, as it will share the tail of the list. The first item in the returned list is never an empty cstruct, so you'll get <code>[]</code> if and only if <code>lenv ts = n</code>.</p></div></div><h3 id="iterations"><a href="#iterations" class="anchor"></a>Iterations</h3><div class="odoc-spec"><div class="spec type anchored" id="type-iter"><a href="#type-iter" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a iter</span></span><span> = <span>unit <span class="arrow">-></span></span> <span><span class="type-var">'a</span> option</span></span></code></div><div class="spec-doc"><p>Type of an iterator.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-iter"><a href="#val-iter" class="anchor"></a><code><span><span class="keyword">val</span> iter : <span><span>(<span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int option</span>)</span> <span class="arrow">-></span></span> <span><span>(<span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-iter">iter</a></span></span></code></div><div class="spec-doc"><p><code>iter lenf of_cstr cstr</code> is an iterator over <code>cstr</code> that returns elements of size <code>lenf cstr</code> and type <code>of_cstr cstr</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-fold"><a href="#val-fold" class="anchor"></a><code><span><span class="keyword">val</span> fold : <span><span>(<span><span class="type-var">'b</span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-iter">iter</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <span class="arrow">-></span></span> <span class="type-var">'b</span></span></code></div><div class="spec-doc"><p><code>fold f iter acc</code> is <code>(f iterN accN ... (f iter acc)...)</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-append"><a href="#val-append" class="anchor"></a><code><span><span class="keyword">val</span> append : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>append t1 t2</code> is the concatenation <code>t1 || t2</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-concat"><a href="#val-concat" class="anchor"></a><code><span><span class="keyword">val</span> concat : <span><span><a href="#type-t">t</a> list</span> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>concat ts</code> is the concatenation of all the <code>ts</code>. It is not guaranteed that * the result is a newly created <code>t</code> in the zero- and one-element cases.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-rev"><a href="#val-rev" class="anchor"></a><code><span><span class="keyword">val</span> rev : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>rev t</code> is <code>t</code> in reverse order. The return value is a freshly allocated cstruct, and the argument is not modified.</p></div></div><h2 id="helpers-to-parse."><a href="#helpers-to-parse." class="anchor"></a>Helpers to parse.</h2><p><code>Cstruct</code> is used to manipulate <i>payloads</i> which can be formatted according an <a href="https://perdu.com/">RFC</a> or an user-defined format. In such context, this module provides utilities to be able to easily <i>parse</i> <i>payloads</i>.</p><p>Due to the type <a href="#type-t"><code>Cstruct.t</code></a>, no copy are done when you use these utilities and you are able to extract your information without a big performance cost.</p><p>More precisely, each values returned by these utilities will be located into the minor-heap where the base buffer will never be copied or relocated.</p><p>For instance, to parse a Git tree object:</p><pre> entry := perm ' ' name '\000' 20byte
|
||
tree := entry *</pre><pre class="language-ocaml"><code> open Cstruct
|
||
|
||
let ( >>= ) = Option.bind
|
||
|
||
let rec hash_of_name ~name payload =
|
||
if is_empty payload then raise Not_found
|
||
else
|
||
cut ~sep:(v " ") payload >>= fun (_, payload) ->
|
||
cut ~sep:(v "\000") payload >>= fun (name', payload) ->
|
||
if name = name' then with_range ~len:20 payload
|
||
else hash_of_name ~name (shift payload 20)</code></pre><p>A <code>Cstruct</code> defines a possibly empty subsequence of bytes in a <em>base</em> buffer (a <code>Bigarray.Array1.t</code>).</p><p>The positions of a buffer <code>b</code> of length <code>l</code> are the slits found before each byte and after the last byte of the buffer. They are labelled from left to right by increasing number in the range [<code>0</code>;<code>l</code>].</p><pre>positions 0 1 2 3 4 l-1 l
|
||
+---+---+---+---+ +-----+
|
||
indices | 0 | 1 | 2 | 3 | ... | l-1 |
|
||
+---+---+---+---+ +-----+</pre><p>The <code>i</code>th byte index is between positions <code>i</code> and <code>i+1</code>.</p><p>Formally we define a subbuffer of <code>b</code> as being a subsequence of bytes defined by a <em>off</em> position and a <em>len</em> number. When <code>len</code> is <code>0</code> the subbuffer is <em>empty</em>. Note that for a given base buffer there are as many empty subbuffers as there are positions in the buffer.</p><p>Like in strings, we index the bytes of a subbuffer using zero-based indices.</p><div class="odoc-spec"><div class="spec value anchored" id="val-get"><a href="#val-get" class="anchor"></a><code><span><span class="keyword">val</span> get : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> char</span></code></div><div class="spec-doc"><p><code>get cs zidx</code> is the byte of <code>cs</code> at its zero-based index <code>zidx</code>. It's an alias of <a href="#val-get_char"><code>get_char</code></a>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>zidx</code> is not an index of <code>cs</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-get_byte"><a href="#val-get_byte" class="anchor"></a><code><span><span class="keyword">val</span> get_byte : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>get_byte cs zidx</code> is <code>Char.code (get cs zidx)</code>. It's an alias of <a href="#val-get_uint8"><code>get_uint8</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-string"><a href="#val-string" class="anchor"></a><code><span><span class="keyword">val</span> string : <span><span class="optlabel">?off</span>:int <span class="arrow">-></span></span> <span><span class="optlabel">?len</span>:int <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>string ~off ~len str</code> is the subbuffer of <code>str</code> that starts at position <code>off</code> (defaults to <code>0</code>) and stops at position <code>off + len</code> (defaults to <code>String.length str</code>). <code>str</code> is fully-replaced by an fresh allocated <a href="#type-buffer"><code>buffer</code></a>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>off</code> or <code>off + len</code> are not positions of <code>str</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-buffer"><a href="#val-buffer" class="anchor"></a><code><span><span class="keyword">val</span> buffer : <span><span class="optlabel">?off</span>:int <span class="arrow">-></span></span> <span><span class="optlabel">?len</span>:int <span class="arrow">-></span></span> <span><a href="#type-buffer">buffer</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>buffer ~off ~len buffer</code> is the sub-part of <code>buffer</code> that starts at position <code>off</code> (default to <code>0</code>) and stops at position <code>off + len</code> (default to <code>Bigarray.Array1.dim buffer</code>). <code>buffer</code> is used as the base buffer of the returned value (no major-heap allocation are performed).</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>off</code> or <code>off + len</code> are not positions of <code>buffer</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-start_pos"><a href="#val-start_pos" class="anchor"></a><code><span><span class="keyword">val</span> start_pos : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>start_pos cs</code> is <code>cs</code>'s start position in the base <a href="#type-buffer"><code>buffer</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-stop_pos"><a href="#val-stop_pos" class="anchor"></a><code><span><span class="keyword">val</span> stop_pos : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>stop_pos cs</code> is <code>cs</code>'s stop position in the base <a href="#type-buffer"><code>buffer</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-length"><a href="#val-length" class="anchor"></a><code><span><span class="keyword">val</span> length : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p>Returns the length of the current cstruct view. Note that this length is potentially smaller than the actual size of the underlying buffer, as the <code>sub</code> function can construct a smaller view.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-head"><a href="#val-head" class="anchor"></a><code><span><span class="keyword">val</span> head : <span><span class="optlabel">?rev</span>:bool <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>char option</span></span></code></div><div class="spec-doc"><p><code>head cs</code> is <code>Some (get cs h)</code> with <code>h = 0</code> if <code>rev = false</code> (default) or <code>h = length cs - 1</code> if <code>rev = true</code>. <code>None</code> is returned if <code>cs</code> is empty.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-tail"><a href="#val-tail" class="anchor"></a><code><span><span class="keyword">val</span> tail : <span><span class="optlabel">?rev</span>:bool <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>tail cs</code> is <code>cs</code> without its first (<code>rev</code> is <code>false</code>, default) or last (<code>rev</code> is <code>true</code>) byte or <code>cs</code> is empty.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-is_empty"><a href="#val-is_empty" class="anchor"></a><code><span><span class="keyword">val</span> is_empty : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>is_empty cs</code> is <code>length cs = 0</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-is_prefix"><a href="#val-is_prefix" class="anchor"></a><code><span><span class="keyword">val</span> is_prefix : <span><span class="label">affix</span>:<a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>is_prefix ~affix cs</code> is <code>true</code> iff <code>affix.[zidx] = cs.[zidx]</code> for all indices <code>zidx</code> of <code>affix</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-is_suffix"><a href="#val-is_suffix" class="anchor"></a><code><span><span class="keyword">val</span> is_suffix : <span><span class="label">affix</span>:<a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>is_suffix ~affix cs</code> is <code>true</code> iff <code>affix.[n - zidx] = cs.[m - zidx]</code> for all indices <code>zidx</code> of <code>affix</code> with <code>n = length affix - 1</code> and <code>m = length cs - 1</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-is_infix"><a href="#val-is_infix" class="anchor"></a><code><span><span class="keyword">val</span> is_infix : <span><span class="label">affix</span>:<a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>is_infix ~affix cs</code> is <code>true</code> iff there exists an index <code>z</code> in <code>cs</code> such that for all indices <code>zidx</code> of <code>affix</code> we have <code>affix.[zidx] = cs.[z + zidx]</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-for_all"><a href="#val-for_all" class="anchor"></a><code><span><span class="keyword">val</span> for_all : <span><span>(<span>char <span class="arrow">-></span></span> bool)</span> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>for_all p cs</code> is <code>true</code> iff for all indices <code>zidx</code> of <code>cs</code>, <code>p cs.[zidx] = true</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exists"><a href="#val-exists" class="anchor"></a><code><span><span class="keyword">val</span> exists : <span><span>(<span>char <span class="arrow">-></span></span> bool)</span> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>exists p cs</code> is <code>true</code> iff there exists an index <code>zidx</code> of <code>cs</code> with <code>p cs.[zidx] = true</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-start"><a href="#val-start" class="anchor"></a><code><span><span class="keyword">val</span> start : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>start cs</code> is the empty sub-part at the start position of <code>cs</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-stop"><a href="#val-stop" class="anchor"></a><code><span><span class="keyword">val</span> stop : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>stop cs</code> is the empty sub-part at the stop position of <code>cs</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-trim"><a href="#val-trim" class="anchor"></a><code><span><span class="keyword">val</span> trim : <span><span class="optlabel">?drop</span>:<span>(<span>char <span class="arrow">-></span></span> bool)</span> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>trim ~drop cs</code> is <code>cs</code> with prefix and suffix bytes satisfying <code>drop</code> in <code>cs</code> removed. <code>drop</code> defaults to <code>function ' ' | '\r' .. '\t' -> true | _ -> false</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-span"><a href="#val-span" class="anchor"></a><code><span><span class="keyword">val</span> span :
|
||
<span><span class="optlabel">?rev</span>:bool <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?min</span>:int <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?max</span>:int <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?sat</span>:<span>(<span>char <span class="arrow">-></span></span> bool)</span> <span class="arrow">-></span></span>
|
||
<span><a href="#type-t">t</a> <span class="arrow">-></span></span>
|
||
<a href="#type-t">t</a> * <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>span ~rev ~min ~max ~sat cs</code> is <code>(l, r)</code> where:</p><ul><li>if <code>rev</code> is <code>false</code> (default), <code>l</code> is at least <code>min</code> and at most <code>max</code> consecutive <code>sat</code> satisfying initial bytes of <code>cs</code> or <a href="#val-empty"><code>empty</code></a> if there are no such bytes. <code>r</code> are the remaining bytes of <code>cs</code>.</li><li>if <code>rev</code> is <code>true</code>, <code>r</code> is at least <code>min</code> and at most <code>max</code> consecutive <code>sat</code> satisfying final bytes of <code>cs</code> or <a href="#val-empty"><code>empty</code></a> if there are no such bytes. <code>l</code> are the remaining bytes of <code>cs</code>.</li></ul><p>If <code>max</code> is unspecified the span is unlimited. If <code>min</code> is unspecified it defaults to <code>0</code>. If <code>min > max</code> the condition can't be satisfied and the left or right span, depending on <code>rev</code>, is always empty. <code>sat</code> defaults to <code>(fun _ -> true)</code>.</p><p>The invariant <code>l ^ r = s</code> holds.</p><p>For instance, the <i>ABNF</i> expression:</p><pre> time := 1*10DIGIT</pre><p>can be translated to:</p><pre class="language-ocaml"><code> let (time, _) = span ~min:1 ~max:10 is_digit cs in</code></pre><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>max</code> or <code>min</code> is negative.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-take"><a href="#val-take" class="anchor"></a><code><span><span class="keyword">val</span> take : <span><span class="optlabel">?rev</span>:bool <span class="arrow">-></span></span> <span><span class="optlabel">?min</span>:int <span class="arrow">-></span></span> <span><span class="optlabel">?max</span>:int <span class="arrow">-></span></span> <span><span class="optlabel">?sat</span>:<span>(<span>char <span class="arrow">-></span></span> bool)</span> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>take ~rev ~min ~max ~sat cs</code> is the matching span of <a href="#val-span"><code>span</code></a> without the remaining one. In other words:</p><pre class="language-ocaml"><code>(if rev then snd else fst) @@ span ~rev ~min ~max ~sat cs</code></pre></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-drop"><a href="#val-drop" class="anchor"></a><code><span><span class="keyword">val</span> drop : <span><span class="optlabel">?rev</span>:bool <span class="arrow">-></span></span> <span><span class="optlabel">?min</span>:int <span class="arrow">-></span></span> <span><span class="optlabel">?max</span>:int <span class="arrow">-></span></span> <span><span class="optlabel">?sat</span>:<span>(<span>char <span class="arrow">-></span></span> bool)</span> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>drop ~rev ~min ~max ~sat cs</code> is the remaining span of <a href="#val-span"><code>span</code></a> without the matching one. In other words:</p><pre class="language-ocaml"><code>(if rev then fst else snd) @@ span ~rev ~min ~max ~sat cs</code></pre></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-cut"><a href="#val-cut" class="anchor"></a><code><span><span class="keyword">val</span> cut : <span><span class="optlabel">?rev</span>:bool <span class="arrow">-></span></span> <span><span class="label">sep</span>:<a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><span>(<a href="#type-t">t</a> * <a href="#type-t">t</a>)</span> option</span></span></code></div><div class="spec-doc"><p><code>cut ~sep cs</code> is either the pair <code>Some (l, r)</code> of the two (possibly empty) sub-buffers of <code>cs</code> that are delimited by the first match of the non empty separator string <code>sep</code> or <code>None</code> if <code>sep</code> can't be matched in <code>cs</code>. Matching starts from the beginning of <code>cs</code> (<code>rev</code> is <code>false</code>, default) or the end (<code>rev</code> is <code>true</code>).</p><p>The invariant <code>l ^ sep ^ r = s</code> holds.</p><p>For instance, the <i>ABNF</i> expression:</p><pre> field_name := *PRINT
|
||
field_value := *ASCII
|
||
field := field_name ":" field_value</pre><p>can be translated to:</p><pre class="language-ocaml"><code> match cut ~sep:":" value with
|
||
| Some (field_name, field_value) -> ...
|
||
| None -> invalid_arg "invalid field"</code></pre><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>sep</code> is the empty buffer.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-cuts"><a href="#val-cuts" class="anchor"></a><code><span><span class="keyword">val</span> cuts : <span><span class="optlabel">?rev</span>:bool <span class="arrow">-></span></span> <span><span class="optlabel">?empty</span>:bool <span class="arrow">-></span></span> <span><span class="label">sep</span>:<a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> list</span></span></code></div><div class="spec-doc"><p><code>cuts ~sep cs</code> is the list of all sub-buffers of <code>cs</code> that are delimited by matches of the non empty separator <code>sep</code>. Empty sub-buffers are omitted in the list if <code>empty</code> is <code>false</code> (default to <code>true</code>).</p><p>Matching separators in <code>cs</code> starts from the beginning of <code>cs</code> (<code>rev</code> is <code>false</code>, default) or the end (<code>rev</code> is <code>true</code>). Once one is found, the separator is skipped and matching starts again, that is separator matches can't overlap. If there is no separator match in <code>cs</code>, the list <code>[cs]</code> is returned.</p><p>The following invariants hold:</p><ul><li><code>concat ~sep (cuts ~empty:true ~sep cs) = cs</code></li><li><code>cuts ~empty:true ~sep cs <> []</code></li></ul><p>For instance, the <i>ABNF</i> expression:</p><pre> arg := *(ASCII / ",") ; any characters exclude ","
|
||
args := arg *("," arg)</pre><p>can be translated to:</p><pre class="language-ocaml"><code> let args = cuts ~sep:"," buffer in</code></pre><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>sep</code> is the empty buffer.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-fields"><a href="#val-fields" class="anchor"></a><code><span><span class="keyword">val</span> fields : <span><span class="optlabel">?empty</span>:bool <span class="arrow">-></span></span> <span><span class="optlabel">?is_sep</span>:<span>(<span>char <span class="arrow">-></span></span> bool)</span> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> list</span></span></code></div><div class="spec-doc"><p><code>fields ~empty ~is_sep cs</code> is the list of (possibly empty) sub-buffers that are delimited by bytes for which <code>is_sep</code> is <code>true</code>. Empty sub-buffers are omitted in the list if <code>empty</code> is <code>false</code> (defaults to <code>true</code>). <code>is_sep c</code> if it's not define by the user is <code>true</code> iff <code>c</code> is an US-ASCII white space character, that is one of space <code>' '</code> (<code>0x20</code>), tab <code>'\t'</code> (<code>0x09</code>), newline <code>'\n'</code> (<code>0x0a</code>), vertical tab (<code>0x0b</code>), form feed (<code>0x0c</code>), carriage return <code>'\r'</code> (<code>0x0d</code>).</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-find"><a href="#val-find" class="anchor"></a><code><span><span class="keyword">val</span> find : <span><span class="optlabel">?rev</span>:bool <span class="arrow">-></span></span> <span><span>(<span>char <span class="arrow">-></span></span> bool)</span> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> option</span></span></code></div><div class="spec-doc"><p><code>find ~rev sat cs</code> is the sub-buffer of <code>cs</code> (if any) that spans the first byte that satisfies <code>sat</code> in <code>cs</code> after position <code>start cs</code> (<code>rev</code> is <code>false</code>, default) or before <code>stop cs</code> (<code>rev</code> is <code>true</code>). <code>None</code> is returned if there is no matching byte in <code>s</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-find_sub"><a href="#val-find_sub" class="anchor"></a><code><span><span class="keyword">val</span> find_sub : <span><span class="optlabel">?rev</span>:bool <span class="arrow">-></span></span> <span><span class="label">sub</span>:<a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> option</span></span></code></div><div class="spec-doc"><p><code>find_sub ~rev ~sub cs</code> is the sub-buffer of <code>cs</code> (if any) that spans the first match of <code>sub</code> in <code>cs</code> after position <code>start cs</code> (<code>rev</code> is <code>false</code>, default) or before <code>stop cs</code> (<code>rev</code> is <code>true</code>). Only bytes are compared and <code>sub</code> can be on a different base buffer. <code>None</code> is returned if there is no match of <code>sub</code> in <code>s</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-filter"><a href="#val-filter" class="anchor"></a><code><span><span class="keyword">val</span> filter : <span><span>(<span>char <span class="arrow">-></span></span> bool)</span> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>filter sat cs</code> is the buffer made of the bytes of <code>cs</code> that satisfy <code>sat</code>, in the same order.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-filter_map"><a href="#val-filter_map" class="anchor"></a><code><span><span class="keyword">val</span> filter_map : <span><span>(<span>char <span class="arrow">-></span></span> <span>char option</span>)</span> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>filter_map f cs</code> is the buffer made of the bytes of <code>cs</code> as mapped by <code>f</code>, in the same order.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-map"><a href="#val-map" class="anchor"></a><code><span><span class="keyword">val</span> map : <span><span>(<span>char <span class="arrow">-></span></span> char)</span> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>map f cs</code> is <code>cs'</code> with <code>cs'.[i] = f cs.[i]</code> for all indices <code>i</code> of <code>cs</code>. <code>f</code> is invoked in increasing index order.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-mapi"><a href="#val-mapi" class="anchor"></a><code><span><span class="keyword">val</span> mapi : <span><span>(<span>int <span class="arrow">-></span></span> <span>char <span class="arrow">-></span></span> char)</span> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>map f cs</code> is <code>cs'</code> with <code>cs'.[i] = f i cs.[i]</code> for all indices <code>i</code> of <code>cs</code>. <code>f</code> is invoked in increasing index order.</p></div></div></div></body></html>
|