Struct std::io::Cursor
[−]
[src]
pub struct Cursor<T> {
// some fields omitted
}1.0.0A Cursor wraps another type and provides it with a
Seek implementation.
Cursors are typically used with in-memory buffers 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]>.
Examples
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; // a library function we've written fn write_ten_bytes_at_end<W: Write + Seek>(writer: &mut W) -> io::Result<()> { try!(writer.seek(SeekFrom::End(-10))); for i in 0..10 { try!(writer.write(&[i])); } // all went well Ok(()) } // Here's some code that uses this library function. // // We might want to use a BufReader here for efficiency, but let's // keep this example focused. let mut file = try!(File::create("foo.txt")); try!(write_ten_bytes_at_end(&mut file)); // now let's write a test #[test] fn test_writes_bytes() { // setting up a real File is much more slow than an in-memory buffer, // let's use a cursor instead 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]); }
Methods
impl<T> Cursor<T>
fn new(inner: T) -> Cursor<T>
Creates a new cursor wrapping the provided underlying I/O object.
Examples
fn main() { use std::io::Cursor; let buff = Cursor::new(Vec::new()); fn force_inference(_: &Cursor<Vec<u8>>) {} force_inference(&buff); }use std::io::Cursor; let buff = Cursor::new(Vec::new());
fn into_inner(self) -> T
Consumes this cursor, returning the underlying value.
Examples
fn main() { use std::io::Cursor; let buff = Cursor::new(Vec::new()); fn force_inference(_: &Cursor<Vec<u8>>) {} force_inference(&buff); let vec = buff.into_inner(); }use std::io::Cursor; let buff = Cursor::new(Vec::new()); let vec = buff.into_inner();
fn get_ref(&self) -> &T
Gets a reference to the underlying value in this cursor.
Examples
fn main() { use std::io::Cursor; let buff = Cursor::new(Vec::new()); fn force_inference(_: &Cursor<Vec<u8>>) {} force_inference(&buff); let reference = buff.get_ref(); }use std::io::Cursor; let buff = Cursor::new(Vec::new()); let reference = buff.get_ref();
fn get_mut(&mut self) -> &mut T
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.
Examples
fn main() { use std::io::Cursor; let mut buff = Cursor::new(Vec::new()); fn force_inference(_: &Cursor<Vec<u8>>) {} force_inference(&buff); let reference = buff.get_mut(); }use std::io::Cursor; let mut buff = Cursor::new(Vec::new()); let reference = buff.get_mut();
fn position(&self) -> u64
Returns the current position of this cursor.
Examples
fn main() { 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); }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);
fn set_position(&mut self, pos: u64)
Sets the position of this cursor.
Examples
fn main() { 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); }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);