mirror of
https://github.com/ocaml-tracing/ocaml-opentelemetry.git
synced 2026-05-06 01:15:11 -04:00
48 lines
69 KiB
HTML
48 lines
69 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Cstruct_cap (cstruct.Cstruct_cap)</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_cap</nav><header class="odoc-preamble"><h1>Module <code><span>Cstruct_cap</span></code></h1><p>Raw memory buffers with capabilities</p><p><code>Cstruct_cap</code> wraps OCaml Stdlib's <a href="http://caml.inria.fr/pub/docs/manual-ocaml/libref/Bigarray.html">Bigarray</a> module. Each <code>t</code> consists of a proxy (consisting of offset, length, and the actual <code>Bigarray.t</code> buffer). The goal of this module is two-fold: enable zero-copy - the underlying buffer is shared by most of the functions - and static checking of read and write capabilities to the underlying buffer (using phantom types).</p><p>Each <code>'a t</code> is parameterized by the available capabilities: read (<code>rd</code>) and write (<code>wr</code>): to access the contents of the buffer the <code>read</code> capability is necessary, for modifying the content of the buffer the <code>write</code> capability is necessary. Capabilities can only be dropped, never gained, to a buffer. If code only has read capability, this does not mean that there is no other code fragment with write capability to the underlying buffer.</p><p>The functions that retrieve bytes (<a href="#val-get_uint8"><code>get_uint8</code></a> etc.) require a <code>read</code> capability, functions mutating the underlying buffer (<a href="#val-set_uint8"><code>set_uint8</code></a> etc.) require a <code>write</code> capability. Allocation of a buffer (via <a href="#val-create"><code>create</code></a>, ...) returns a <code>t</code> with read and write capabilities. <a href="#val-ro"><code>ro</code></a> drops the write capability, <a href="#val-wo"><code>wo</code></a> drops the read capability. The only exception is <a href="#val-unsafe_to_bigarray"><code>unsafe_to_bigarray</code></a> that returns the underlying <code>Bigarray.t</code>.</p><p>Accessors and mutators for fixed size integers (8, 16, 32, 64 bit) are provided for big-endian and little-endian encodings.</p></header><div class="odoc-tocs"><nav class="odoc-toc odoc-local-toc"><ul><li><a href="#types">Types</a></li><li><a href="#capabilities">Capabilities</a></li><li><a href="#basic-operations">Basic operations</a></li><li><a href="#constructors">Constructors</a></li><li><a href="#subviews">Subviews</a></li><li><a href="#construction-from-existing-t">Construction from existing t</a></li><li><a href="#mutation-of-the-underlying-buffer">Mutation of the underlying buffer</a></li><li><a href="#converters:-string,-bytes,-bigarray">Converters: string, bytes, bigarray</a></li><li><a href="#higher-order-functions">Higher order functions</a></li><li><a href="#accessors-and-mutators">Accessors and mutators</a></li><li><a href="#helpers-to-parse-with-capabilities.">Helpers to parse with capabilities.</a></li></ul></nav></div><div class="odoc-content"><h3 id="types"><a href="#types" class="anchor"></a>Types</h3><div class="odoc-spec"><div class="spec type anchored" id="type-rd"><a href="#type-rd" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a rd</span></span><span> = <span>< rd : unit.. ></span> <span class="keyword">as</span> 'a</span></code></div><div class="spec-doc"><p>Type of read capability.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-wr"><a href="#type-wr" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a wr</span></span><span> = <span>< wr : unit.. ></span> <span class="keyword">as</span> 'a</span></code></div><div class="spec-doc"><p>Type of write capability.</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> <span>'a t</span></span></code></div><div class="spec-doc"><p>Type of cstruct with capabilities <code>'a</code>.</p></div></div><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 buffer. A <a href="#type-t"><code>t</code></a> is composed of an underlying buffer.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-rdwr"><a href="#type-rdwr" class="anchor"></a><code><span><span class="keyword">type</span> rdwr</span><span> = <span>< rd : unit ; wr : unit ></span></span></code></div><div class="spec-doc"><p>Type of both read and write capability.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-ro"><a href="#type-ro" class="anchor"></a><code><span><span class="keyword">type</span> ro</span><span> = <span>< rd : unit ></span></span></code></div><div class="spec-doc"><p>Type of only read capability.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-wo"><a href="#type-wo" class="anchor"></a><code><span><span class="keyword">type</span> wo</span><span> = <span>< wr : unit ></span></span></code></div><div class="spec-doc"><p>Type of only write capability.</p></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.</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.</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.</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.</p></div></div><h3 id="capabilities"><a href="#capabilities" class="anchor"></a>Capabilities</h3><div class="odoc-spec"><div class="spec value anchored" id="val-ro"><a href="#val-ro" class="anchor"></a><code><span><span class="keyword">val</span> ro : <span><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><a href="#type-ro">ro</a> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>ro t</code> is <code>t'</code> with only read capability.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wo"><a href="#val-wo" class="anchor"></a><code><span><span class="keyword">val</span> wo : <span><span><span><span class="type-var">'a</span> <a href="#type-wr">wr</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><a href="#type-wo">wo</a> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>wo t</code> is <code>t'</code> with only write capability.</p></div></div><h3 id="basic-operations"><a href="#basic-operations" class="anchor"></a>Basic operations</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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span><span class="type-var">'b</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>equal a b</code> is <code>true</code> iff <code>a</code> and <code>b</code> correspond to the same sequence of bytes (it uses <code>memcmp</code> internally). Both <code>a</code> and <code>b</code> need at least read capability <a href="#type-rd"><code>rd</code></a>.</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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span><span class="type-var">'b</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>compare a b</code> gives an unspecified total ordering over <a href="#type-t"><code>t</code></a>. Both <code>a</code> and <code>b</code> need at least read capability <a href="#type-rd"><code>rd</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-pp"><a href="#val-pp" class="anchor"></a><code><span><span class="keyword">val</span> pp : <span><a href="../../ocaml/Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a> <span class="arrow">-></span></span> <span><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>pp ppf t</code> pretty-prints <code>t</code> on <code>ppf</code>. <code>t</code> needs read capability <a href="#type-rd"><code>rd</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><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>length t</code> return length of <code>t</code>. Note that this length is potentially smaller than the actual size of the underlying buffer, as functions such as <a href="#val-sub"><code>sub</code></a>, <a href="#val-shift"><code>shift</code></a>, and <a href="#val-split"><code>split</code></a> can construct a smaller view.</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><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>check_alignment t alignment</code> is <code>true</code> if the first byte stored in the underlying buffer of <code>t</code> is at a memory address where <code>address mod alignment = 0</code>, <code>false</code> otherwise. The <code>mod</code> used has the C/OCaml semantic (which differs from Python). 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-lenv"><a href="#val-lenv" class="anchor"></a><code><span><span class="keyword">val</span> lenv : <span><span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> list</span> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>lenv vs</code> is the combined length of all <a href="#type-t"><code>t</code></a> in <code>vs</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><h3 id="constructors"><a href="#constructors" class="anchor"></a>Constructors</h3><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> <span><a href="#type-rdwr">rdwr</a> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>create len</code> allocates a buffer and proxy with both read and write capabilities of size <code>len</code>. It is 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> <span><a href="#type-rdwr">rdwr</a> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>create_unsafe len</code> allocates a buffer and proxy with both read and write capabilities of size <code>len</code>.</p><p>Note that the returned <code>t</code> 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><h3 id="subviews"><a href="#subviews" class="anchor"></a>Subviews</h3><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><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="label">off</span>:int <span class="arrow">-></span></span> <span><span class="label">len</span>:int <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>sub t ~off ~len</code> returns a proxy which shares the underlying buffer of <code>t</code>. It is sliced at offset <code>off</code> and of length <code>len</code>. The returned value has the same capabilities as <code>t</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the offset exceeds <code>t</code> 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><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="label">off</span>:int <span class="arrow">-></span></span> <span><span class="label">len</span>:int <span class="arrow">-></span></span> <span><a href="#type-rdwr">rdwr</a> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>sub_copy t ~off ~len</code> is a new copy of <code>sub t ~off ~len</code>, that does not share the underlying buffer of <code>t</code>. The returned value has read-write capabilities because it doesn't affect <code>t</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the offset exceeds <code>t</code> 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><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>shift t len</code> returns a proxy which shares the underlying buffer of <code>t</code>. The returned value starts <code>len</code> bytes later than the given <code>t</code>. The returned value has the same capabilities as <code>t</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the offset exceeds <code>t</code> length.</p></li></ul></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><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> list</span> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> 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><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><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span> * <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>split ~start t len</code> returns two proxies extracted from <code>t</code>. The first starts at offset <code>start</code> (default <code>0</code>), and is of length <code>len</code>. The second is the remainder of <code>t</code>. The underlying buffer is shared, the capabilities are preserved.</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 length of <code>t</code>, or if there is a bounds violation of <code>t</code> via <code>len + start</code>.</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><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <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 same as <code>Cstruct.to_string cstr ~off ~len</code>.</p><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><h3 id="construction-from-existing-t"><a href="#construction-from-existing-t" class="anchor"></a>Construction from existing t</h3><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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span><span class="type-var">'b</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><a href="#type-rdwr">rdwr</a> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>append a b</code> allocates a buffer <code>r</code> of size <code>length a + length b</code>. Then the content of <code>a</code> is copied at the start of the buffer <code>r</code>, and <code>b</code> is copied behind <code>a</code>'s end in <code>r</code>. <code>a</code> and <code>b</code> need at least read capability <a href="#type-rd"><code>rd</code></a>, the returned value has both read and write capabilities.</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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> list</span> <span class="arrow">-></span></span> <span><a href="#type-rdwr">rdwr</a> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>concat vss</code> allocates a buffer <code>r</code> of size <code>lenv vss</code>. Each <code>v</code> of <code>vss</code> is copied into the buffer <code>r</code>. Each <code>v</code> of <code>vss</code> need at least read capability <a href="#type-rd"><code>rd</code></a>, the returned value has both read and write capabilities.</p></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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> list</span> <span class="arrow">-></span></span> <span><span class="label">dst</span>:<span><span><span class="type-var">'b</span> <a href="#type-wr">wr</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> int * <span><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> 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. It returns the number of bytes copied and the remaining data from <code>src</code>, if any. This is useful if you want to <i>bufferize</i> data into fixed-sized chunks. Each <a href="#type-t"><code>t</code></a> of <code>src</code> need at least read capability <a href="#type-rd"><code>rd</code></a>. <code>dst</code> needs at least write capability <a href="#type-wr"><code>wr</code></a>.</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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><a href="#type-rdwr">rdwr</a> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>rev t</code> allocates a buffer <code>r</code> of size <code>length t</code>, and fills it with the bytes of <code>t</code> in reverse order. The given <code>t</code> needs at least read capability <a href="#type-rd"><code>rd</code></a>, the returned value has both read and write capabilities.</p></div></div><h3 id="mutation-of-the-underlying-buffer"><a href="#mutation-of-the-underlying-buffer" class="anchor"></a>Mutation of the underlying buffer</h3><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><span><span><span class="type-var">'a</span> <a href="#type-wr">wr</a></span> <a href="#type-t">t</a></span> <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 bytes of <code>t</code> to <code>x land 0xFF</code>. <code>t</code> needs at least write capability <a href="#type-wr"><code>wr</code></a>.</p></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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="label">src_off</span>:int <span class="arrow">-></span></span> <span><span><span><span class="type-var">'b</span> <a href="#type-wr">wr</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="label">dst_off</span>:int <span class="arrow">-></span></span> <span><span class="label">len</span>:int <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>blit src ~src_off dst ~dst_off ~len</code> copies <code>len</code> bytes from <code>src</code> starting at index <code>src_off</code> to <code>dst</code> starting at index <code>dst_off</code>. It works correctly even if <code>src</code> and <code>dst</code> refer to the same underlying buffer, and the <code>src</code> and <code>dst</code> intervals overlap. This function uses <code>memmove</code> internally.</p><p><code>src</code> needs at least read capability <a href="#type-rd"><code>rd</code></a>. <code>dst</code> needs at least write capability <a href="#type-wr"><code>wr</code></a>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>src_off</code> and <code>len</code> do not designate a valid segment of <code>src</code>, or if <code>dst_off</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><span class="label">src_off</span>:int <span class="arrow">-></span></span>
|
||
<span><span><span><span class="type-var">'a</span> <a href="#type-wr">wr</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span>
|
||
<span><span class="label">dst_off</span>:int <span class="arrow">-></span></span>
|
||
<span><span class="label">len</span>:int <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><p><code>blit_from_string src ~src_off dst ~dst_off ~len</code> copies <code>len</code> byres from <code>src</code> starting at index <code>src_off</code> to <code>dst</code> starting at index <code>dst_off</code>. This function uses <code>memcpy</code> internally.</p><p><code>dst</code> needs at least write capability <a href="#type-wr"><code>wr</code></a>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>src_off</code> and <code>len</code> do not designate a valid sub-string of <code>src</code>, or if <code>dst_off</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><span class="label">src_off</span>:int <span class="arrow">-></span></span>
|
||
<span><span><span><span class="type-var">'a</span> <a href="#type-wr">wr</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span>
|
||
<span><span class="label">dst_off</span>:int <span class="arrow">-></span></span>
|
||
<span><span class="label">len</span>:int <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><p><code>blit_from_bytes src ~src_off dst ~dst_off ~len</code> copies <code>len</code> bytes from <code>src</code> starting at index <code>src_off</code> to <code>dst</code> starting at index <code>dst_off</code>. This uses <code>memcpy</code> internally.</p><p><code>dst</code> needs at least write capability <a href="#type-wr"><code>wr</code></a>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>src_off</code> and <code>len</code> do not designate a valid sub-sequence of <code>src</code>, or if <code>dst_off</code> and <code>len</code> do no designate a valid segment of <code>dst</code>.</p></li></ul></div></div><h3 id="converters:-string,-bytes,-bigarray"><a href="#converters:-string,-bytes,-bigarray" class="anchor"></a>Converters: string, bytes, bigarray</h3><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">?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> <span><a href="#type-rdwr">rdwr</a> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>of_string ~off ~len s</code> allocates a buffer and copies the contents of <code>s</code> into it starting at offset <code>off</code> (default <code>0</code>) and of length <code>len</code> (default <code>String.length s - off</code>). The returned value has both read and write capabilities.</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> does not designate a valid segment of <code>s</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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p><code>to_string ~off ~len t</code> is the string representation of the segment of <code>t</code> starting at <code>off</code> (default <code>0</code>) of size <code>len</code> (default <code>length t - off</code>). <code>t</code> needs at least read capability <a href="#type-rd"><code>rd</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> and <code>len</code> does not designate a valid segment of <code>t</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><span><span><span class="type-var">_</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <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>. See <a href="../Cstruct/index.html#val-to_hex_string"><code>Cstruct.to_hex_string</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-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> <span><a href="#type-rdwr">rdwr</a> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>of_hex ~off ~len s</code> allocates a buffer and copies the content of <code>s</code> starting at offset <code>off</code> (default <code>0</code>) of length <code>len</code> (default <code>String.length s - off</code>), decoding the hex-encoded characters. Whitespaces in the string are ignored, every pair of hex-encoded characters in <code>s</code> are converted to one byte in the returned <a href="#type-t"><code>t</code></a>, which is exactly half the size of the non-whitespace characters of <code>s</code> from <code>off</code> of length <code>len</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>is the input string contains invalid characters or an off number of non-whitespace characters.</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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> list</span> <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p><code>copy vs</code> is the string representation of the concatenation of all <a href="#type-t"><code>t</code></a> in <code>vs</code>. Each <a href="#type-t"><code>t</code></a> need at least read capability <a href="#type-rd"><code>rd</code></a>.</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-of_bytes"><a href="#val-of_bytes" class="anchor"></a><code><span><span class="keyword">val</span> of_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>bytes <span class="arrow">-></span></span> <span><a href="#type-rdwr">rdwr</a> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>of_bytes ~off ~len b</code> allocates a buffer and copies the contents of <code>b</code> into it starting at offset <code>off</code> (default <code>0</code>) and of length <code>len</code> (default <code>Bytes.length b - off</code>). The returned value has both read and write capabilities.</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> does not designate a valid segment of <code>s</code>.</p></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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> bytes</span></code></div><div class="spec-doc"><p><code>to_bytes ~off ~len t</code> is the bytes representation of the segment of <code>t</code> starting at <code>off</code> (default <code>0</code>) of size <code>len</code> (default <code>length t - off</code>). <code>t</code> needs at least read capability <a href="#type-rd"><code>rd</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> and <code>len</code> do not designate a valid segment of <code>t</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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span>
|
||
<span><span class="label">src_off</span>:int <span class="arrow">-></span></span>
|
||
<span>bytes <span class="arrow">-></span></span>
|
||
<span><span class="label">dst_off</span>:int <span class="arrow">-></span></span>
|
||
<span><span class="label">len</span>:int <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><p><code>blit_to_bytes src ~src_off dst ~dst_off ~len</code> copies length <code>len</code> bytes from <code>src</code>, starting at index <code>src_off</code>, to sequences <code>dst</code>, starting at index <code>dst_off</code>. <code>blit_to_bytes</code> uses <code>memcpy</code> internally.</p><p><code>src</code> needs at least read capability <a href="#type-rd"><code>rd</code></a>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>src_off</code> and <code>len</code> do not designate a valid segment of <code>src</code>, or if <code>dst_off</code> and <code>len</code> do not designate a valid sub-seuqnce of <code>dst</code>.</p></li></ul></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> <span><a href="#type-rdwr">rdwr</a> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>of_bigarray ~off ~len b</code> is a proxy that contains <code>b</code> with offset <code>off</code> (default <code>0</code>) of length <code>len</code> (default <code>Bigarray.Array1.dim b - off</code>). The returned value has both read and write capabilties.</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>b</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-unsafe_to_bigarray"><a href="#val-unsafe_to_bigarray" class="anchor"></a><code><span><span class="keyword">val</span> unsafe_to_bigarray : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <a href="#type-buffer">buffer</a></span></code></div><div class="spec-doc"><p><code>unsafe_to_bigarray t</code> converts <code>t</code> into a <a href="#type-buffer"><code>buffer</code></a> Bigarray, using the Bigarray slicing to allocate a fresh <i>proxy</i> Bigarray that preserves sharing of the underlying buffer.</p><p>In other words:</p><pre class="language-ocaml"><code>let t = Cstruct_cap.create 10 in
|
||
let b = Cstruct_cap.unsafe_to_bigarray t in
|
||
Bigarray.Array1.set b 0 '\x42' ;
|
||
assert (Cstruct_cap.get_char t 0 = '\x42')</code></pre></div></div><h3 id="higher-order-functions"><a href="#higher-order-functions" class="anchor"></a>Higher order functions</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 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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>int option</span>)</span> <span class="arrow">-></span></span> <span><span>(<span><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span class="type-var">'v</span>)</span> <span class="arrow">-></span></span> <span><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'v</span> <a href="#type-iter">iter</a></span></span></code></div><div class="spec-doc"><p><code>iter lenf of_cstruct t</code> is an iterator over <code>t</code> that returns elements of size <code>lenf t</code> and type <code>of_cstruct t</code>. <code>t</code> needs at least read capability <a href="#type-rd"><code>rd</code></a> and <code>iter</code> keeps capabilities of <code>t</code> on <code>of_cstruct</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">'acc</span> <span class="arrow">-></span></span> <span><span class="type-var">'x</span> <span class="arrow">-></span></span> <span class="type-var">'acc</span>)</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'x</span> <a href="#type-iter">iter</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'acc</span> <span class="arrow">-></span></span> <span class="type-var">'acc</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><h3 id="accessors-and-mutators"><a href="#accessors-and-mutators" class="anchor"></a>Accessors and mutators</h3><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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <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 <code>t</code> at offset <code>off</code>. <code>t</code> needs at least read capability <a href="#type-rd"><code>rd</code></a>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the offset exceeds <code>t</code> 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><span><span><span class="type-var">'a</span> <a href="#type-wr">wr</a></span> <a href="#type-t">t</a></span> <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 character contained in <code>t</code> at offset <code>off</code> to character <code>c</code>. <code>t</code> needs at least write capability <a href="#type-wr"><code>wr</code></a>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the offset exceeds <code>t</code> 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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <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 <code>t</code> at offset <code>off</code>. <code>t</code> needs at least read capability <a href="#type-rd"><code>rd</code></a>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the offset exceeds <code>t</code> 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><span><span><span class="type-var">'a</span> <a href="#type-wr">wr</a></span> <a href="#type-t">t</a></span> <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 x</code> sets the byte contained in <code>t</code> at offset <code>off</code> to byte <code>x</code>. <code>t</code> needs at least write capability <a href="#type-wr"><code>wr</code></a>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if the offset exceeds <code>t</code> length.</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><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><h3 id="helpers-to-parse-with-capabilities."><a href="#helpers-to-parse-with-capabilities." class="anchor"></a>Helpers to parse with capabilities.</h3><p>As <code>Cstruct</code>, capabilities interface provides helpers functions to help the user to parse contents.</p><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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span></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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <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>:<span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <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>:<span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <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>:<span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span></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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span></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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span></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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span>
|
||
<span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> * <span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span></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-is_empty"><code>is_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-is_empty"><code>is_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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span>
|
||
<span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span></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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span>
|
||
<span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span></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>:<span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span>(<span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> * <span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span>)</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>:<span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> 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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> 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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> 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>:<span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> 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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span></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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><a href="#type-rdwr">rdwr</a> <a href="#type-t">t</a></span></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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><a href="#type-rdwr">rdwr</a> <a href="#type-t">t</a></span></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><span><span><span class="type-var">'a</span> <a href="#type-rd">rd</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><a href="#type-rdwr">rdwr</a> <a href="#type-t">t</a></span></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>
|