Struct core_io::Cursor [−] [src]

pub struct Cursor<T> { /* fields omitted */ }

A 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>
[src]

Creates a new cursor wrapping the provided underlying I/O object.

Examples

use std::io::Cursor;

let buff = Cursor::new(Vec::new());

Consumes this cursor, returning the underlying value.

Examples

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.

Examples

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.

Examples

use std::io::Cursor;

let mut buff = Cursor::new(Vec::new());

let reference = buff.get_mut();

Returns the current position of this cursor.

Examples

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.

Examples

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);

Trait Implementations

impl<T: Clone> Clone for Cursor<T>
[src]

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

impl<T: Debug> Debug for Cursor<T>
[src]

Formats the value using the given formatter.

impl<T> Seek for Cursor<T> where T: AsRef<[u8]>
[src]

Seek to an offset, in bytes, in a stream. Read more

impl<T> Read for Cursor<T> where T: AsRef<[u8]>
[src]

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

Creates a "by reference" adaptor for this instance of Read. Read more

Transforms this Read instance to an Iterator over its bytes. Read more

Transforms this Read instance to an Iterator over chars. 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

impl<'a> Write for Cursor<&'a mut [u8]>
[src]

Write a buffer into this object, 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 write. 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