danvics/oxipng
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
oxipng/doc/bitflags/__core/io/trait.Read.html

447 lines
No EOL
40 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 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="API documentation for the Rust `Read` trait in crate `bitflags`.">
<meta name="keywords" content="rust, rustlang, rust-lang, Read">
<title>bitflags::__core::io::Read - Rust</title>
<link rel="stylesheet" type="text/css" href="../../../rustdoc.css">
<link rel="stylesheet" type="text/css" href="../../../main.css">
</head>
<body class="rustdoc">
<!--[if lte IE 8]>
<div class="warning">
This old browser is unsupported and will most likely display funky
things.
</div>
<![endif]-->
<nav class="sidebar">
<p class='location'><a href='../../index.html'>bitflags</a>::<wbr><a href='../index.html'>__core</a>::<wbr><a href='index.html'>io</a></p><script>window.sidebarCurrent = {name: 'Read', ty: 'trait', relpath: ''};</script><script defer src="sidebar-items.js"></script>
</nav>
<nav class="sub">
<form class="search-form js-only">
<div class="search-container">
<input class="search-input" name="search"
autocomplete="off"
placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
type="search">
</div>
</form>
</nav>
<section id='main' class="content trait">
<h1 class='fqn'><span class='in-band'>Trait <a href='../../index.html'>bitflags</a>::<wbr><a href='../index.html'>__core</a>::<wbr><a href='index.html'>io</a>::<wbr><a class='trait' href=''>Read</a></span><span class='out-of-band'><span id='render-detail'>
<a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
[<span class='inner'>&#x2212;</span>]
</a>
</span><a id='src-4830' class='srclink' href='https://doc.rust-lang.org/nightly/std/io/trait.Read.html?gotosrc=4830' title='goto source code'>[src]</a></span></h1>
<pre class='rust trait'>pub trait Read {
fn <a href='#tymethod.read' class='fnname'>read</a>(&amp;mut self, buf: <a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.slice.html'>&amp;mut [</a><a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.u8.html'>u8</a><a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.slice.html'>]</a>) -&gt; <a class='enum' href='../../../bitflags/__core/result/enum.Result.html' title='bitflags::__core::result::Result'>Result</a>&lt;<a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.usize.html'>usize</a>, <a class='struct' href='../../../bitflags/__core/io/struct.Error.html' title='bitflags::__core::io::Error'>Error</a>&gt;;
fn <a href='#method.read_to_end' class='fnname'>read_to_end</a>(&amp;mut self, buf: &amp;mut <a class='struct' href='../../../bitflags/__core/vec/struct.Vec.html' title='bitflags::__core::vec::Vec'>Vec</a>&lt;<a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.u8.html'>u8</a>&gt;) -&gt; <a class='enum' href='../../../bitflags/__core/result/enum.Result.html' title='bitflags::__core::result::Result'>Result</a>&lt;<a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.usize.html'>usize</a>, <a class='struct' href='../../../bitflags/__core/io/struct.Error.html' title='bitflags::__core::io::Error'>Error</a>&gt; { ... }
fn <a href='#method.read_to_string' class='fnname'>read_to_string</a>(&amp;mut self, buf: &amp;mut <a class='struct' href='../../../bitflags/__core/string/struct.String.html' title='bitflags::__core::string::String'>String</a>) -&gt; <a class='enum' href='../../../bitflags/__core/result/enum.Result.html' title='bitflags::__core::result::Result'>Result</a>&lt;<a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.usize.html'>usize</a>, <a class='struct' href='../../../bitflags/__core/io/struct.Error.html' title='bitflags::__core::io::Error'>Error</a>&gt; { ... }
fn <a href='#method.read_exact' class='fnname'>read_exact</a>(&amp;mut self, buf: <a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.slice.html'>&amp;mut [</a><a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.u8.html'>u8</a><a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.slice.html'>]</a>) -&gt; <a class='enum' href='../../../bitflags/__core/result/enum.Result.html' title='bitflags::__core::result::Result'>Result</a>&lt;<a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.tuple.html'>()</a>, <a class='struct' href='../../../bitflags/__core/io/struct.Error.html' title='bitflags::__core::io::Error'>Error</a>&gt; { ... }
fn <a href='#method.by_ref' class='fnname'>by_ref</a>(&amp;mut self) -&gt; &amp;mut Self { ... }
fn <a href='#method.bytes' class='fnname'>bytes</a>(self) -&gt; <a class='struct' href='../../../bitflags/__core/io/struct.Bytes.html' title='bitflags::__core::io::Bytes'>Bytes</a>&lt;Self&gt; { ... }
fn <a href='#method.chars' class='fnname'>chars</a>(self) -&gt; <a class='struct' href='../../../bitflags/__core/io/struct.Chars.html' title='bitflags::__core::io::Chars'>Chars</a>&lt;Self&gt; { ... }
fn <a href='#method.chain' class='fnname'>chain</a>&lt;R&gt;(self, next: R) -&gt; <a class='struct' href='../../../bitflags/__core/io/struct.Chain.html' title='bitflags::__core::io::Chain'>Chain</a>&lt;Self, R&gt; <span class='where'>where R: <a class='trait' href='../../../bitflags/__core/io/trait.Read.html' title='bitflags::__core::io::Read'>Read</a></span> { ... }
fn <a href='#method.take' class='fnname'>take</a>(self, limit: <a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.u64.html'>u64</a>) -&gt; <a class='struct' href='../../../bitflags/__core/io/struct.Take.html' title='bitflags::__core::io::Take'>Take</a>&lt;Self&gt; { ... }
}</pre><div class='docblock'><p>The <code>Read</code> trait allows for reading bytes from a source.</p>
<p>Implementors of the <code>Read</code> trait are sometimes called &#39;readers&#39;.</p>
<p>Readers are defined by one required method, <code>read()</code>. Each call to <code>read</code>
will attempt to pull bytes from this source into a provided buffer. A
number of other methods are implemented in terms of <code>read()</code>, giving
implementors a number of ways to read bytes while only needing to implement
a single method.</p>
<p>Readers are intended to be composable with one another. Many implementors
throughout <code>std::io</code> take and provide types which implement the <code>Read</code>
trait.</p>
<p>Please note that each call to <code>read</code> may involve a system call, and
therefore, using something that implements <a href="trait.BufRead.html"><code>BufRead</code></a>, such as
<a href="struct.BufReader.html"><code>BufReader</code></a>, will be more efficient.</p>
<h1 id='examples' class='section-header'><a href='#examples'>Examples</a></h1>
<p><a href="../fs/struct.File.html"><code>File</code></a>s implement <code>Read</code>:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>::<span class='ident'>prelude</span>::<span class='op'>*</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>fs</span>::<span class='ident'>File</span>;
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>f</span> <span class='op'>=</span> <span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>File</span>::<span class='ident'>open</span>(<span class='string'>&quot;foo.txt&quot;</span>));
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>buffer</span> <span class='op'>=</span> [<span class='number'>0</span>; <span class='number'>10</span>];
<span class='comment'>// read up to 10 bytes</span>
<span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>f</span>.<span class='ident'>read</span>(<span class='kw-2'>&amp;</span><span class='kw-2'>mut</span> <span class='ident'>buffer</span>));
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>buffer</span> <span class='op'>=</span> <span class='macro'>vec</span><span class='macro'>!</span>[<span class='number'>0</span>; <span class='number'>10</span>];
<span class='comment'>// read the whole file</span>
<span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>f</span>.<span class='ident'>read_to_end</span>(<span class='kw-2'>&amp;</span><span class='kw-2'>mut</span> <span class='ident'>buffer</span>));
<span class='comment'>// read into a String, so that you don&#39;t need to do the conversion.</span>
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>buffer</span> <span class='op'>=</span> <span class='ident'>String</span>::<span class='ident'>new</span>();
<span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>f</span>.<span class='ident'>read_to_string</span>(<span class='kw-2'>&amp;</span><span class='kw-2'>mut</span> <span class='ident'>buffer</span>));
<span class='comment'>// and more! See the other methods for more details.</span></pre>
</div>
<h2 id='required-methods'>Required Methods</h2>
<div class='methods'>
<h3 id='tymethod.read' class='method stab '><code>fn <a href='#tymethod.read' class='fnname'>read</a>(&amp;mut self, buf: <a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.slice.html'>&amp;mut [</a><a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.u8.html'>u8</a><a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.slice.html'>]</a>) -&gt; <a class='enum' href='../../../bitflags/__core/result/enum.Result.html' title='bitflags::__core::result::Result'>Result</a>&lt;<a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.usize.html'>usize</a>, <a class='struct' href='../../../bitflags/__core/io/struct.Error.html' title='bitflags::__core::io::Error'>Error</a>&gt;</code></h3><div class='docblock'><p>Pull some bytes from this source into the specified buffer, returning
how many bytes were read.</p>
<p>This function does not provide any guarantees about whether it blocks
waiting for data, but if an object needs to block for a read but cannot
it will typically signal this via an <code>Err</code> return value.</p>
<p>If the return value of this method is <code>Ok(n)</code>, then it must be
guaranteed that <code>0 &lt;= n &lt;= buf.len()</code>. A nonzero <code>n</code> value indicates
that the buffer <code>buf</code> has been filled in with <code>n</code> bytes of data from this
source. If <code>n</code> is <code>0</code>, then it can indicate one of two scenarios:</p>
<ol>
<li>This reader has reached its &quot;end of file&quot; and will likely no longer
be able to produce bytes. Note that this does not mean that the
reader will <em>always</em> no longer be able to produce bytes.</li>
<li>The buffer specified was 0 bytes in length.</li>
</ol>
<p>No guarantees are provided about the contents of <code>buf</code> when this
function is called, implementations cannot rely on any property of the
contents of <code>buf</code> being true. It is recommended that implementations
only write data to <code>buf</code> instead of reading its contents.</p>
<h1 id='errors' class='section-header'><a href='#errors'>Errors</a></h1>
<p>If this function encounters any form of I/O or other error, an error
variant will be returned. If an error is returned then it must be
guaranteed that no bytes were read.</p>
<h1 id='examples-1' class='section-header'><a href='#examples-1'>Examples</a></h1>
<p><a href="../fs/struct.File.html"><code>File</code></a>s implement <code>Read</code>:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>::<span class='ident'>prelude</span>::<span class='op'>*</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>fs</span>::<span class='ident'>File</span>;
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>f</span> <span class='op'>=</span> <span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>File</span>::<span class='ident'>open</span>(<span class='string'>&quot;foo.txt&quot;</span>));
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>buffer</span> <span class='op'>=</span> [<span class='number'>0</span>; <span class='number'>10</span>];
<span class='comment'>// read 10 bytes</span>
<span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>f</span>.<span class='ident'>read</span>(<span class='kw-2'>&amp;</span><span class='kw-2'>mut</span> <span class='ident'>buffer</span>[..]));</pre>
</div></div>
<h2 id='provided-methods'>Provided Methods</h2>
<div class='methods'>
<h3 id='method.read_to_end' class='method stab '><code>fn <a href='#method.read_to_end' class='fnname'>read_to_end</a>(&amp;mut self, buf: &amp;mut <a class='struct' href='../../../bitflags/__core/vec/struct.Vec.html' title='bitflags::__core::vec::Vec'>Vec</a>&lt;<a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.u8.html'>u8</a>&gt;) -&gt; <a class='enum' href='../../../bitflags/__core/result/enum.Result.html' title='bitflags::__core::result::Result'>Result</a>&lt;<a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.usize.html'>usize</a>, <a class='struct' href='../../../bitflags/__core/io/struct.Error.html' title='bitflags::__core::io::Error'>Error</a>&gt;</code></h3><div class='docblock'><p>Read all bytes until EOF in this source, placing them into <code>buf</code>.</p>
<p>All bytes read from this source will be appended to the specified buffer
<code>buf</code>. This function will continuously call <code>read</code> to append more data to
<code>buf</code> until <code>read</code> returns either <code>Ok(0)</code> or an error of
non-<code>ErrorKind::Interrupted</code> kind.</p>
<p>If successful, this function will return the total number of bytes read.</p>
<h1 id='errors-1' class='section-header'><a href='#errors-1'>Errors</a></h1>
<p>If this function encounters an error of the kind
<code>ErrorKind::Interrupted</code> then the error is ignored and the operation
will continue.</p>
<p>If any other read error is encountered then this function immediately
returns. Any bytes which have already been read will be appended to
<code>buf</code>.</p>
<h1 id='examples-2' class='section-header'><a href='#examples-2'>Examples</a></h1>
<p><a href="../fs/struct.File.html"><code>File</code></a>s implement <code>Read</code>:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>::<span class='ident'>prelude</span>::<span class='op'>*</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>fs</span>::<span class='ident'>File</span>;
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>f</span> <span class='op'>=</span> <span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>File</span>::<span class='ident'>open</span>(<span class='string'>&quot;foo.txt&quot;</span>));
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>buffer</span> <span class='op'>=</span> <span class='ident'>Vec</span>::<span class='ident'>new</span>();
<span class='comment'>// read the whole file</span>
<span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>f</span>.<span class='ident'>read_to_end</span>(<span class='kw-2'>&amp;</span><span class='kw-2'>mut</span> <span class='ident'>buffer</span>));</pre>
</div><h3 id='method.read_to_string' class='method stab '><code>fn <a href='#method.read_to_string' class='fnname'>read_to_string</a>(&amp;mut self, buf: &amp;mut <a class='struct' href='../../../bitflags/__core/string/struct.String.html' title='bitflags::__core::string::String'>String</a>) -&gt; <a class='enum' href='../../../bitflags/__core/result/enum.Result.html' title='bitflags::__core::result::Result'>Result</a>&lt;<a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.usize.html'>usize</a>, <a class='struct' href='../../../bitflags/__core/io/struct.Error.html' title='bitflags::__core::io::Error'>Error</a>&gt;</code></h3><div class='docblock'><p>Read all bytes until EOF in this source, placing them into <code>buf</code>.</p>
<p>If successful, this function returns the number of bytes which were read
and appended to <code>buf</code>.</p>
<h1 id='errors-2' class='section-header'><a href='#errors-2'>Errors</a></h1>
<p>If the data in this stream is <em>not</em> valid UTF-8 then an error is
returned and <code>buf</code> is unchanged.</p>
<p>See <a href="#method.read_to_end"><code>read_to_end()</code></a> for other error semantics.</p>
<h1 id='examples-3' class='section-header'><a href='#examples-3'>Examples</a></h1>
<p><a href="../fs/struct.File.html"><code>File</code></a>s implement <code>Read</code>:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>::<span class='ident'>prelude</span>::<span class='op'>*</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>fs</span>::<span class='ident'>File</span>;
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>f</span> <span class='op'>=</span> <span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>File</span>::<span class='ident'>open</span>(<span class='string'>&quot;foo.txt&quot;</span>));
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>buffer</span> <span class='op'>=</span> <span class='ident'>String</span>::<span class='ident'>new</span>();
<span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>f</span>.<span class='ident'>read_to_string</span>(<span class='kw-2'>&amp;</span><span class='kw-2'>mut</span> <span class='ident'>buffer</span>));</pre>
</div><h3 id='method.read_exact' class='method stab '><code>fn <a href='#method.read_exact' class='fnname'>read_exact</a>(&amp;mut self, buf: <a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.slice.html'>&amp;mut [</a><a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.u8.html'>u8</a><a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.slice.html'>]</a>) -&gt; <a class='enum' href='../../../bitflags/__core/result/enum.Result.html' title='bitflags::__core::result::Result'>Result</a>&lt;<a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.tuple.html'>()</a>, <a class='struct' href='../../../bitflags/__core/io/struct.Error.html' title='bitflags::__core::io::Error'>Error</a>&gt;</code><span class="since">1.6.0</span></h3><div class='docblock'><p>Read the exact number of bytes required to fill <code>buf</code>.</p>
<p>This function reads as many bytes as necessary to completely fill the
specified buffer <code>buf</code>.</p>
<p>No guarantees are provided about the contents of <code>buf</code> when this
function is called, implementations cannot rely on any property of the
contents of <code>buf</code> being true. It is recommended that implementations
only write data to <code>buf</code> instead of reading its contents.</p>
<h1 id='errors-3' class='section-header'><a href='#errors-3'>Errors</a></h1>
<p>If this function encounters an error of the kind
<code>ErrorKind::Interrupted</code> then the error is ignored and the operation
will continue.</p>
<p>If this function encounters an &quot;end of file&quot; before completely filling
the buffer, it returns an error of the kind <code>ErrorKind::UnexpectedEof</code>.
The contents of <code>buf</code> are unspecified in this case.</p>
<p>If any other read error is encountered then this function immediately
returns. The contents of <code>buf</code> are unspecified in this case.</p>
<p>If this function returns an error, it is unspecified how many bytes it
has read, but it will never read more than would be necessary to
completely fill the buffer.</p>
<h1 id='examples-4' class='section-header'><a href='#examples-4'>Examples</a></h1>
<p><a href="../fs/struct.File.html"><code>File</code></a>s implement <code>Read</code>:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>::<span class='ident'>prelude</span>::<span class='op'>*</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>fs</span>::<span class='ident'>File</span>;
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>f</span> <span class='op'>=</span> <span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>File</span>::<span class='ident'>open</span>(<span class='string'>&quot;foo.txt&quot;</span>));
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>buffer</span> <span class='op'>=</span> [<span class='number'>0</span>; <span class='number'>10</span>];
<span class='comment'>// read exactly 10 bytes</span>
<span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>f</span>.<span class='ident'>read_exact</span>(<span class='kw-2'>&amp;</span><span class='kw-2'>mut</span> <span class='ident'>buffer</span>));</pre>
</div><h3 id='method.by_ref' class='method stab '><code>fn <a href='#method.by_ref' class='fnname'>by_ref</a>(&amp;mut self) -&gt; &amp;mut Self</code></h3><div class='docblock'><p>Creates a &quot;by reference&quot; adaptor for this instance of <code>Read</code>.</p>
<p>The returned adaptor also implements <code>Read</code> and will simply borrow this
current reader.</p>
<h1 id='examples-5' class='section-header'><a href='#examples-5'>Examples</a></h1>
<p><a href="../fs/struct.File.html"><code>File</code></a>s implement <code>Read</code>:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>::<span class='ident'>Read</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>fs</span>::<span class='ident'>File</span>;
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>f</span> <span class='op'>=</span> <span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>File</span>::<span class='ident'>open</span>(<span class='string'>&quot;foo.txt&quot;</span>));
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>buffer</span> <span class='op'>=</span> <span class='ident'>Vec</span>::<span class='ident'>new</span>();
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>other_buffer</span> <span class='op'>=</span> <span class='ident'>Vec</span>::<span class='ident'>new</span>();
{
<span class='kw'>let</span> <span class='ident'>reference</span> <span class='op'>=</span> <span class='ident'>f</span>.<span class='ident'>by_ref</span>();
<span class='comment'>// read at most 5 bytes</span>
<span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>reference</span>.<span class='ident'>take</span>(<span class='number'>5</span>).<span class='ident'>read_to_end</span>(<span class='kw-2'>&amp;</span><span class='kw-2'>mut</span> <span class='ident'>buffer</span>));
} <span class='comment'>// drop our &amp;mut reference so we can use f again</span>
<span class='comment'>// original file still usable, read the rest</span>
<span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>f</span>.<span class='ident'>read_to_end</span>(<span class='kw-2'>&amp;</span><span class='kw-2'>mut</span> <span class='ident'>other_buffer</span>));</pre>
</div><h3 id='method.bytes' class='method stab '><code>fn <a href='#method.bytes' class='fnname'>bytes</a>(self) -&gt; <a class='struct' href='../../../bitflags/__core/io/struct.Bytes.html' title='bitflags::__core::io::Bytes'>Bytes</a>&lt;Self&gt;</code></h3><div class='docblock'><p>Transforms this <code>Read</code> instance to an <code>Iterator</code> over its bytes.</p>
<p>The returned type implements <code>Iterator</code> where the <code>Item</code> is <code>Result&lt;u8, R::Err&gt;</code>. The yielded item is <code>Ok</code> if a byte was successfully read and
<code>Err</code> otherwise for I/O errors. EOF is mapped to returning <code>None</code> from
this iterator.</p>
<h1 id='examples-6' class='section-header'><a href='#examples-6'>Examples</a></h1>
<p><a href="../fs/struct.File.html"><code>File</code></a>s implement <code>Read</code>:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>::<span class='ident'>prelude</span>::<span class='op'>*</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>fs</span>::<span class='ident'>File</span>;
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>f</span> <span class='op'>=</span> <span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>File</span>::<span class='ident'>open</span>(<span class='string'>&quot;foo.txt&quot;</span>));
<span class='kw'>for</span> <span class='ident'>byte</span> <span class='kw'>in</span> <span class='ident'>f</span>.<span class='ident'>bytes</span>() {
<span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>&quot;{}&quot;</span>, <span class='ident'>byte</span>.<span class='ident'>unwrap</span>());
}</pre>
</div><h3 id='method.chars' class='method stab unstable'><code>fn <a href='#method.chars' class='fnname'>chars</a>(self) -&gt; <a class='struct' href='../../../bitflags/__core/io/struct.Chars.html' title='bitflags::__core::io::Chars'>Chars</a>&lt;Self&gt;</code></h3><div class='stability'><em class='stab unstable'>Unstable (<code>io</code>)<p>: the semantics of a partial read/write of where errors happen is currently unclear and may change</p>
</em></div><div class='docblock'><p>Transforms this <code>Read</code> instance to an <code>Iterator</code> over <code>char</code>s.</p>
<p>This adaptor will attempt to interpret this reader as a UTF-8 encoded
sequence of characters. The returned iterator will return <code>None</code> once
EOF is reached for this reader. Otherwise each element yielded will be a
<code>Result&lt;char, E&gt;</code> where <code>E</code> may contain information about what I/O error
occurred or where decoding failed.</p>
<p>Currently this adaptor will discard intermediate data read, and should
be avoided if this is not desired.</p>
<h1 id='examples-7' class='section-header'><a href='#examples-7'>Examples</a></h1>
<p><a href="../fs/struct.File.html"><code>File</code></a>s implement <code>Read</code>:</p>
<pre class='rust rust-example-rendered'>
<span class='attribute'>#<span class='op'>!</span>[<span class='ident'>feature</span>(<span class='ident'>io</span>)]</span>
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>::<span class='ident'>prelude</span>::<span class='op'>*</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>fs</span>::<span class='ident'>File</span>;
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>f</span> <span class='op'>=</span> <span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>File</span>::<span class='ident'>open</span>(<span class='string'>&quot;foo.txt&quot;</span>));
<span class='kw'>for</span> <span class='ident'>c</span> <span class='kw'>in</span> <span class='ident'>f</span>.<span class='ident'>chars</span>() {
<span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>&quot;{}&quot;</span>, <span class='ident'>c</span>.<span class='ident'>unwrap</span>());
}</pre>
</div><h3 id='method.chain' class='method stab '><code>fn <a href='#method.chain' class='fnname'>chain</a>&lt;R&gt;(self, next: R) -&gt; <a class='struct' href='../../../bitflags/__core/io/struct.Chain.html' title='bitflags::__core::io::Chain'>Chain</a>&lt;Self, R&gt; <span class='where'>where R: <a class='trait' href='../../../bitflags/__core/io/trait.Read.html' title='bitflags::__core::io::Read'>Read</a></span></code></h3><div class='docblock'><p>Creates an adaptor which will chain this stream with another.</p>
<p>The returned <code>Read</code> instance will first read all bytes from this object
until EOF is encountered. Afterwards the output is equivalent to the
output of <code>next</code>.</p>
<h1 id='examples-8' class='section-header'><a href='#examples-8'>Examples</a></h1>
<p><a href="../fs/struct.File.html"><code>File</code></a>s implement <code>Read</code>:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>::<span class='ident'>prelude</span>::<span class='op'>*</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>fs</span>::<span class='ident'>File</span>;
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>f1</span> <span class='op'>=</span> <span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>File</span>::<span class='ident'>open</span>(<span class='string'>&quot;foo.txt&quot;</span>));
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>f2</span> <span class='op'>=</span> <span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>File</span>::<span class='ident'>open</span>(<span class='string'>&quot;bar.txt&quot;</span>));
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>handle</span> <span class='op'>=</span> <span class='ident'>f1</span>.<span class='ident'>chain</span>(<span class='ident'>f2</span>);
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>buffer</span> <span class='op'>=</span> <span class='ident'>String</span>::<span class='ident'>new</span>();
<span class='comment'>// read the value into a String. We could use any Read method here,</span>
<span class='comment'>// this is just one example.</span>
<span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>handle</span>.<span class='ident'>read_to_string</span>(<span class='kw-2'>&amp;</span><span class='kw-2'>mut</span> <span class='ident'>buffer</span>));</pre>
</div><h3 id='method.take' class='method stab '><code>fn <a href='#method.take' class='fnname'>take</a>(self, limit: <a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.u64.html'>u64</a>) -&gt; <a class='struct' href='../../../bitflags/__core/io/struct.Take.html' title='bitflags::__core::io::Take'>Take</a>&lt;Self&gt;</code></h3><div class='docblock'><p>Creates an adaptor which will read at most <code>limit</code> bytes from it.</p>
<p>This function returns a new instance of <code>Read</code> which will read at most
<code>limit</code> bytes, after which it will always return EOF (<code>Ok(0)</code>). Any
read errors will not count towards the number of bytes read and future
calls to <code>read</code> may succeed.</p>
<h1 id='examples-9' class='section-header'><a href='#examples-9'>Examples</a></h1>
<p><a href="../fs/struct.File.html"><code>File</code></a>s implement <code>Read</code>:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>io</span>::<span class='ident'>prelude</span>::<span class='op'>*</span>;
<span class='kw'>use</span> <span class='ident'>std</span>::<span class='ident'>fs</span>::<span class='ident'>File</span>;
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>f</span> <span class='op'>=</span> <span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>File</span>::<span class='ident'>open</span>(<span class='string'>&quot;foo.txt&quot;</span>));
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>buffer</span> <span class='op'>=</span> [<span class='number'>0</span>; <span class='number'>5</span>];
<span class='comment'>// read at most five bytes</span>
<span class='kw'>let</span> <span class='kw-2'>mut</span> <span class='ident'>handle</span> <span class='op'>=</span> <span class='ident'>f</span>.<span class='ident'>take</span>(<span class='number'>5</span>);
<span class='macro'>try</span><span class='macro'>!</span>(<span class='ident'>handle</span>.<span class='ident'>read</span>(<span class='kw-2'>&amp;</span><span class='kw-2'>mut</span> <span class='ident'>buffer</span>));</pre>
</div></div>
<h2 id='implementors'>Implementors</h2>
<ul class='item-list' id='implementors-list'>
<li><code>impl Read for <a class='struct' href='../../../bitflags/__core/fs/struct.File.html' title='bitflags::__core::fs::File'>File</a></code></li>
<li><code>impl&lt;'a&gt; Read for &amp;'a <a class='struct' href='../../../bitflags/__core/fs/struct.File.html' title='bitflags::__core::fs::File'>File</a></code></li>
<li><code>impl&lt;R&gt; Read for <a class='struct' href='../../../bitflags/__core/io/struct.BufReader.html' title='bitflags::__core::io::BufReader'>BufReader</a>&lt;R&gt; <span class='where'>where R: <a class='trait' href='../../../bitflags/__core/io/trait.Read.html' title='bitflags::__core::io::Read'>Read</a></span></code></li>
<li><code>impl&lt;T&gt; Read for <a class='struct' href='../../../bitflags/__core/io/struct.Cursor.html' title='bitflags::__core::io::Cursor'>Cursor</a>&lt;T&gt; <span class='where'>where T: <a class='trait' href='../../../bitflags/__core/convert/trait.AsRef.html' title='bitflags::__core::convert::AsRef'>AsRef</a>&lt;<a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.slice.html'>[</a><a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.u8.html'>u8</a><a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.slice.html'>]</a>&gt;</span></code></li>
<li><code>impl&lt;'a, R&gt; Read for &amp;'a mut R <span class='where'>where R: <a class='trait' href='../../../bitflags/__core/io/trait.Read.html' title='bitflags::__core::io::Read'>Read</a> + ?<a class='trait' href='../../../bitflags/__core/marker/trait.Sized.html' title='bitflags::__core::marker::Sized'>Sized</a></span></code></li>
<li><code>impl&lt;R&gt; Read for <a class='struct' href='../../../bitflags/__core/boxed/struct.Box.html' title='bitflags::__core::boxed::Box'>Box</a>&lt;R&gt; <span class='where'>where R: <a class='trait' href='../../../bitflags/__core/io/trait.Read.html' title='bitflags::__core::io::Read'>Read</a> + ?<a class='trait' href='../../../bitflags/__core/marker/trait.Sized.html' title='bitflags::__core::marker::Sized'>Sized</a></span></code></li>
<li><code>impl&lt;'a&gt; Read for <a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.slice.html'>&amp;'a [</a><a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.u8.html'>u8</a><a class='primitive' href='https://doc.rust-lang.org/nightly/bitflags/primitive.slice.html'>]</a></code></li>
<li><code>impl Read for <a class='struct' href='../../../bitflags/__core/io/struct.Empty.html' title='bitflags::__core::io::Empty'>Empty</a></code></li>
<li><code>impl Read for <a class='struct' href='../../../bitflags/__core/io/struct.Repeat.html' title='bitflags::__core::io::Repeat'>Repeat</a></code></li>
<li><code>impl Read for <a class='struct' href='../../../bitflags/__core/io/struct.Stdin.html' title='bitflags::__core::io::Stdin'>Stdin</a></code></li>
<li><code>impl&lt;'a&gt; Read for <a class='struct' href='../../../bitflags/__core/io/struct.StdinLock.html' title='bitflags::__core::io::StdinLock'>StdinLock</a>&lt;'a&gt;</code></li>
<li><code>impl&lt;T, U&gt; Read for <a class='struct' href='../../../bitflags/__core/io/struct.Chain.html' title='bitflags::__core::io::Chain'>Chain</a>&lt;T, U&gt; <span class='where'>where U: <a class='trait' href='../../../bitflags/__core/io/trait.Read.html' title='bitflags::__core::io::Read'>Read</a>, T: <a class='trait' href='../../../bitflags/__core/io/trait.Read.html' title='bitflags::__core::io::Read'>Read</a></span></code></li>
<li><code>impl&lt;T&gt; Read for <a class='struct' href='../../../bitflags/__core/io/struct.Take.html' title='bitflags::__core::io::Take'>Take</a>&lt;T&gt; <span class='where'>where T: <a class='trait' href='../../../bitflags/__core/io/trait.Read.html' title='bitflags::__core::io::Read'>Read</a></span></code></li>
<li><code>impl Read for <a class='struct' href='../../../bitflags/__core/net/struct.TcpStream.html' title='bitflags::__core::net::TcpStream'>TcpStream</a></code></li>
<li><code>impl&lt;'a&gt; Read for &amp;'a <a class='struct' href='../../../bitflags/__core/net/struct.TcpStream.html' title='bitflags::__core::net::TcpStream'>TcpStream</a></code></li>
<li><code>impl Read for <a class='struct' href='../../../bitflags/__core/os/ext/net/struct.UnixStream.html' title='bitflags::__core::os::ext::net::UnixStream'>UnixStream</a></code></li>
<li><code>impl&lt;'a&gt; Read for &amp;'a <a class='struct' href='../../../bitflags/__core/os/ext/net/struct.UnixStream.html' title='bitflags::__core::os::ext::net::UnixStream'>UnixStream</a></code></li>
<li><code>impl Read for <a class='struct' href='../../../bitflags/__core/process/struct.ChildStdout.html' title='bitflags::__core::process::ChildStdout'>ChildStdout</a></code></li>
<li><code>impl Read for <a class='struct' href='../../../bitflags/__core/process/struct.ChildStderr.html' title='bitflags::__core::process::ChildStderr'>ChildStderr</a></code></li>
<li><code>impl&lt;'a&gt; Read for &amp;'a FileDesc</code></li>
</ul><script type="text/javascript" async
src="../../../implementors/std/io/trait.Read.js">
</script></section>
<section id='search' class="content hidden"></section>
<section class="footer"></section>
<aside id="help" class="hidden">
<div>
<h1 class="hidden">Help</h1>
<div class="shortcuts">
<h2>Keyboard Shortcuts</h2>
<dl>
<dt>?</dt>
<dd>Show this help dialog</dd>
<dt>S</dt>
<dd>Focus the search field</dd>
<dt>&larrb;</dt>
<dd>Move up in search results</dd>
<dt>&rarrb;</dt>
<dd>Move down in search results</dd>
<dt>&#9166;</dt>
<dd>Go to active search result</dd>
</dl>
</div>
<div class="infos">
<h2>Search Tricks</h2>
<p>
Prefix searches with a type followed by a colon (e.g.
<code>fn:</code>) to restrict the search to a given type.
</p>
<p>
Accepted types are: <code>fn</code>, <code>mod</code>,
<code>struct</code>, <code>enum</code>,
<code>trait</code>, <code>type</code>, <code>macro</code>,
and <code>const</code>.
</p>
<p>
Search functions by type signature (e.g.
<code>vec -> usize</code> or <code>* -> vec</code>)
</p>
</div>
</div>
</aside>
<script>
window.rootPath = "../../../";
window.currentCrate = "bitflags";
window.playgroundUrl = "";
</script>
<script src="../../../jquery.js"></script>
<script src="../../../main.js"></script>
<script defer src="../../../search-index.js"></script>
</body>
</html>
Reference in a new issue View git blame Copy permalink