simon/linol
1
0
Fork 0
mirror of https://github.com/c-cube/linol.git synced 2025-12-06 11:15:46 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions
linol/lwt/Lwt_stream/index.html
c-cube e99e434bc2 deploy: 0cb0185797
2024-05-08 15:15:46 +00:00

21 lines
44 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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 2.4.2"/><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">lwt</a> &#x00BB; Lwt_stream</nav><header class="odoc-preamble"><h1>Module <code><span>Lwt_stream</span></code></h1><p>Data streams</p></header><nav class="odoc-toc"><ul><li><a href="#construction">Construction</a></li><li><a href="#destruction">Destruction</a></li><li><a href="#data-retrieval">Data retrieval</a></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 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">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</span></span> <span><span class="type-var">'a</span> option</span>)</span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</span></span> unit)</span> * <span>(<span><span class="type-var">'b</span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</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 &lt; 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">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</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 = &lt;abstr&gt;
# let st2 = Lwt_stream.clone st1;;
val st2 : int Lwt_stream.t = &lt;abstr&gt;
# 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">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> bool)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> <span>bool <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> bool)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> <span>bool <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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_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">&#45;&gt;</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_old 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">&#45;&gt;</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">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</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><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 = &lt;abstr&gt;
# let st2 = Lwt_stream.map string_of_int st1;;
val st2 : string Lwt_stream.t = &lt;abstr&gt;
# lwt x = Lwt_stream.next st1;;
val x : int = 1
# lwt y = Lwt_stream.next st2;;
val y : string = &quot;2&quot;</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">&#45;&gt;</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">&#45;&gt;</span></span> <span class="type-var">'b</span>)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> <span><span class="type-var">'b</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> bool)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> <span>bool <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> <span><span class="type-var">'b</span> option</span>)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> <span><span class="type-var">'b</span> list</span>)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> <span><span class="type-var">'b</span> <span class="arrow">&#45;&gt;</span></span> <span class="type-var">'b</span>)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> <span><span class="type-var">'b</span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> <span><span class="type-var">'b</span> <span class="arrow">&#45;&gt;</span></span> <span><span class="type-var">'b</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> <span><span class="type-var">'b</span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> unit)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> <span>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> <span>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> <span><span>(<span><span class="type-var">'a</span> <span class="arrow">&#45;&gt;</span></span> <span>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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 &lt; 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">&#45;&gt;</span></span> bool)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> <span>bool <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> <span><span class="type-var">'b</span> option</span>)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> <span><span><span class="type-var">'b</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</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">&#45;&gt;</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 -&gt; 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">&#45;&gt;</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">&#45;&gt;</span></span> <span><span>(<span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> <span><span class="type-var">'b</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <span class="arrow">&#45;&gt;</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">&#45;&gt;</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>
Reference in a new issue View git blame Copy permalink