Struct std::io::BufferedReader
pub struct BufferedReader<R> {
// some fields omitted
}Wraps a Reader and buffers input from it
It can be excessively inefficient to work directly with a Reader. For
example, every call to read on TcpStream results in a system call. A
BufferedReader performs large, infrequent reads on the underlying
Reader and maintains an in-memory buffer of the results.
Example
use std::io::{BufferedReader, File}; let file = File::open(&Path::new("message.txt")); let mut reader = BufferedReader::new(file); let mut buf = [0, ..100]; match reader.read(buf) { Ok(nread) => println!("Read {} bytes", nread), Err(e) => println!("error reading: {}", e) }
Methods
impl<R: Reader> BufferedReader<R>
fn with_capacity(cap: uint, inner: R) -> BufferedReader<R>
Creates a new BufferedReader with the specified buffer capacity
fn new(inner: R) -> BufferedReader<R>
Creates a new BufferedReader with a default buffer capacity
fn get_ref<'a>(&'a self) -> &'a R
Gets a reference to the underlying reader.
This type does not expose the ability to get a mutable reference to the underlying reader because that could possibly corrupt the buffer.
fn unwrap(self) -> R
Unwraps this BufferedReader, returning the underlying reader.
Note that any leftover data in the internal buffer is lost.
Trait Implementations
impl<R: Reader> Buffer for BufferedReader<R>
fn fill_buf<'a>(&'a mut self) -> IoResult<&'a [u8]>
Fills the internal buffer of this object, returning the buffer contents.
Note that none of the contents will be "read" in the sense that later
calling read may return the same contents.
The consume function must be called with the number of bytes that are
consumed from this buffer returned to ensure that the bytes are never
returned twice.
Error
This function will return an I/O error if the underlying reader was read, but returned an error. Note that it is not an error to return a 0-length buffer.
fn consume(&mut self, amt: uint)
Tells this buffer that amt bytes have been consumed from the buffer,
so they should no longer be returned in calls to fill or read.
fn read_line(&mut self) -> IoResult<~str>
Reads the next line of input, interpreted as a sequence of UTF-8 encoded unicode codepoints. If a newline is encountered, then the newline is contained in the returned string.
Example
use std::io; let mut reader = io::stdin(); let input = reader.read_line().ok().unwrap_or(~"nothing");
Error
This function has the same error semantics as read_until:
- All non-EOF errors will be returned immediately
- If an error is returned previously consumed bytes are lost
- EOF is only returned if no bytes have been read
- Reach EOF may mean that the delimiter is not present in the return value
Additionally, this function can fail if the line of input read is not a valid UTF-8 sequence of bytes.
fn lines<'r>(&'r mut self) -> Lines<'r, Self>
Create an iterator that reads a line on each iteration until EOF.
Error
Any error other than EndOfFile that is produced by the underlying Reader
is returned by the iterator and should be handled by the caller.
fn read_until(&mut self, byte: u8) -> IoResult<~[u8]>
Reads a sequence of bytes leading up to a specified delimiter. Once the specified byte is encountered, reading ceases and the bytes up to and including the delimiter are returned.
Error
If any I/O error is encountered other than EOF, the error is immediately returned. Note that this may discard bytes which have already been read, and those bytes will not be returned. It is recommended to use other methods if this case is worrying.
If EOF is encountered, then this function will return EOF if 0 bytes have been read, otherwise the pending byte buffer is returned. This is the reason that the byte buffer returned may not always contain the delimiter.
fn read_char(&mut self) -> IoResult<char>
Reads the next utf8-encoded character from the underlying stream.
Error
If an I/O error occurs, or EOF, then this function will return Err.
This function will also return error if the stream does not contain a
valid utf-8 encoded codepoint as the next few bytes in the stream.
fn chars<'r>(&'r mut self) -> Chars<'r, Self>
Create an iterator that reads a utf8-encoded character on each iteration until EOF.
Error
Any error other than EndOfFile that is produced by the underlying Reader
is returned by the iterator and should be handled by the caller.
impl<R: Reader> Reader for BufferedReader<R>
fn read(&mut self, buf: &mut [u8]) -> IoResult<uint>
Read bytes, up to the length of buf and place them in buf.
Returns the number of bytes read. The number of bytes read my
be less than the number requested, even 0. Returns Err on EOF.
Error
If an error occurs during this I/O operation, then it is returned as
Err(IoError). Note that end-of-file is considered an error, and can be
inspected for in the error's kind field. Also note that reading 0
bytes is not considered an error in all circumstances
fn read_byte(&mut self) -> IoResult<u8>
Reads a single byte. Returns Err on EOF.
fn fill(&mut self, buf: &mut [u8]) -> IoResult<()>
Fills the provided slice with bytes from this reader
This will continue to call read until the slice has been completely
filled with bytes.
Error
If an error occurs at any point, that error is returned, and no further bytes are read.
fn push_exact(&mut self, buf: &mut ~[u8], len: uint) -> IoResult<()>
Reads exactly len bytes and appends them to a vector.
May push fewer than the requested number of bytes on error
or EOF. If Ok(()) is returned, then all of the requested bytes were
pushed on to the vector, otherwise the amount len bytes couldn't be
read (an error was encountered), and the error is returned.
fn read_exact(&mut self, len: uint) -> IoResult<~[u8]>
Reads exactly len bytes and gives you back a new vector of length
len
Error
Fails with the same conditions as read. Additionally returns error
on EOF. Note that if an error is returned, then some number of bytes may
have already been consumed from the underlying reader, and they are lost
(not returned as part of the error). If this is unacceptable, then it is
recommended to use the push_exact or read methods.
fn read_to_end(&mut self) -> IoResult<~[u8]>
Reads all remaining bytes from the stream.
Error
Returns any non-EOF error immediately. Previously read bytes are discarded when an error is returned.
When EOF is encountered, all bytes read up to that point are returned.
fn read_to_str(&mut self) -> IoResult<~str>
Reads all of the remaining bytes of this stream, interpreting them as a UTF-8 encoded stream. The corresponding string is returned.
Error
This function returns all of the same errors as read_to_end with an
additional error if the reader's contents are not a valid sequence of
UTF-8 bytes.
fn bytes<'r>(&'r mut self) -> Bytes<'r, Self>
Create an iterator that reads a single byte on each iteration, until EOF.
Error
Any error other than EndOfFile that is produced by the underlying Reader
is returned by the iterator and should be handled by the caller.
fn read_le_uint_n(&mut self, nbytes: uint) -> IoResult<u64>
Reads n little-endian unsigned integer bytes.
n must be between 1 and 8, inclusive.
fn read_le_int_n(&mut self, nbytes: uint) -> IoResult<i64>
Reads n little-endian signed integer bytes.
n must be between 1 and 8, inclusive.
fn read_be_uint_n(&mut self, nbytes: uint) -> IoResult<u64>
Reads n big-endian unsigned integer bytes.
n must be between 1 and 8, inclusive.
fn read_be_int_n(&mut self, nbytes: uint) -> IoResult<i64>
Reads n big-endian signed integer bytes.
n must be between 1 and 8, inclusive.
fn read_le_uint(&mut self) -> IoResult<uint>
Reads a little-endian unsigned integer.
The number of bytes returned is system-dependant.
fn read_le_int(&mut self) -> IoResult<int>
Reads a little-endian integer.
The number of bytes returned is system-dependant.
fn read_be_uint(&mut self) -> IoResult<uint>
Reads a big-endian unsigned integer.
The number of bytes returned is system-dependant.
fn read_be_int(&mut self) -> IoResult<int>
Reads a big-endian integer.
The number of bytes returned is system-dependant.
fn read_be_u64(&mut self) -> IoResult<u64>
Reads a big-endian u64.
u64s are 8 bytes long.
fn read_be_u32(&mut self) -> IoResult<u32>
Reads a big-endian u32.
u32s are 4 bytes long.
fn read_be_u16(&mut self) -> IoResult<u16>
Reads a big-endian u16.
u16s are 2 bytes long.
fn read_be_i64(&mut self) -> IoResult<i64>
Reads a big-endian i64.
i64s are 8 bytes long.
fn read_be_i32(&mut self) -> IoResult<i32>
Reads a big-endian i32.
i32s are 4 bytes long.
fn read_be_i16(&mut self) -> IoResult<i16>
Reads a big-endian i16.
i16s are 2 bytes long.
fn read_be_f64(&mut self) -> IoResult<f64>
Reads a big-endian f64.
f64s are 8 byte, IEEE754 double-precision floating point numbers.
fn read_be_f32(&mut self) -> IoResult<f32>
Reads a big-endian f32.
f32s are 4 byte, IEEE754 single-precision floating point numbers.
fn read_le_u64(&mut self) -> IoResult<u64>
Reads a little-endian u64.
u64s are 8 bytes long.
fn read_le_u32(&mut self) -> IoResult<u32>
Reads a little-endian u32.
u32s are 4 bytes long.
fn read_le_u16(&mut self) -> IoResult<u16>
Reads a little-endian u16.
u16s are 2 bytes long.
fn read_le_i64(&mut self) -> IoResult<i64>
Reads a little-endian i64.
i64s are 8 bytes long.
fn read_le_i32(&mut self) -> IoResult<i32>
Reads a little-endian i32.
i32s are 4 bytes long.
fn read_le_i16(&mut self) -> IoResult<i16>
Reads a little-endian i16.
i16s are 2 bytes long.
fn read_le_f64(&mut self) -> IoResult<f64>
Reads a little-endian f64.
f64s are 8 byte, IEEE754 double-precision floating point numbers.
fn read_le_f32(&mut self) -> IoResult<f32>
Reads a little-endian f32.
f32s are 4 byte, IEEE754 single-precision floating point numbers.
fn read_u8(&mut self) -> IoResult<u8>
Read a u8.
u8s are 1 byte.
fn read_i8(&mut self) -> IoResult<i8>
Read an i8.
i8s are 1 byte.
fn by_ref<'a>(&'a mut self) -> RefReader<'a, Self>
Creates a wrapper around a mutable reference to the reader.
This is useful to allow applying adaptors while still retaining ownership of the original value.