225 lines
29 KiB
HTML
225 lines
29 KiB
HTML
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="An extension trait which adds utility methods to `AsyncBufRead` types."><title>AsyncBufReadExt in tokio::io - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2"href="../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../static.files/rustdoc-ca0dd0c4.css"><meta name="rustdoc-vars" data-root-path="../../" data-static-root-path="../../static.files/" data-current-crate="tokio" data-themes="" data-resource-suffix="" data-rustdoc-version="1.93.1 (01f6ddf75 2026-02-11) (Arch Linux rust 1:1.93.1-1)" data-channel="1.93.1" data-search-js="search-9e2438ea.js" data-stringdex-js="stringdex-a3946164.js" data-settings-js="settings-c38705f0.js" ><script src="../../static.files/storage-e2aeef58.js"></script><script defer src="sidebar-items.js"></script><script defer src="../../static.files/main-a410ff4d.js"></script><noscript><link rel="stylesheet" href="../../static.files/noscript-263c88ec.css"></noscript><link rel="alternate icon" type="image/png" href="../../static.files/favicon-32x32-eab170b8.png"><link rel="icon" type="image/svg+xml" href="../../static.files/favicon-044be391.svg"></head><body class="rustdoc trait"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><rustdoc-topbar><h2><a href="#">AsyncBufReadExt</a></h2></rustdoc-topbar><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../tokio/index.html">tokio</a><span class="version">1.49.0</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">Async<wbr>BufRead<wbr>Ext</a></h2><h3><a href="#provided-methods">Provided Methods</a></h3><ul class="block"><li><a href="#method.consume" title="consume">consume</a></li><li><a href="#method.fill_buf" title="fill_buf">fill_buf</a></li><li><a href="#method.lines" title="lines">lines</a></li><li><a href="#method.read_line" title="read_line">read_line</a></li><li><a href="#method.read_until" title="read_until">read_until</a></li><li><a href="#method.split" title="split">split</a></li></ul><h3><a href="#dyn-compatibility">Dyn Compatibility</a></h3><h3><a href="#implementors">Implementors</a></h3></section><div id="rustdoc-modnav"><h2><a href="index.html">In tokio::<wbr>io</a></h2></div></div></nav><div class="sidebar-resizer" title="Drag to resize sidebar"></div><main><div class="width-limiter"><section id="main-content" class="content"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../index.html">tokio</a>::<wbr><a href="index.html">io</a></div><h1>Trait <span class="trait">Async<wbr>BufRead<wbr>Ext</span> <button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../../src/tokio/io/util/async_buf_read_ext.rs.html#12-354">Source</a> </span></div><pre class="rust item-decl"><code>pub trait AsyncBufReadExt: <a class="trait" href="trait.AsyncBufRead.html" title="trait tokio::io::AsyncBufRead">AsyncBufRead</a> {
|
||
// Provided methods
|
||
fn <a href="#method.read_until" class="fn">read_until</a><'a>(
|
||
&'a mut self,
|
||
byte: <a class="primitive" href="https://doc.rust-lang.org/1.93.1/std/primitive.u8.html">u8</a>,
|
||
buf: &'a mut <a class="struct" href="https://doc.rust-lang.org/1.93.1/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a><<a class="primitive" href="https://doc.rust-lang.org/1.93.1/std/primitive.u8.html">u8</a>>,
|
||
) -> ReadUntil<'a, Self>
|
||
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Unpin.html" title="trait core::marker::Unpin">Unpin</a></span> { ... }
|
||
<span class="item-spacer"></span> fn <a href="#method.read_line" class="fn">read_line</a><'a>(&'a mut self, buf: &'a mut <a class="struct" href="https://doc.rust-lang.org/1.93.1/alloc/string/struct.String.html" title="struct alloc::string::String">String</a>) -> ReadLine<'a, Self>
|
||
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Unpin.html" title="trait core::marker::Unpin">Unpin</a></span> { ... }
|
||
<span class="item-spacer"></span> fn <a href="#method.split" class="fn">split</a>(self, byte: <a class="primitive" href="https://doc.rust-lang.org/1.93.1/std/primitive.u8.html">u8</a>) -> <a class="struct" href="struct.Split.html" title="struct tokio::io::Split">Split</a><Self>
|
||
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a> + <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Unpin.html" title="trait core::marker::Unpin">Unpin</a></span> { ... }
|
||
<span class="item-spacer"></span> fn <a href="#method.fill_buf" class="fn">fill_buf</a>(&mut self) -> FillBuf<'_, Self>
|
||
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Unpin.html" title="trait core::marker::Unpin">Unpin</a></span> { ... }
|
||
<span class="item-spacer"></span> fn <a href="#method.consume" class="fn">consume</a>(&mut self, amt: <a class="primitive" href="https://doc.rust-lang.org/1.93.1/std/primitive.usize.html">usize</a>)
|
||
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Unpin.html" title="trait core::marker::Unpin">Unpin</a></span> { ... }
|
||
<span class="item-spacer"></span> fn <a href="#method.lines" class="fn">lines</a>(self) -> <a class="struct" href="struct.Lines.html" title="struct tokio::io::Lines">Lines</a><Self>
|
||
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
|
||
}</code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>An extension trait which adds utility methods to <a href="trait.AsyncBufRead.html" title="trait tokio::io::AsyncBufRead"><code>AsyncBufRead</code></a> types.</p>
|
||
</div></details><h2 id="provided-methods" class="section-header">Provided Methods<a href="#provided-methods" class="anchor">§</a></h2><div class="methods"><details class="toggle method-toggle" open><summary><section id="method.read_until" class="method"><a class="src rightside" href="../../src/tokio/io/util/async_buf_read_ext.rs.html#96-101">Source</a><h4 class="code-header">fn <a href="#method.read_until" class="fn">read_until</a><'a>(
|
||
&'a mut self,
|
||
byte: <a class="primitive" href="https://doc.rust-lang.org/1.93.1/std/primitive.u8.html">u8</a>,
|
||
buf: &'a mut <a class="struct" href="https://doc.rust-lang.org/1.93.1/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a><<a class="primitive" href="https://doc.rust-lang.org/1.93.1/std/primitive.u8.html">u8</a>>,
|
||
) -> ReadUntil<'a, Self><div class="where">where
|
||
Self: <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Unpin.html" title="trait core::marker::Unpin">Unpin</a>,</div></h4></section></summary><div class="docblock"><p>Reads all bytes into <code>buf</code> until the delimiter <code>byte</code> or EOF is reached.</p>
|
||
<p>Equivalent to:</p>
|
||
|
||
<div class="example-wrap ignore"><a href="#" class="tooltip" title="This example is not tested">ⓘ</a><pre class="rust rust-example-rendered"><code><span class="kw">async fn </span>read_until(<span class="kw-2">&mut </span><span class="self">self</span>, byte: u8, buf: <span class="kw-2">&mut </span>Vec<u8>) -> io::Result<usize>;</code></pre></div>
|
||
<p>This function will read bytes from the underlying stream until the
|
||
delimiter or EOF is found. Once found, all bytes up to, and including,
|
||
the delimiter (if found) will be appended to <code>buf</code>.</p>
|
||
<p>If successful, this function will return the total number of bytes read.</p>
|
||
<p>If this function returns <code>Ok(0)</code>, the stream has reached EOF.</p>
|
||
<h5 id="errors"><a class="doc-anchor" href="#errors">§</a>Errors</h5>
|
||
<p>This function will ignore all instances of <a href="https://doc.rust-lang.org/1.93.1/std/io/error/enum.ErrorKind.html#variant.Interrupted" title="variant std::io::error::ErrorKind::Interrupted"><code>ErrorKind::Interrupted</code></a> and
|
||
will otherwise return any errors returned by <a href="trait.AsyncBufRead.html#tymethod.poll_fill_buf" title="method tokio::io::AsyncBufRead::poll_fill_buf"><code>fill_buf</code></a>.</p>
|
||
<p>If an I/O error is encountered then all bytes read so far will be
|
||
present in <code>buf</code> and its length will have been adjusted appropriately.</p>
|
||
<h5 id="cancel-safety"><a class="doc-anchor" href="#cancel-safety">§</a>Cancel safety</h5>
|
||
<p>If the method is used as the event in a
|
||
<a href="../macro.select.html" title="macro tokio::select"><code>tokio::select!</code></a> statement and some other branch
|
||
completes first, then some data may have been partially read. Any
|
||
partially read bytes are appended to <code>buf</code>, and the method can be
|
||
called again to continue reading until <code>byte</code>.</p>
|
||
<p>This method returns the total number of bytes read. If you cancel
|
||
the call to <code>read_until</code> and then call it again to continue reading,
|
||
the counter is reset.</p>
|
||
<h5 id="examples"><a class="doc-anchor" href="#examples">§</a>Examples</h5>
|
||
<p><a href="https://doc.rust-lang.org/1.93.1/std/io/cursor/struct.Cursor.html" title="struct std::io::cursor::Cursor"><code>std::io::Cursor</code></a> is a type that implements <code>BufRead</code>. In
|
||
this example, we use <a href="https://doc.rust-lang.org/1.93.1/std/io/cursor/struct.Cursor.html" title="struct std::io::cursor::Cursor"><code>Cursor</code></a> to read all the bytes in a byte slice
|
||
in hyphen delimited segments:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>tokio::io::AsyncBufReadExt;
|
||
|
||
<span class="kw">use </span>std::io::Cursor;
|
||
|
||
<span class="kw">let </span><span class="kw-2">mut </span>cursor = Cursor::new(<span class="string">b"lorem-ipsum"</span>);
|
||
<span class="kw">let </span><span class="kw-2">mut </span>buf = <span class="macro">vec!</span>[];
|
||
|
||
<span class="comment">// cursor is at 'l'
|
||
</span><span class="kw">let </span>num_bytes = cursor.read_until(<span class="string">b'-'</span>, <span class="kw-2">&mut </span>buf)
|
||
.<span class="kw">await
|
||
</span>.expect(<span class="string">"reading from cursor won't fail"</span>);
|
||
|
||
<span class="macro">assert_eq!</span>(num_bytes, <span class="number">6</span>);
|
||
<span class="macro">assert_eq!</span>(buf, <span class="string">b"lorem-"</span>);
|
||
buf.clear();
|
||
|
||
<span class="comment">// cursor is at 'i'
|
||
</span><span class="kw">let </span>num_bytes = cursor.read_until(<span class="string">b'-'</span>, <span class="kw-2">&mut </span>buf)
|
||
.<span class="kw">await
|
||
</span>.expect(<span class="string">"reading from cursor won't fail"</span>);
|
||
|
||
<span class="macro">assert_eq!</span>(num_bytes, <span class="number">5</span>);
|
||
<span class="macro">assert_eq!</span>(buf, <span class="string">b"ipsum"</span>);
|
||
buf.clear();
|
||
|
||
<span class="comment">// cursor is at EOF
|
||
</span><span class="kw">let </span>num_bytes = cursor.read_until(<span class="string">b'-'</span>, <span class="kw-2">&mut </span>buf)
|
||
.<span class="kw">await
|
||
</span>.expect(<span class="string">"reading from cursor won't fail"</span>);
|
||
<span class="macro">assert_eq!</span>(num_bytes, <span class="number">0</span>);
|
||
<span class="macro">assert_eq!</span>(buf, <span class="string">b""</span>);</code></pre></div></div></details><details class="toggle method-toggle" open><summary><section id="method.read_line" class="method"><a class="src rightside" href="../../src/tokio/io/util/async_buf_read_ext.rs.html#199-204">Source</a><h4 class="code-header">fn <a href="#method.read_line" class="fn">read_line</a><'a>(&'a mut self, buf: &'a mut <a class="struct" href="https://doc.rust-lang.org/1.93.1/alloc/string/struct.String.html" title="struct alloc::string::String">String</a>) -> ReadLine<'a, Self><div class="where">where
|
||
Self: <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Unpin.html" title="trait core::marker::Unpin">Unpin</a>,</div></h4></section></summary><div class="docblock"><p>Reads all bytes until a newline (the 0xA byte) is reached, and append
|
||
them to the provided buffer.</p>
|
||
<p>Equivalent to:</p>
|
||
|
||
<div class="example-wrap ignore"><a href="#" class="tooltip" title="This example is not tested">ⓘ</a><pre class="rust rust-example-rendered"><code><span class="kw">async fn </span>read_line(<span class="kw-2">&mut </span><span class="self">self</span>, buf: <span class="kw-2">&mut </span>String) -> io::Result<usize>;</code></pre></div>
|
||
<p>This function will read bytes from the underlying stream until the
|
||
newline delimiter (the 0xA byte) or EOF is found. Once found, all bytes
|
||
up to, and including, the delimiter (if found) will be appended to
|
||
<code>buf</code>.</p>
|
||
<p>If successful, this function will return the total number of bytes read.</p>
|
||
<p>If this function returns <code>Ok(0)</code>, the stream has reached EOF.</p>
|
||
<h5 id="errors-1"><a class="doc-anchor" href="#errors-1">§</a>Errors</h5>
|
||
<p>This function has the same error semantics as <a href="trait.AsyncBufReadExt.html#method.read_until" title="method tokio::io::AsyncBufReadExt::read_until"><code>read_until</code></a> and will
|
||
also return an error if the read bytes are not valid UTF-8. If an I/O
|
||
error is encountered then <code>buf</code> may contain some bytes already read in
|
||
the event that all data read so far was valid UTF-8.</p>
|
||
<h5 id="cancel-safety-1"><a class="doc-anchor" href="#cancel-safety-1">§</a>Cancel safety</h5>
|
||
<p>This method is not cancellation safe. If the method is used as the
|
||
event in a <a href="../macro.select.html" title="macro tokio::select"><code>tokio::select!</code></a> statement and some
|
||
other branch completes first, then some data may have been partially
|
||
read, and this data is lost. There are no guarantees regarding the
|
||
contents of <code>buf</code> when the call is cancelled. The current
|
||
implementation replaces <code>buf</code> with the empty string, but this may
|
||
change in the future.</p>
|
||
<p>This function does not behave like <a href="trait.AsyncBufReadExt.html#method.read_until" title="method tokio::io::AsyncBufReadExt::read_until"><code>read_until</code></a> because of the
|
||
requirement that a string contains only valid utf-8. If you need a
|
||
cancellation safe <code>read_line</code>, there are three options:</p>
|
||
<ul>
|
||
<li>Call <a href="trait.AsyncBufReadExt.html#method.read_until" title="method tokio::io::AsyncBufReadExt::read_until"><code>read_until</code></a> with a newline character and manually perform the utf-8 check.</li>
|
||
<li>The stream returned by <a href="trait.AsyncBufReadExt.html#method.lines"><code>lines</code></a> has a cancellation safe
|
||
<a href="struct.Lines.html#method.next_line" title="method tokio::io::Lines::next_line"><code>next_line</code></a> method.</li>
|
||
<li>Use <a href="https://docs.rs/tokio-util/latest/tokio_util/codec/struct.LinesCodec.html"><code>tokio_util::codec::LinesCodec</code></a>.</li>
|
||
</ul>
|
||
<h5 id="examples-1"><a class="doc-anchor" href="#examples-1">§</a>Examples</h5>
|
||
<p><a href="https://doc.rust-lang.org/1.93.1/std/io/cursor/struct.Cursor.html" title="struct std::io::cursor::Cursor"><code>std::io::Cursor</code></a> is a type that implements
|
||
<code>AsyncBufRead</code>. In this example, we use <a href="https://doc.rust-lang.org/1.93.1/std/io/cursor/struct.Cursor.html" title="struct std::io::cursor::Cursor"><code>Cursor</code></a> to read all the
|
||
lines in a byte slice:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>tokio::io::AsyncBufReadExt;
|
||
|
||
<span class="kw">use </span>std::io::Cursor;
|
||
|
||
<span class="kw">let </span><span class="kw-2">mut </span>cursor = Cursor::new(<span class="string">b"foo\nbar"</span>);
|
||
<span class="kw">let </span><span class="kw-2">mut </span>buf = String::new();
|
||
|
||
<span class="comment">// cursor is at 'f'
|
||
</span><span class="kw">let </span>num_bytes = cursor.read_line(<span class="kw-2">&mut </span>buf)
|
||
.<span class="kw">await
|
||
</span>.expect(<span class="string">"reading from cursor won't fail"</span>);
|
||
|
||
<span class="macro">assert_eq!</span>(num_bytes, <span class="number">4</span>);
|
||
<span class="macro">assert_eq!</span>(buf, <span class="string">"foo\n"</span>);
|
||
buf.clear();
|
||
|
||
<span class="comment">// cursor is at 'b'
|
||
</span><span class="kw">let </span>num_bytes = cursor.read_line(<span class="kw-2">&mut </span>buf)
|
||
.<span class="kw">await
|
||
</span>.expect(<span class="string">"reading from cursor won't fail"</span>);
|
||
|
||
<span class="macro">assert_eq!</span>(num_bytes, <span class="number">3</span>);
|
||
<span class="macro">assert_eq!</span>(buf, <span class="string">"bar"</span>);
|
||
buf.clear();
|
||
|
||
<span class="comment">// cursor is at EOF
|
||
</span><span class="kw">let </span>num_bytes = cursor.read_line(<span class="kw-2">&mut </span>buf)
|
||
.<span class="kw">await
|
||
</span>.expect(<span class="string">"reading from cursor won't fail"</span>);
|
||
|
||
<span class="macro">assert_eq!</span>(num_bytes, <span class="number">0</span>);
|
||
<span class="macro">assert_eq!</span>(buf, <span class="string">""</span>);</code></pre></div></div></details><details class="toggle method-toggle" open><summary><section id="method.split" class="method"><a class="src rightside" href="../../src/tokio/io/util/async_buf_read_ext.rs.html#240-245">Source</a><h4 class="code-header">fn <a href="#method.split" class="fn">split</a>(self, byte: <a class="primitive" href="https://doc.rust-lang.org/1.93.1/std/primitive.u8.html">u8</a>) -> <a class="struct" href="struct.Split.html" title="struct tokio::io::Split">Split</a><Self><div class="where">where
|
||
Self: <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a> + <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Unpin.html" title="trait core::marker::Unpin">Unpin</a>,</div></h4></section></summary><div class="docblock"><p>Returns a stream of the contents of this reader split on the byte
|
||
<code>byte</code>.</p>
|
||
<p>This method is the asynchronous equivalent to
|
||
<a href="https://doc.rust-lang.org/1.93.1/std/io/trait.BufRead.html#method.split" title="method std::io::BufRead::split"><code>BufRead::split</code></a>.</p>
|
||
<p>The stream returned from this function will yield instances of
|
||
<a href="https://doc.rust-lang.org/1.93.1/std/io/error/type.Result.html" title="type std::io::error::Result"><code>io::Result</code></a><code><</code><a href="https://doc.rust-lang.org/1.93.1/core/option/enum.Option.html" title="enum core::option::Option"><code>Option</code></a><code><</code><a href="https://doc.rust-lang.org/1.93.1/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec"><code>Vec<u8></code></a><code>>></code>. Each vector returned will <em>not</em> have
|
||
the delimiter byte at the end.</p>
|
||
<h5 id="errors-2"><a class="doc-anchor" href="#errors-2">§</a>Errors</h5>
|
||
<p>Each item of the stream has the same error semantics as
|
||
<a href="trait.AsyncBufReadExt.html#method.read_until" title="method tokio::io::AsyncBufReadExt::read_until"><code>AsyncBufReadExt::read_until</code></a>.</p>
|
||
<h5 id="examples-2"><a class="doc-anchor" href="#examples-2">§</a>Examples</h5>
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>tokio::io::AsyncBufReadExt;
|
||
|
||
<span class="kw">let </span><span class="kw-2">mut </span>segments = my_buf_read.split(<span class="string">b'f'</span>);
|
||
|
||
<span class="kw">while let </span><span class="prelude-val">Some</span>(segment) = segments.next_segment().<span class="kw">await</span><span class="question-mark">? </span>{
|
||
<span class="macro">println!</span>(<span class="string">"length = {}"</span>, segment.len())
|
||
}</code></pre></div></div></details><details class="toggle method-toggle" open><summary><section id="method.fill_buf" class="method"><a class="src rightside" href="../../src/tokio/io/util/async_buf_read_ext.rs.html#277-282">Source</a><h4 class="code-header">fn <a href="#method.fill_buf" class="fn">fill_buf</a>(&mut self) -> FillBuf<'_, Self><div class="where">where
|
||
Self: <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Unpin.html" title="trait core::marker::Unpin">Unpin</a>,</div></h4></section></summary><div class="docblock"><p>Returns the contents of the internal buffer, filling it with more
|
||
data from the inner reader if it is empty.</p>
|
||
<p>This function is a lower-level call. It needs to be paired with the
|
||
<a href="trait.AsyncBufReadExt.html#method.consume" title="method tokio::io::AsyncBufReadExt::consume"><code>consume</code></a> method to function properly. When calling this method,
|
||
none of the contents will be “read” in the sense that later calling
|
||
<code>read</code> may return the same contents. As such, <a href="trait.AsyncBufReadExt.html#method.consume" title="method tokio::io::AsyncBufReadExt::consume"><code>consume</code></a> must be
|
||
called with the number of bytes that are consumed from this buffer
|
||
to ensure that the bytes are never returned twice.</p>
|
||
<p>An empty buffer returned indicates that the stream has reached EOF.</p>
|
||
<p>Equivalent to:</p>
|
||
|
||
<div class="example-wrap ignore"><a href="#" class="tooltip" title="This example is not tested">ⓘ</a><pre class="rust rust-example-rendered"><code><span class="kw">async fn </span>fill_buf(<span class="kw-2">&mut </span><span class="self">self</span>) -> io::Result<<span class="kw-2">&</span>[u8]>;</code></pre></div><h5 id="errors-3"><a class="doc-anchor" href="#errors-3">§</a>Errors</h5>
|
||
<p>This function will return an I/O error if the underlying reader was
|
||
read, but returned an error.</p>
|
||
<h5 id="cancel-safety-2"><a class="doc-anchor" href="#cancel-safety-2">§</a>Cancel safety</h5>
|
||
<p>This method is cancel safe. If you use it as the event in a
|
||
<a href="../macro.select.html" title="macro tokio::select"><code>tokio::select!</code></a> statement and some other branch
|
||
completes first, then it is guaranteed that no data was read.</p>
|
||
</div></details><details class="toggle method-toggle" open><summary><section id="method.consume" class="method"><a class="src rightside" href="../../src/tokio/io/util/async_buf_read_ext.rs.html#299-304">Source</a><h4 class="code-header">fn <a href="#method.consume" class="fn">consume</a>(&mut self, amt: <a class="primitive" href="https://doc.rust-lang.org/1.93.1/std/primitive.usize.html">usize</a>)<div class="where">where
|
||
Self: <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Unpin.html" title="trait core::marker::Unpin">Unpin</a>,</div></h4></section></summary><div class="docblock"><p>Tells this buffer that <code>amt</code> bytes have been consumed from the
|
||
buffer, so they should no longer be returned in calls to <a href="trait.AsyncReadExt.html#method.read" title="method tokio::io::AsyncReadExt::read"><code>read</code></a>.</p>
|
||
<p>This function is a lower-level call. It needs to be paired with the
|
||
<a href="trait.AsyncBufReadExt.html#method.fill_buf" title="method tokio::io::AsyncBufReadExt::fill_buf"><code>fill_buf</code></a> method to function properly. This function does not
|
||
perform any I/O, it simply informs this object that some amount of
|
||
its buffer, returned from <a href="trait.AsyncBufReadExt.html#method.fill_buf" title="method tokio::io::AsyncBufReadExt::fill_buf"><code>fill_buf</code></a>, has been consumed and should
|
||
no longer be returned. As such, this function may do odd things if
|
||
<a href="trait.AsyncBufReadExt.html#method.fill_buf" title="method tokio::io::AsyncBufReadExt::fill_buf"><code>fill_buf</code></a> isn’t called before calling it.</p>
|
||
<p>The <code>amt</code> must be less than the number of bytes in the buffer
|
||
returned by <a href="trait.AsyncBufReadExt.html#method.fill_buf" title="method tokio::io::AsyncBufReadExt::fill_buf"><code>fill_buf</code></a>.</p>
|
||
</div></details><details class="toggle method-toggle" open><summary><section id="method.lines" class="method"><a class="src rightside" href="../../src/tokio/io/util/async_buf_read_ext.rs.html#348-353">Source</a><h4 class="code-header">fn <a href="#method.lines" class="fn">lines</a>(self) -> <a class="struct" href="struct.Lines.html" title="struct tokio::io::Lines">Lines</a><Self><div class="where">where
|
||
Self: <a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Returns a stream over the lines of this reader.
|
||
This method is the async equivalent to <a href="https://doc.rust-lang.org/1.93.1/std/io/trait.BufRead.html#method.lines" title="method std::io::BufRead::lines"><code>BufRead::lines</code></a>.</p>
|
||
<p>The stream returned from this function will yield instances of
|
||
<a href="https://doc.rust-lang.org/1.93.1/std/io/error/type.Result.html" title="type std::io::error::Result"><code>io::Result</code></a><code><</code><a href="https://doc.rust-lang.org/1.93.1/core/option/enum.Option.html" title="enum core::option::Option"><code>Option</code></a><code><</code><a href="https://doc.rust-lang.org/1.93.1/alloc/string/struct.String.html" title="struct alloc::string::String"><code>String</code></a><code>>></code>. Each string returned will <em>not</em> have a newline
|
||
byte (the 0xA byte) or <code>CRLF</code> (0xD, 0xA bytes) at the end.</p>
|
||
<h5 id="errors-4"><a class="doc-anchor" href="#errors-4">§</a>Errors</h5>
|
||
<p>Each line of the stream has the same error semantics as <a href="trait.AsyncBufReadExt.html#method.read_line" title="method tokio::io::AsyncBufReadExt::read_line"><code>AsyncBufReadExt::read_line</code></a>.</p>
|
||
<h5 id="examples-3"><a class="doc-anchor" href="#examples-3">§</a>Examples</h5>
|
||
<p><a href="https://doc.rust-lang.org/1.93.1/std/io/cursor/struct.Cursor.html" title="struct std::io::cursor::Cursor"><code>std::io::Cursor</code></a> is a type that implements <code>BufRead</code>. In
|
||
this example, we use <a href="https://doc.rust-lang.org/1.93.1/std/io/cursor/struct.Cursor.html" title="struct std::io::cursor::Cursor"><code>Cursor</code></a> to iterate over all the lines in a byte
|
||
slice.</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>tokio::io::AsyncBufReadExt;
|
||
|
||
<span class="kw">use </span>std::io::Cursor;
|
||
|
||
<span class="kw">let </span>cursor = Cursor::new(<span class="string">b"lorem\nipsum\r\ndolor"</span>);
|
||
|
||
<span class="kw">let </span><span class="kw-2">mut </span>lines = cursor.lines();
|
||
|
||
<span class="macro">assert_eq!</span>(lines.next_line().<span class="kw">await</span>.unwrap(), <span class="prelude-val">Some</span>(String::from(<span class="string">"lorem"</span>)));
|
||
<span class="macro">assert_eq!</span>(lines.next_line().<span class="kw">await</span>.unwrap(), <span class="prelude-val">Some</span>(String::from(<span class="string">"ipsum"</span>)));
|
||
<span class="macro">assert_eq!</span>(lines.next_line().<span class="kw">await</span>.unwrap(), <span class="prelude-val">Some</span>(String::from(<span class="string">"dolor"</span>)));
|
||
<span class="macro">assert_eq!</span>(lines.next_line().<span class="kw">await</span>.unwrap(), <span class="prelude-val">None</span>);</code></pre></div></div></details></div><h2 id="dyn-compatibility" class="section-header">Dyn Compatibility<a href="#dyn-compatibility" class="anchor">§</a></h2><div class="dyn-compatibility-info"><p>This trait is <b>not</b> <a href="https://doc.rust-lang.org/1.93.1/reference/items/traits.html#dyn-compatibility">dyn compatible</a>.</p><p><i>In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.</i></p></div><h2 id="implementors" class="section-header">Implementors<a href="#implementors" class="anchor">§</a></h2><div id="implementors-list"><section id="impl-AsyncBufReadExt-for-R" class="impl"><a class="src rightside" href="../../src/tokio/io/util/async_buf_read_ext.rs.html#357">Source</a><a href="#impl-AsyncBufReadExt-for-R" class="anchor">§</a><h3 class="code-header">impl<R: <a class="trait" href="trait.AsyncBufRead.html" title="trait tokio::io::AsyncBufRead">AsyncBufRead</a> + ?<a class="trait" href="https://doc.rust-lang.org/1.93.1/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>> <a class="trait" href="trait.AsyncBufReadExt.html" title="trait tokio::io::AsyncBufReadExt">AsyncBufReadExt</a> for R</h3></section></div><script src="../../trait.impl/tokio/io/util/async_buf_read_ext/trait.AsyncBufReadExt.js" async></script></section></div></main></body></html> |