mirror of
https://github.com/c-cube/moonpool.git
synced 2025-12-06 03:05:30 -05:00
21 lines
45 KiB
HTML
21 lines
45 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Lwt_stream (lwt.Lwt_stream)</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">lwt</a> » Lwt_stream</nav><header class="odoc-preamble"><h1>Module <code><span>Lwt_stream</span></code></h1><p>Data streams</p></header><div class="odoc-tocs"><nav class="odoc-toc odoc-local-toc"><ul><li><a href="#construction">Construction</a></li><li><a href="#destruction">Destruction</a></li><li><a href="#data-retrieval">Data retrieval</a><ul><li><a href="#deprecated">Deprecated</a></li></ul></li><li><a href="#stream-transversal">Stream transversal</a></li><li><a href="#parsing">Parsing</a></li><li><a href="#misc">Misc</a></li></ul></nav></div><div class="odoc-content"><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>A stream holding values of type <code>'a</code>.</p><p>Naming convention: in this module, all functions applying a function to each element of a stream are suffixed by:</p><ul><li><code>_s</code> when the function returns a thread and calls are serialised</li><li><code>_p</code> when the function returns a thread and calls are parallelised</li></ul></div></div><h3 id="construction"><a href="#construction" class="anchor"></a>Construction</h3><div class="odoc-spec"><div class="spec value anchored" id="val-from"><a href="#val-from" class="anchor"></a><code><span><span class="keyword">val</span> from : <span><span>(<span>unit <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> option</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <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>from f</code> creates a stream from the given input function. <code>f</code> is called each time more input is needed, and the stream ends when <code>f</code> returns <code>None</code>.</p><p>If <code>f</code>, or the thread produced by <code>f</code>, raises an exception, that exception is forwarded to the consumer of the stream (for example, a caller of <a href="#val-get"><code>get</code></a>). Note that this does not end the stream. A subsequent attempt to read from the stream will cause another call to <code>f</code>, which may succeed with a value.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-from_direct"><a href="#val-from_direct" class="anchor"></a><code><span><span class="keyword">val</span> from_direct : <span><span>(<span>unit <span class="arrow">-></span></span> <span><span class="type-var">'a</span> option</span>)</span> <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>from_direct f</code> does the same as <a href="#val-from"><code>from</code></a> but with a function that does not return a thread. It is preferred that this function be used rather than wrapping <code>f</code> into a function which returns a thread.</p><p>The behavior when <code>f</code> raises an exception is the same as for <a href="#val-from"><code>from</code></a>, except that <code>f</code> does not produce a thread.</p></div></div><div class="odoc-spec"><div class="spec exception anchored" id="exception-Closed"><a href="#exception-Closed" class="anchor"></a><code><span><span class="keyword">exception</span> </span><span><span class="exception">Closed</span></span></code></div><div class="spec-doc"><p>Exception raised by the push function of a push-stream when pushing an element after the end of stream (<code>= None</code>) has been pushed.</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>unit <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span> * <span>(<span><span><span class="type-var">'a</span> option</span> <span class="arrow">-></span></span> unit)</span></span></code></div><div class="spec-doc"><p><code>create ()</code> returns a new stream and a push function.</p><p>To notify the stream's consumer of errors, either use a separate communication channel, or use a <a href="../../ocaml/Stdlib/index.html#type-result"><code>Stdlib.result</code></a> stream. There is no way to push an exception into a push-stream.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-create_with_reference"><a href="#val-create_with_reference" class="anchor"></a><code><span><span class="keyword">val</span> create_with_reference : <span>unit <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span> * <span>(<span><span><span class="type-var">'a</span> option</span> <span class="arrow">-></span></span> unit)</span> * <span>(<span><span class="type-var">'b</span> <span class="arrow">-></span></span> unit)</span></span></code></div><div class="spec-doc"><p><code>create_with_reference ()</code> returns a new stream and a push function. The last function allows a reference to be set to an external source. This prevents the external source from being garbage collected.</p><p>For example, to convert a reactive event to a stream:</p><pre class="language-ocaml"><code> let stream, push, set_ref = Lwt_stream.create_with_reference () in
|
||
set_ref (map_event push event)</code></pre></div></div><div class="odoc-spec"><div class="spec exception anchored" id="exception-Full"><a href="#exception-Full" class="anchor"></a><code><span><span class="keyword">exception</span> </span><span><span class="exception">Full</span></span></code></div><div class="spec-doc"><p>Exception raised by the push function of a bounded push-stream when the stream queue is full and a thread is already waiting to push an element.</p></div></div><div class="odoc-spec"><div class="spec class-type anchored" id="class-type-bounded_push"><a href="#class-type-bounded_push" class="anchor"></a><code><span><span class="keyword">class</span> <span class="keyword">type</span> 'a </span><span><a href="class-type-bounded_push/index.html">bounded_push</a></span><span> = <span class="keyword">object</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>Type of sources for bounded push-streams.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-create_bounded"><a href="#val-create_bounded" class="anchor"></a><code><span><span class="keyword">val</span> create_bounded : <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="class-type-bounded_push/index.html">bounded_push</a></span></span></code></div><div class="spec-doc"><p><code>create_bounded size</code> returns a new stream and a bounded push source. The stream can hold a maximum of <code>size</code> elements. When this limit is reached, pushing a new element will block until one is consumed.</p><p>Note that you cannot clone or parse (with <a href="#val-parse"><code>parse</code></a>) a bounded stream. These functions will raise <code>Invalid_argument</code> if you try to do so.</p><p>It raises <code>Invalid_argument</code> if <code>size < 0</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-return"><a href="#val-return" class="anchor"></a><code><span><span class="keyword">val</span> return : <span><span class="type-var">'a</span> <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>return a</code> creates a stream containing the value <code>a</code> and being immediately closed stream (in the sense of <a href="#val-is_closed"><code>is_closed</code></a>).</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 5.5.0</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-return_lwt"><a href="#val-return_lwt" class="anchor"></a><code><span><span class="keyword">val</span> return_lwt : <span><span><span class="type-var">'a</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span> <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>return_lwt l</code> creates a stream returning the value that <code>l</code> resolves to. The value is pushed into the stream immediately after the promise becomes resolved and the stream is then immediately closed (in the sense of <a href="#val-is_closed"><code>is_closed</code></a>).</p><p>If, instead, <code>l</code> becomes rejected, then the stream is closed without any elements in it. Attempting to fetch elements from it will raise <a href="#exception-Empty"><code>Empty</code></a>.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 5.5.0</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-of_seq"><a href="#val-of_seq" class="anchor"></a><code><span><span class="keyword">val</span> of_seq : <span><span><span class="type-var">'a</span> <a href="../../ocaml/Stdlib/Seq/index.html#type-t">Stdlib.Seq.t</a></span> <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>of_seq s</code> creates a stream returning all elements of <code>s</code>. The elements are evaluated from <code>s</code> and pushed onto the stream as the stream is consumed.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 4.2.0</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-of_lwt_seq"><a href="#val-of_lwt_seq" class="anchor"></a><code><span><span class="keyword">val</span> of_lwt_seq : <span><span><span class="type-var">'a</span> <a href="../Lwt_seq/index.html#type-t">Lwt_seq.t</a></span> <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>of_lwt_seq s</code> creates a stream returning all elements of <code>s</code>. The elements are evaluated from <code>s</code> and pushed onto the stream as the stream is consumed.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 5.5.0</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-of_list"><a href="#val-of_list" class="anchor"></a><code><span><span class="keyword">val</span> of_list : <span><span><span class="type-var">'a</span> list</span> <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>of_list l</code> creates a stream returning all elements of <code>l</code>. The elements are pushed into the stream immediately, resulting in a closed stream (in the sense of <a href="#val-is_closed"><code>is_closed</code></a>).</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-of_array"><a href="#val-of_array" class="anchor"></a><code><span><span class="keyword">val</span> of_array : <span><span><span class="type-var">'a</span> array</span> <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>of_array a</code> creates a stream returning all elements of <code>a</code>. The elements are pushed into the stream immediately, resulting in a closed stream (in the sense of <a href="#val-is_closed"><code>is_closed</code></a>).</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>string <span class="arrow">-></span></span> <span>char <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>of_string str</code> creates a stream returning all characters of <code>str</code>. The characters are pushed into the stream immediately, resulting in a closed stream (in the sense of <a href="#val-is_closed"><code>is_closed</code></a>).</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-clone"><a href="#val-clone" class="anchor"></a><code><span><span class="keyword">val</span> clone : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <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>clone st</code> clone the given stream. Operations on each stream will not affect the other.</p><p>For example:</p><pre class="language-ocaml"><code> # let st1 = Lwt_stream.of_list [1; 2; 3];;
|
||
val st1 : int Lwt_stream.t = <abstr>
|
||
# let st2 = Lwt_stream.clone st1;;
|
||
val st2 : int Lwt_stream.t = <abstr>
|
||
# lwt x = Lwt_stream.next st1;;
|
||
val x : int = 1
|
||
# lwt y = Lwt_stream.next st2;;
|
||
val y : int = 1</code></pre><p>It raises <code>Invalid_argument</code> if <code>st</code> is a bounded push-stream.</p></div></div><h3 id="destruction"><a href="#destruction" class="anchor"></a>Destruction</h3><div class="odoc-spec"><div class="spec value anchored" id="val-to_list"><a href="#val-to_list" class="anchor"></a><code><span><span class="keyword">val</span> to_list : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> list</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p>Returns the list of elements of the given stream</p></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>char <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>string <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p>Returns the word composed of all characters of the given stream</p></div></div><h3 id="data-retrieval"><a href="#data-retrieval" class="anchor"></a>Data retrieval</h3><div class="odoc-spec"><div class="spec exception anchored" id="exception-Empty"><a href="#exception-Empty" class="anchor"></a><code><span><span class="keyword">exception</span> </span><span><span class="exception">Empty</span></span></code></div><div class="spec-doc"><p>Exception raised when trying to retrieve data from an empty stream.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-peek"><a href="#val-peek" class="anchor"></a><code><span><span class="keyword">val</span> peek : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> option</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>peek st</code> returns the first element of the stream, if any, without removing it.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-npeek"><a href="#val-npeek" class="anchor"></a><code><span><span class="keyword">val</span> npeek : <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><span><span class="type-var">'a</span> list</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>npeek n st</code> returns at most the first <code>n</code> elements of <code>st</code>, without removing them.</p></div></div><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><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> option</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>get st</code> removes and returns the first element of the stream, if any.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-nget"><a href="#val-nget" class="anchor"></a><code><span><span class="keyword">val</span> nget : <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><span><span class="type-var">'a</span> list</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>nget n st</code> removes and returns at most the first <code>n</code> elements of <code>st</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-get_while"><a href="#val-get_while" class="anchor"></a><code><span><span class="keyword">val</span> get_while : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> bool)</span> <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><span><span class="type-var">'a</span> list</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-get_while_s"><a href="#val-get_while_s" class="anchor"></a><code><span><span class="keyword">val</span> get_while_s : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span>bool <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <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><span><span class="type-var">'a</span> list</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>get_while f st</code> returns the longest prefix of <code>st</code> where all elements satisfy <code>f</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-next"><a href="#val-next" class="anchor"></a><code><span><span class="keyword">val</span> next : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>next st</code> removes and returns the next element of the stream or fails with <a href="#exception-Empty"><code>Empty</code></a>, if the stream is empty.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-last_new"><a href="#val-last_new" class="anchor"></a><code><span><span class="keyword">val</span> last_new : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>last_new st</code> returns the last element that can be obtained without sleeping, or wait for one if none is available.</p><p>It fails with <a href="#exception-Empty"><code>Empty</code></a> if the stream has no more elements.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-junk"><a href="#val-junk" class="anchor"></a><code><span><span class="keyword">val</span> junk : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>junk st</code> removes the first element of <code>st</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-njunk"><a href="#val-njunk" class="anchor"></a><code><span><span class="keyword">val</span> njunk : <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>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>njunk n st</code> removes at most the first <code>n</code> elements of the stream.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-junk_while"><a href="#val-junk_while" class="anchor"></a><code><span><span class="keyword">val</span> junk_while : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> bool)</span> <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>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-junk_while_s"><a href="#val-junk_while_s" class="anchor"></a><code><span><span class="keyword">val</span> junk_while_s : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span>bool <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <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>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>junk_while f st</code> removes all elements at the beginning of the streams which satisfy <code>f</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-junk_available"><a href="#val-junk_available" class="anchor"></a><code><span><span class="keyword">val</span> junk_available : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>junk_available st</code> removes all elements that are ready to be read without yielding from <code>st</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-get_available"><a href="#val-get_available" class="anchor"></a><code><span><span class="keyword">val</span> get_available : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> list</span></span></code></div><div class="spec-doc"><p><code>get_available st</code> returns all available elements of <code>l</code> without blocking.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-get_available_up_to"><a href="#val-get_available_up_to" class="anchor"></a><code><span><span class="keyword">val</span> get_available_up_to : <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><span class="type-var">'a</span> list</span></span></code></div><div class="spec-doc"><p><code>get_available_up_to n st</code> returns up to <code>n</code> elements of <code>l</code> without blocking.</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 class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>bool <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>is_empty st</code> returns whether the given stream is empty.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-is_closed"><a href="#val-is_closed" class="anchor"></a><code><span><span class="keyword">val</span> is_closed : <span><span><span class="type-var">'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_closed st</code> returns whether the given stream has been closed. A closed stream is not necessarily empty. It may still contain unread elements. If <code>is_closed s = true</code>, then all subsequent reads until the end of the stream are guaranteed not to block.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 2.6.0</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-closed"><a href="#val-closed" class="anchor"></a><code><span><span class="keyword">val</span> closed : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>closed st</code> returns a thread that will sleep until the stream has been closed.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 2.6.0</li></ul></div></div><h4 id="deprecated"><a href="#deprecated" class="anchor"></a>Deprecated</h4><div class="odoc-spec"><div class="spec value anchored" id="val-junk_old"><a href="#val-junk_old" class="anchor"></a><code><span><span class="keyword">val</span> junk_old : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> <p><code>junk_old st</code> is <code>Lwt.return (junk_available st)</code>.</p></li></ul></div></div><h3 id="stream-transversal"><a href="#stream-transversal" class="anchor"></a>Stream transversal</h3><p>Note: all the following functions are destructive.</p><p>For example:</p><pre class="language-ocaml"><code> # let st1 = Lwt_stream.of_list [1; 2; 3];;
|
||
val st1 : int Lwt_stream.t = <abstr>
|
||
# let st2 = Lwt_stream.map string_of_int st1;;
|
||
val st2 : string Lwt_stream.t = <abstr>
|
||
# lwt x = Lwt_stream.next st1;;
|
||
val x : int = 1
|
||
# lwt y = Lwt_stream.next st2;;
|
||
val y : string = "2"</code></pre><div class="odoc-spec"><div class="spec value anchored" id="val-choose"><a href="#val-choose" class="anchor"></a><code><span><span class="keyword">val</span> choose : <span><span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> list</span> <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>choose l</code> creates an stream from a list of streams. The resulting stream will return elements returned by any stream of <code>l</code> in an unspecified 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><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-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-map_s"><a href="#val-map_s" class="anchor"></a><code><span><span class="keyword">val</span> map_s : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <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><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>map f st</code> maps the value returned by <code>st</code> with <code>f</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><span class="type-var">'a</span> <span class="arrow">-></span></span> bool)</span> <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><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-filter_s"><a href="#val-filter_s" class="anchor"></a><code><span><span class="keyword">val</span> filter_s : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span>bool <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <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><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>filter f st</code> keeps only values, <code>x</code>, such that <code>f x</code> is <code>true</code></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><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> option</span>)</span> <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><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-filter_map_s"><a href="#val-filter_map_s" class="anchor"></a><code><span><span class="keyword">val</span> filter_map_s : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'b</span> option</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <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><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>filter_map f st</code> filter and map <code>st</code> at the same time</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-map_list"><a href="#val-map_list" class="anchor"></a><code><span><span class="keyword">val</span> map_list : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> list</span>)</span> <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><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-map_list_s"><a href="#val-map_list_s" class="anchor"></a><code><span><span class="keyword">val</span> map_list_s : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'b</span> list</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <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><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>map_list f st</code> applies <code>f</code> on each element of <code>st</code> and flattens the lists returned</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">'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> <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><span class="type-var">'b</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-fold_s"><a href="#val-fold_s" class="anchor"></a><code><span><span class="keyword">val</span> fold_s : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <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><span class="type-var">'b</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>fold f s x</code> fold_like function for streams.</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 class="type-var">'a</span> <span class="arrow">-></span></span> unit)</span> <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>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-iter_p"><a href="#val-iter_p" class="anchor"></a><code><span><span class="keyword">val</span> iter_p : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <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>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-iter_s"><a href="#val-iter_s" class="anchor"></a><code><span><span class="keyword">val</span> iter_s : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <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>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>iter f s</code> iterates over all elements of the stream.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-iter_n"><a href="#val-iter_n" class="anchor"></a><code><span><span class="keyword">val</span> iter_n : <span><span class="optlabel">?max_concurrency</span>:int <span class="arrow">-></span></span> <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <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>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>iter_n ?max_concurrency f s</code> iterates over all elements of the stream <code>s</code>. Iteration is performed concurrently with up to <code>max_threads</code> concurrent instances of <code>f</code>.</p><p>Iteration is <b>not</b> guaranteed to be in order as this function will attempt to always process <code>max_concurrency</code> elements from <code>s</code> at once.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">max_concurrency</span> <p>defaults to <code>1</code>.</p></li></ul><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>max_concurrency < 1</code>.</p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 3.3.0</li></ul></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>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> bool)</span> <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><span><span class="type-var">'a</span> option</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-find_s"><a href="#val-find_s" class="anchor"></a><code><span><span class="keyword">val</span> find_s : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span>bool <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <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><span><span class="type-var">'a</span> option</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>find f s</code> find an element in a stream.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-find_map"><a href="#val-find_map" class="anchor"></a><code><span><span class="keyword">val</span> find_map : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> option</span>)</span> <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><span><span class="type-var">'b</span> option</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-find_map_s"><a href="#val-find_map_s" class="anchor"></a><code><span><span class="keyword">val</span> find_map_s : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'b</span> option</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <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><span><span class="type-var">'b</span> option</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>find_map f s</code> find and map at the same time.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-combine"><a href="#val-combine" class="anchor"></a><code><span><span class="keyword">val</span> combine : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'b</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span>(<span class="type-var">'a</span> * <span class="type-var">'b</span>)</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>combine s1 s2</code> combines two streams. The stream will end when either stream ends.</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><span><span class="type-var">'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-t">t</a></span> <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>append s1 s2</code> returns a stream which returns all elements of <code>s1</code>, then all elements of <code>s2</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><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <a href="#type-t">t</a></span> <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>concat st</code> returns the concatenation of all streams of <code>st</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-flatten"><a href="#val-flatten" class="anchor"></a><code><span><span class="keyword">val</span> flatten : <span><span><span><span class="type-var">'a</span> list</span> <a href="#type-t">t</a></span> <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>flatten st = map_list (fun l -> l) st</code></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wrap_exn"><a href="#val-wrap_exn" class="anchor"></a><code><span><span class="keyword">val</span> wrap_exn : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span>(<span class="type-var">'a</span>, exn)</span> <a href="../../ocaml/Stdlib/index.html#type-result">result</a></span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>wrap_exn s</code> is a stream <code>s'</code> such that each time <code>s</code> yields a value <code>v</code>, <code>s'</code> yields <code>Result.Ok v</code>, and when the source of <code>s</code> raises an exception <code>e</code>, <code>s'</code> yields <code>Result.Error e</code>.</p><p>Note that push-streams (as returned by <a href="#val-create"><code>create</code></a>) never raise exceptions.</p><p>If the stream source keeps raising the same exception <code>e</code> each time the stream is read, <code>s'</code> is unbounded. Reading it will produce <code>Result.Error e</code> indefinitely.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 2.7.0</li></ul></div></div><h3 id="parsing"><a href="#parsing" class="anchor"></a>Parsing</h3><div class="odoc-spec"><div class="spec value anchored" id="val-parse"><a href="#val-parse" class="anchor"></a><code><span><span class="keyword">val</span> parse : <span><span><span class="type-var">'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-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>parse st f</code> parses <code>st</code> with <code>f</code>. If <code>f</code> raise an exception, <code>st</code> is restored to its previous state.</p><p>It raises <code>Invalid_argument</code> if <code>st</code> is a bounded push-stream.</p></div></div><h3 id="misc"><a href="#misc" class="anchor"></a>Misc</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><span>char <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>string <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>hexdump byte_stream</code> returns a stream which is the same as the output of <code>hexdump -C</code>.</p><p>Basically, here is a simple implementation of <code>hexdump -C</code>:</p><pre class="language-ocaml"><code> let () = Lwt_main.run begin
|
||
Lwt_io.write_lines
|
||
Lwt_io.stdout
|
||
(Lwt_stream.hexdump (Lwt_io.read_lines Lwt_io.stdin))
|
||
end</code></pre></div></div></div></body></html>
|