pub struct Cursor<T> { /* fields omitted */ }
A Cursor
wraps an in-memory buffer and provides it with a
Seek
implementation.
Cursor
s are used with in-memory buffers, anything implementing
AsRef<[u8]>
, to allow them to implement Read
and/or Write
,
allowing these buffers to be used anywhere you might use a reader or writer
that does actual I/O.
The standard library implements some I/O traits on various types which
are commonly used as a buffer, like Cursor<
Vec
<u8>>
and
Cursor<
&[u8]
>
.
We may want to write bytes to a File
in our production
code, but use an in-memory buffer in our tests. We can do this with
Cursor
:
use std::io::prelude::*;
use std::io::{self, SeekFrom};
use std::fs::File;
fn write_ten_bytes_at_end<W: Write + Seek>(writer: &mut W) -> io::Result<()> {
writer.seek(SeekFrom::End(-10))?;
for i in 0..10 {
writer.write(&[i])?;
}
Ok(())
}
let mut file = File::create("foo.txt")?;
write_ten_bytes_at_end(&mut file)?;
#[test]
fn test_writes_bytes() {
use std::io::Cursor;
let mut buff = Cursor::new(vec![0; 15]);
write_ten_bytes_at_end(&mut buff).unwrap();
assert_eq!(&buff.get_ref()[5..15], &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
}
Creates a new cursor wrapping the provided underlying in-memory buffer.
Cursor initial position is 0
even if underlying buffer (e.g., Vec
)
is not empty. So writing to cursor starts with overwriting Vec
content, not with appending to it.
use std::io::Cursor;
let buff = Cursor::new(Vec::new());
Consumes this cursor, returning the underlying value.
use std::io::Cursor;
let buff = Cursor::new(Vec::new());
let vec = buff.into_inner();
Gets a reference to the underlying value in this cursor.
use std::io::Cursor;
let buff = Cursor::new(Vec::new());
let reference = buff.get_ref();
Gets a mutable reference to the underlying value in this cursor.
Care should be taken to avoid modifying the internal I/O state of the
underlying value as it may corrupt this cursor's position.
use std::io::Cursor;
let mut buff = Cursor::new(Vec::new());
let reference = buff.get_mut();
Returns the current position of this cursor.
use std::io::Cursor;
use std::io::prelude::*;
use std::io::SeekFrom;
let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]);
assert_eq!(buff.position(), 0);
buff.seek(SeekFrom::Current(2)).unwrap();
assert_eq!(buff.position(), 2);
buff.seek(SeekFrom::Current(-1)).unwrap();
assert_eq!(buff.position(), 1);
Sets the position of this cursor.
use std::io::Cursor;
let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]);
assert_eq!(buff.position(), 0);
buff.set_position(2);
assert_eq!(buff.position(), 2);
buff.set_position(4);
assert_eq!(buff.position(), 4);
Performs copy-assignment from source
. Read more
Formats the value using the given formatter. Read more
Returns the contents of the internal buffer, filling it with more data from the inner reader if it is empty. Read more
Tells this buffer that amt
bytes have been consumed from the buffer, so they should no longer be returned in calls to read
. Read more
Read all bytes into buf
until the delimiter byte
or EOF is reached. Read more
Read all bytes until a newline (the 0xA byte) is reached, and append them to the provided buffer. Read more
Returns an iterator over the contents of this reader split on the byte byte
. Read more
Returns an iterator over the lines of this reader. Read more
Seek to an offset, in bytes, in a stream. Read more
Write a buffer into this writer, returning how many bytes were written. Read more
Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
Attempts to write an entire buffer into this writer. Read more
Writes a formatted string into this writer, returning any error encountered. Read more
Creates a "by reference" adaptor for this instance of Write
. Read more
Write a buffer into this writer, returning how many bytes were written. Read more
Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
Attempts to write an entire buffer into this writer. Read more
Writes a formatted string into this writer, returning any error encountered. Read more
Creates a "by reference" adaptor for this instance of Write
. Read more
Write a buffer into this writer, returning how many bytes were written. Read more
Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
Attempts to write an entire buffer into this writer. Read more
Writes a formatted string into this writer, returning any error encountered. Read more
Creates a "by reference" adaptor for this instance of Write
. Read more
Write a buffer into this writer, returning how many bytes were written. Read more
Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
Attempts to write an entire buffer into this writer. Read more
Writes a formatted string into this writer, returning any error encountered. Read more
Creates a "by reference" adaptor for this instance of Write
. Read more
Pull some bytes from this source into the specified buffer, returning how many bytes were read. Read more
Read the exact number of bytes required to fill buf
. Read more
🔬 This is a nightly-only experimental API. (read_initializer
)
Determines if this Read
er can work with buffers of uninitialized memory. Read more
Read all bytes until EOF in this source, placing them into buf
. Read more
Read all bytes until EOF in this source, appending them to buf
. Read more
Creates a "by reference" adaptor for this instance of Read
. Read more
Transforms this Read
instance to an [Iterator
] over its bytes. Read more
Creates an adaptor which will chain this stream with another. Read more
Creates an adaptor which will read at most limit
bytes from it. Read more
type Owned = T
Creates owned data from borrowed data, usually by cloning. Read more
🔬 This is a nightly-only experimental API. (toowned_clone_into
)
recently added
Uses borrowed data to replace owned data, usually by cloning. Read more
type Error = !
🔬 This is a nightly-only experimental API. (try_from
)
The type returned in the event of a conversion error.
🔬 This is a nightly-only experimental API. (try_from
)
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
type Error = <U as TryFrom<T>>::Error
🔬 This is a nightly-only experimental API. (try_from
)
The type returned in the event of a conversion error.
🔬 This is a nightly-only experimental API. (try_from
)
🔬 This is a nightly-only experimental API. (get_type_id
)
this method will likely be replaced by an associated static