Struct Cursor

1.0.0 · Source

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

Expand description

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>(mut writer: 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")?;
// First, we need to allocate 10 bytes to be able to write into.
file.set_len(10)?;

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

Implementations§

Source §

impl<T> Cursor<T>

1.0.0 (const: 1.79.0) · Source

pub const fn new(inner: T) -> 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());

1.0.0 · Source

pub fn into_inner(self) -> T

Consumes this cursor, returning the underlying value.

§Examples

use std::io::Cursor;

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

let vec = buff.into_inner();

1.0.0 (const: 1.79.0) · Source

pub const fn get_ref(&self) -> &T

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

1.0.0 (const: 1.86.0) · Source

pub const 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

use std::io::Cursor;

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

let reference = buff.get_mut();

1.0.0 (const: 1.79.0) · Source

pub const fn position(&self) -> u64

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

1.0.0 (const: 1.86.0) · Source

pub const fn set_position(&mut self, pos: u64)

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

Source §

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

Source

pub fn split(&self) -> (&[u8], &[u8])

🔬This is a nightly-only experimental API. (cursor_split)

Splits the underlying slice at the cursor position and returns them.

§Examples

#![feature(cursor_split)]
use std::io::Cursor;

let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]);

assert_eq!(buff.split(), ([].as_slice(), [1, 2, 3, 4, 5].as_slice()));

buff.set_position(2);
assert_eq!(buff.split(), ([1, 2].as_slice(), [3, 4, 5].as_slice()));

buff.set_position(6);
assert_eq!(buff.split(), ([1, 2, 3, 4, 5].as_slice(), [].as_slice()));

Source §

impl<T> Cursor<T>
where T: AsMut<[u8]>,

Source

pub fn split_mut(&mut self) -> (&mut [u8], &mut [u8])

🔬This is a nightly-only experimental API. (cursor_split)

Splits the underlying slice at the cursor position and returns them mutably.

§Examples

#![feature(cursor_split)]
use std::io::Cursor;

let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]);

assert_eq!(buff.split_mut(), ([].as_mut_slice(), [1, 2, 3, 4, 5].as_mut_slice()));

buff.set_position(2);
assert_eq!(buff.split_mut(), ([1, 2].as_mut_slice(), [3, 4, 5].as_mut_slice()));

buff.set_position(6);
assert_eq!(buff.split_mut(), ([1, 2, 3, 4, 5].as_mut_slice(), [].as_mut_slice()));

Trait Implementations§

1.0.0 · Source§

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

Source §

fn fill_buf(&mut self) -> Result<&[u8], Error>

Returns the contents of the internal buffer, filling it with more data, via Read methods, if empty. Read more

Source §

fn consume(&mut self, amt: usize)

Marks the given amount of additional bytes from the internal buffer as having been read. Subsequent calls to read only return bytes that have not been marked as read. Read more

Source §