1.0.0[][src]Struct std::io::Cursor

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

A Cursor wraps an in-memory buffer and provides it with a Seek implementation.

Cursors 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]>.

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<()> {
    writer.seek(SeekFrom::End(-10))?;

    for i in 0..10 {
        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 = File::create("foo.txt")?;

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 slower 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]);
}Run

Methods

impl<T> Cursor<T>
[src]

Important traits for Cursor<T>

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.

Examples

use std::io::Cursor;

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

Consumes this cursor, returning the underlying value.

Examples

use std::io::Cursor;

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

let vec = buff.into_inner();Run

Important traits for &'_ mut I

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

Important traits for &'_ mut I

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

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

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

Trait Implementations

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

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

Important traits for &'_ mut I

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

Important traits for Bytes<R>

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

Important traits for Chain<T, U>

Creates an adaptor which will chain this stream with another. Read more

Important traits for Take<T>

Creates an adaptor which will read at most limit bytes from it. Read more

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

Attempts to write an entire buffer into this write. Read more

Writes a formatted string into this writer, returning any error encountered. Read more

Important traits for &'_ mut I

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

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

Attempts to write an entire buffer into this write. Read more

Writes a formatted string into this writer, returning any error encountered. Read more

Important traits for &'_ mut I

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

impl Write for Cursor<Vec<u8>>
[src]

Attempts to write an entire buffer into this write. Read more

Writes a formatted string into this writer, returning any error encountered. Read more

Important traits for &'_ mut I

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

impl Write for Cursor<Box<[u8]>>
1.5.0
[src]

Attempts to write an entire buffer into this write. Read more

Writes a formatted string into this writer, returning any error encountered. Read more

Important traits for &'_ mut I

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

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

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

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

Important traits for Split<B>

Returns an iterator over the contents of this reader split on the byte byte. Read more

Important traits for Lines<B>

Returns an iterator over the lines of this reader. Read more

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

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

Performs copy-assignment from source. Read more

Auto Trait Implementations

impl<T> Send for Cursor<T> where
    T: Send

impl<T> Sync for Cursor<T> where
    T: Sync

Blanket Implementations

impl<T, U> TryFrom for T where
    T: From<U>, 
[src]

🔬 This is a nightly-only experimental API. (try_from #33417)

The type returned in the event of a conversion error.

impl<T> From for T
[src]

impl<T, U> TryInto for T where
    U: TryFrom<T>, 
[src]

🔬 This is a nightly-only experimental API. (try_from #33417)

The type returned in the event of a conversion error.

impl<T, U> Into for T where
    U: From<T>, 
[src]

impl<T> Borrow for T where
    T: ?Sized
[src]

impl<T> BorrowMut for T where
    T: ?Sized
[src]

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> ToOwned for T where
    T: Clone
[src]