Struct std::io::Cursor1.0.0[−][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<()> {
    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 I/O object.

Cursor initial position is 0 even if underlying object (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 &'a 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 &'a 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: Clone> Clone for Cursor<T>
[src]

ⓘImportant traits for Cursor<T>

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. Read more

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

🔬 This is a nightly-only experimental API. (read_initializer #42788)

Determines if this Reader 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

ⓘImportant traits for &'a 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 Chars<R>

Deprecated since 1.27.0

: Use str::from_utf8 instead: https://doc.rust-lang.org/nightly/std/str/struct.Utf8Error.html#examples

🔬 This is a nightly-only experimental API. (io #27802)

the semantics of a partial read/write of where errors happen is currently unclear and may change

Transforms this Read instance to an [Iterator] over [char]s. 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<T> BufRead for Cursor<T> where
    T: AsRef<[u8]>, 
[src]

Fills the internal buffer of this object, returning the buffer contents. 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

ⓘ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<'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

ⓘImportant traits for &'a 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]

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

ⓘImportant traits for &'a mut I

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

impl Write for Cursor<Vec<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

ⓘImportant traits for &'a mut I

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

impl Write for Cursor<Box<[u8]>>
1.5.0
[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

ⓘImportant traits for &'a mut I

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

Auto Trait Implementations

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

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