1.0.0[−][src]Trait std::io::Read
The Read
trait allows for reading bytes from a source.
Implementors of the Read
trait are called 'readers'.
Readers are defined by one required method, read()
. Each call to read()
will attempt to pull bytes from this source into a provided buffer. A
number of other methods are implemented in terms of read()
, giving
implementors a number of ways to read bytes while only needing to implement
a single method.
Readers are intended to be composable with one another. Many implementors
throughout std::io
take and provide types which implement the Read
trait.
Please note that each call to read()
may involve a system call, and
therefore, using something that implements BufRead
, such as
BufReader
, will be more efficient.
Examples
File
s implement Read
:
use std::io; use std::io::prelude::*; use std::fs::File; fn main() -> io::Result<()> { let mut f = File::open("foo.txt")?; let mut buffer = [0; 10]; // read up to 10 bytes f.read(&mut buffer)?; let mut buffer = Vec::new(); // read the whole file f.read_to_end(&mut buffer)?; // read into a String, so that you don't need to do the conversion. let mut buffer = String::new(); f.read_to_string(&mut buffer)?; // and more! See the other methods for more details. Ok(()) }Run
Read from &str
because &[u8]
implements Read
:
use std::io::prelude::*; fn main() -> io::Result<()> { let mut b = "This string will be read".as_bytes(); let mut buffer = [0; 10]; // read up to 10 bytes b.read(&mut buffer)?; // etc... it works exactly as a File does! Ok(()) }Run
Required methods
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
Pull some bytes from this source into the specified buffer, returning how many bytes were read.
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 Err
return value.
If the return value of this method is Ok(n)
, then it must be
guaranteed that 0 <= n <= buf.len()
. A nonzero n
value indicates
that the buffer buf
has been filled in with n
bytes of data from this
source. If n
is 0
, then it can indicate one of two scenarios:
- This reader has reached its "end of file" and will likely no longer be able to produce bytes. Note that this does not mean that the reader will always no longer be able to produce bytes.
- The buffer specified was 0 bytes in length.
No guarantees are provided about the contents of buf
when this
function is called, implementations cannot rely on any property of the
contents of buf
being true. It is recommended that implementations
only write data to buf
instead of reading its contents.
Errors
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.
An error of the ErrorKind::Interrupted
kind is non-fatal and the read
operation should be retried if there is nothing else to do.
Examples
File
s implement Read
:
use std::io; use std::io::prelude::*; use std::fs::File; fn main() -> io::Result<()> { let mut f = File::open("foo.txt")?; let mut buffer = [0; 10]; // read up to 10 bytes let n = f.read(&mut buffer[..])?; println!("The bytes: {:?}", &buffer[..n]); Ok(()) }Run
Provided methods
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize>
1.36.0
Like read
, except that it reads into a slice of buffers.
Data is copied to fill each buffer in order, with the final buffer
written to possibly being only partially filled. This method must behave
as a single call to read
with the buffers concatenated would.
The default implementation calls read
with either the first nonempty
buffer provided, or an empty one if none exists.
unsafe fn initializer(&self) -> Initializer
Determines if this Read
er can work with buffers of uninitialized
memory.
The default implementation returns an initializer which will zero buffers.
If a Read
er guarantees that it can work properly with uninitialized
memory, it should call Initializer::nop()
. See the documentation for
Initializer
for details.
The behavior of this method must be independent of the state of the
Read
er - the method only takes &self
so that it can be used through
trait objects.
Safety
This method is unsafe because a Read
er could otherwise return a
non-zeroing Initializer
from another Read
type without an unsafe
block.
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>
Read all bytes until EOF in this source, placing them into buf
.
All bytes read from this source will be appended to the specified buffer
buf
. This function will continuously call read()
to append more data to
buf
until read()
returns either Ok(0)
or an error of
non-ErrorKind::Interrupted
kind.
If successful, this function will return the total number of bytes read.
Errors
If this function encounters an error of the kind
ErrorKind::Interrupted
then the error is ignored and the operation
will continue.
If any other read error is encountered then this function immediately
returns. Any bytes which have already been read will be appended to
buf
.
Examples
File
s implement Read
:
use std::io; use std::io::prelude::*; use std::fs::File; fn main() -> io::Result<()> { let mut f = File::open("foo.txt")?; let mut buffer = Vec::new(); // read the whole file f.read_to_end(&mut buffer)?; Ok(()) }Run
(See also the std::fs::read
convenience function for reading from a
file.)
fn read_to_string(&mut self, buf: &mut String) -> Result<usize>
Read all bytes until EOF in this source, appending them to buf
.
If successful, this function returns the number of bytes which were read
and appended to buf
.
Errors
If the data in this stream is not valid UTF-8 then an error is
returned and buf
is unchanged.
See read_to_end
for other error semantics.
Examples
File
s implement Read
:
use std::io; use std::io::prelude::*; use std::fs::File; fn main() -> io::Result<()> { let mut f = File::open("foo.txt")?; let mut buffer = String::new(); f.read_to_string(&mut buffer)?; Ok(()) }Run
(See also the std::fs::read_to_string
convenience function for
reading from a file.)
fn read_exact(&mut self, buf: &mut [u8]) -> Result<()>
1.6.0
Read the exact number of bytes required to fill buf
.
This function reads as many bytes as necessary to completely fill the
specified buffer buf
.
No guarantees are provided about the contents of buf
when this
function is called, implementations cannot rely on any property of the
contents of buf
being true. It is recommended that implementations
only write data to buf
instead of reading its contents.
Errors
If this function encounters an error of the kind
ErrorKind::Interrupted
then the error is ignored and the operation
will continue.
If this function encounters an "end of file" before completely filling
the buffer, it returns an error of the kind ErrorKind::UnexpectedEof
.
The contents of buf
are unspecified in this case.
If any other read error is encountered then this function immediately
returns. The contents of buf
are unspecified in this case.
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.
Examples
File
s implement Read
:
use std::io; use std::io::prelude::*; use std::fs::File; fn main() -> io::Result<()> { let mut f = File::open("foo.txt")?; let mut buffer = [0; 10]; // read exactly 10 bytes f.read_exact(&mut buffer)?; Ok(()) }Run
ⓘImportant traits for &'_ mut Ffn by_ref(&mut self) -> &mut Self where
Self: Sized,
Self: Sized,
Creates a "by reference" adaptor for this instance of Read
.
The returned adaptor also implements Read
and will simply borrow this
current reader.
Examples
File
s implement Read
:
use std::io; use std::io::Read; use std::fs::File; fn main() -> io::Result<()> { let mut f = File::open("foo.txt")?; let mut buffer = Vec::new(); let mut other_buffer = Vec::new(); { let reference = f.by_ref(); // read at most 5 bytes reference.take(5).read_to_end(&mut buffer)?; } // drop our &mut reference so we can use f again // original file still usable, read the rest f.read_to_end(&mut other_buffer)?; Ok(()) }Run
ⓘImportant traits for Bytes<R>fn bytes(self) -> Bytes<Self> where
Self: Sized,
Self: Sized,
Transforms this Read
instance to an Iterator
over its bytes.
The returned type implements Iterator
where the Item
is
Result
<
u8
,
io::Error
>
.
The yielded item is Ok
if a byte was successfully read and Err
otherwise. EOF is mapped to returning None
from this iterator.
Examples
File
s implement Read
:
use std::io; use std::io::prelude::*; use std::fs::File; fn main() -> io::Result<()> { let mut f = File::open("foo.txt")?; for byte in f.bytes() { println!("{}", byte.unwrap()); } Ok(()) }Run
ⓘImportant traits for Chain<T, U>fn chain<R: Read>(self, next: R) -> Chain<Self, R> where
Self: Sized,
Self: Sized,
Creates an adaptor which will chain this stream with another.
The returned Read
instance will first read all bytes from this object
until EOF is encountered. Afterwards the output is equivalent to the
output of next
.
Examples
File
s implement Read
:
use std::io; use std::io::prelude::*; use std::fs::File; fn main() -> io::Result<()> { let mut f1 = File::open("foo.txt")?; let mut f2 = File::open("bar.txt")?; let mut handle = f1.chain(f2); let mut buffer = String::new(); // read the value into a String. We could use any Read method here, // this is just one example. handle.read_to_string(&mut buffer)?; Ok(()) }Run
ⓘImportant traits for Take<T>fn take(self, limit: u64) -> Take<Self> where
Self: Sized,
Self: Sized,
Creates an adaptor which will read at most limit
bytes from it.
This function returns a new instance of Read
which will read at most
limit
bytes, after which it will always return EOF (Ok(0)
). Any
read errors will not count towards the number of bytes read and future
calls to read()
may succeed.
Examples
File
s implement Read
:
use std::io; use std::io::prelude::*; use std::fs::File; fn main() -> io::Result<()> { let mut f = File::open("foo.txt")?; let mut buffer = [0; 5]; // read at most five bytes let mut handle = f.take(5); handle.read(&mut buffer)?; Ok(()) }Run
Implementors
impl Read for File
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize>
[src]
unsafe fn initializer(&self) -> Initializer
[src]
impl Read for Empty
[src]
fn read(&mut self, _buf: &mut [u8]) -> Result<usize>
[src]
unsafe fn initializer(&self) -> Initializer
[src]
impl Read for Repeat
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize>
[src]
unsafe fn initializer(&self) -> Initializer
[src]
impl Read for Stdin
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize>
[src]
unsafe fn initializer(&self) -> Initializer
[src]
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>
[src]
fn read_to_string(&mut self, buf: &mut String) -> Result<usize>
[src]
fn read_exact(&mut self, buf: &mut [u8]) -> Result<()>
[src]
impl Read for TcpStream
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize>
[src]
unsafe fn initializer(&self) -> Initializer
[src]
impl Read for UnixStream
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize>
[src]
unsafe fn initializer(&self) -> Initializer
[src]
impl Read for ChildStderr
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize>
[src]
unsafe fn initializer(&self) -> Initializer
[src]
impl Read for ChildStdout
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize>
[src]
unsafe fn initializer(&self) -> Initializer
[src]
impl<'_> Read for &'_ File
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize>
[src]
unsafe fn initializer(&self) -> Initializer
[src]
impl<'_> Read for &'_ TcpStream
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize>
[src]
unsafe fn initializer(&self) -> Initializer
[src]
impl<'_> Read for &'_ [u8]
[src]
Read is implemented for &[u8]
by copying from the slice.
Note that reading updates the slice to point to the yet unread part. The slice will be empty when EOF is reached.
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize>
[src]
unsafe fn initializer(&self) -> Initializer
[src]
fn read_exact(&mut self, buf: &mut [u8]) -> Result<()>
[src]
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>
[src]
impl<'_> Read for StdinLock<'_>
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize>
[src]
unsafe fn initializer(&self) -> Initializer
[src]
impl<'_, R: Read + ?Sized> Read for &'_ mut R
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize>
[src]
unsafe fn initializer(&self) -> Initializer
[src]
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>
[src]
fn read_to_string(&mut self, buf: &mut String) -> Result<usize>
[src]
fn read_exact(&mut self, buf: &mut [u8]) -> Result<()>
[src]
impl<'a> Read for &'a UnixStream
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize>
[src]
unsafe fn initializer(&self) -> Initializer
[src]
impl<R: Read + ?Sized> Read for Box<R>
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize>
[src]
unsafe fn initializer(&self) -> Initializer
[src]
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>
[src]
fn read_to_string(&mut self, buf: &mut String) -> Result<usize>
[src]
fn read_exact(&mut self, buf: &mut [u8]) -> Result<()>
[src]
impl<R: Read> Read for BufReader<R>
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize>
[src]
unsafe fn initializer(&self) -> Initializer
[src]
impl<T> Read for Cursor<T> where
T: AsRef<[u8]>,
[src]
T: AsRef<[u8]>,