W3cubDocs

/Rust

Struct Cursor 

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

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.0Source
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 #86369)

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 #86369)

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.0Source
impl<T> BufRead for Cursor<T>where
    T: AsRef<[u8]>,
Source
fn fill_buf(&mut self) -> Result<&[u8]>
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
fn has_data_left(&mut self) -> Result<bool>
🔬This is a nightly-only experimental API. (buf_read_has_data_left #86423)
Checks if there is any data left to be read. Read more
1.0.0Source
fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> Result<usize>
Reads all bytes into buf until the delimiter byte or EOF is reached. Read more
1.83.0Source
fn skip_until(&mut self, byte: u8) -> Result<usize>
Skips all bytes until the delimiter byte or EOF is reached. Read more
1.0.0Source
fn read_line(&mut self, buf: &mut String) -> Result<usize>
Reads all bytes until a newline (the 0xA byte) is reached, and append them to the provided String buffer. Read more
1.0.0Source
fn split(self, byte: u8) -> Split<Self> ⓘwhere
    Self: Sized,
Returns an iterator over the contents of this reader split on the byte byte. Read more
1.0.0Source
fn lines(self) -> Lines<Self> ⓘwhere
    Self: Sized,
Returns an iterator over the lines of this reader. Read more
1.0.0Source
impl<T> Clone for Cursor<T>where
    T: Clone,
Source
fn clone(&self) -> Self
Returns a duplicate of the value. Read more
Source
fn clone_from(&mut self, other: &Self)
Performs copy-assignment from source. Read more
1.0.0Source
impl<T: Debug> Debug for Cursor<T>
Source
fn fmt(&self, f: &mut Formatter<'_>) -> Result
Formats the value using the given formatter. Read more
1.0.0Source
impl<T: Default> Default for Cursor<T>
Source
fn default() -> Cursor<T> ⓘ
Returns the “default value” for a type. Read more
1.0.0Source
impl<T: PartialEq> PartialEq for Cursor<T>
Source
fn eq(&self, other: &Cursor<T>) -> bool
Tests for self and other values to be equal, and is used by ==.
1.0.0Source
fn ne(&self, other: &Rhs) -> bool
Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
1.0.0Source
impl<T> Read for Cursor<T>where
    T: AsRef<[u8]>,
Source
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
Pull some bytes from this source into the specified buffer, returning how many bytes were read. Read more
Source
fn read_buf(&mut self, cursor: BorrowedCursor<'_>) -> Result<()>
🔬This is a nightly-only experimental API. (read_buf #78485)
Pull some bytes from this source into the specified buffer. Read more
Source
fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>
Like read, except that it reads into a slice of buffers. Read more
Source
fn is_read_vectored(&self) -> bool
🔬This is a nightly-only experimental API. (can_vector #69941)
Determines if this Reader has an efficient read_vectored implementation. Read more
Source
fn read_exact(&mut self, buf: &mut [u8]) -> Result<()>
Reads the exact number of bytes required to fill buf. Read more
Source
fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<()>
🔬This is a nightly-only experimental API. (read_buf #78485)
Reads the exact number of bytes required to fill cursor. Read more
Source
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>
Reads all bytes until EOF in this source, placing them into buf. Read more
Source
fn read_to_string(&mut self, buf: &mut String) -> Result<usize>
Reads all bytes until EOF in this source, appending them to buf. Read more
1.0.0Source
fn by_ref(&mut self) -> &mut Selfwhere
    Self: Sized,
Creates a “by reference” adapter for this instance of Read. Read more
1.0.0Source
fn bytes(self) -> Bytes<Self> ⓘwhere
    Self: Sized,
Transforms this Read instance to an Iterator over its bytes. Read more
1.0.0Source
fn chain<R: Read>(self, next: R) -> Chain<Self, R> ⓘwhere
    Self: Sized,
Creates an adapter which will chain this stream with another. Read more
1.0.0Source
fn take(self, limit: u64) -> Take<Self> ⓘwhere
    Self: Sized,
Creates an adapter which will read at most limit bytes from it. Read more
Source
fn read_array<const N: usize>(&mut self) -> Result<[u8; N]>where
    Self: Sized,
🔬This is a nightly-only experimental API. (read_array #148848)
Read and return a fixed array of bytes from this source. Read more
1.0.0Source
impl<T> Seek for Cursor<T>where
    T: AsRef<[u8]>,
Source
fn seek(&mut self, style: SeekFrom) -> Result<u64>
Seek to an offset, in bytes, in a stream. Read more
Source
fn stream_len(&mut self) -> Result<u64>
🔬This is a nightly-only experimental API. (seek_stream_len #59359)
Returns the length of this stream (in bytes). Read more
Source
fn stream_position(&mut self) -> Result<u64>
Returns the current seek position from the start of the stream. Read more
1.55.0Source
fn rewind(&mut self) -> Result<()>
Rewind to the beginning of a stream. Read more
1.80.0Source
fn seek_relative(&mut self, offset: i64) -> Result<()>
Seeks relative to the current position. Read more
1.0.0Source
impl Write for Cursor<&mut [u8]>
Source
fn write(&mut self, buf: &[u8]) -> Result<usize>
Writes a buffer into this writer, returning how many bytes were written. Read more
Source
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>
Like write, except that it writes from a slice of buffers. Read more
Source
fn is_write_vectored(&self) -> bool
🔬This is a nightly-only experimental API. (can_vector #69941)
Determines if this Writer has an efficient write_vectored implementation. Read more
Source
fn write_all(&mut self, buf: &[u8]) -> Result<()>
Attempts to write an entire buffer into this writer. Read more
Source
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()>
🔬This is a nightly-only experimental API. (write_all_vectored #70436)
Attempts to write multiple buffers into this writer. Read more
Source
fn flush(&mut self) -> Result<()>
Flushes this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
1.0.0Source
fn write_fmt(&mut self, args: Arguments<'_>) -> Result<()>
Writes a formatted string into this writer, returning any error encountered. Read more
1.0.0Source
fn by_ref(&mut self) -> &mut Selfwhere
    Self: Sized,
Creates a “by reference” adapter for this instance of Write. Read more
1.25.0Source
impl<A> Write for Cursor<&mut Vec<u8, A>>where
    A: Allocator,
Source
fn write(&mut self, buf: &[u8]) -> Result<usize>
Writes a buffer into this writer, returning how many bytes were written. Read more
Source
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>
Like write, except that it writes from a slice of buffers. Read more
Source
fn is_write_vectored(&self) -> bool
🔬This is a nightly-only experimental API. (can_vector #69941)
Determines if this Writer has an efficient write_vectored implementation. Read more
Source
fn write_all(&mut self, buf: &[u8]) -> Result<()>
Attempts to write an entire buffer into this writer. Read more
Source
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()>
🔬This is a nightly-only experimental API. (write_all_vectored #70436)
Attempts to write multiple buffers into this writer. Read more
Source
fn flush(&mut self) -> Result<()>
Flushes this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
1.0.0Source
fn write_fmt(&mut self, args: Arguments<'_>) -> Result<()>
Writes a formatted string into this writer, returning any error encountered. Read more
1.0.0Source
fn by_ref(&mut self) -> &mut Selfwhere
    Self: Sized,
Creates a “by reference” adapter for this instance of Write. Read more
1.61.0Source
impl<const N: usize> Write for Cursor<[u8; N]>
Source
fn write(&mut self, buf: &[u8]) -> Result<usize>
Writes a buffer into this writer, returning how many bytes were written. Read more
Source
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>
Like write, except that it writes from a slice of buffers. Read more
Source
fn is_write_vectored(&self) -> bool
🔬This is a nightly-only experimental API. (can_vector #69941)
Determines if this Writer has an efficient write_vectored implementation. Read more
Source
fn write_all(&mut self, buf: &[u8]) -> Result<()>
Attempts to write an entire buffer into this writer. Read more
Source
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()>
🔬This is a nightly-only experimental API. (write_all_vectored #70436)
Attempts to write multiple buffers into this writer. Read more
Source
fn flush(&mut self) -> Result<()>
Flushes this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
1.0.0Source
fn write_fmt(&mut self, args: Arguments<'_>) -> Result<()>
Writes a formatted string into this writer, returning any error encountered. Read more
1.0.0Source
fn by_ref(&mut self) -> &mut Selfwhere
    Self: Sized,
Creates a “by reference” adapter for this instance of Write. Read more
1.5.0Source
impl<A> Write for Cursor<Box<[u8], A>>where
    A: Allocator,
Source
fn write(&mut self, buf: &[u8]) -> Result<usize>
Writes a buffer into this writer, returning how many bytes were written. Read more
Source
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>
Like write, except that it writes from a slice of buffers. Read more
Source
fn is_write_vectored(&self) -> bool
🔬This is a nightly-only experimental API. (can_vector #69941)
Determines if this Writer has an efficient write_vectored implementation. Read more
Source
fn write_all(&mut self, buf: &[u8]) -> Result<()>
Attempts to write an entire buffer into this writer. Read more
Source
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()>
🔬This is a nightly-only experimental API. (write_all_vectored #70436)
Attempts to write multiple buffers into this writer. Read more
Source
fn flush(&mut self) -> Result<()>
Flushes this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
1.0.0Source
fn write_fmt(&mut self, args: Arguments<'_>) -> Result<()>
Writes a formatted string into this writer, returning any error encountered. Read more
1.0.0Source
fn by_ref(&mut self) -> &mut Selfwhere
    Self: Sized,
Creates a “by reference” adapter for this instance of Write. Read more
1.0.0Source
impl<A> Write for Cursor<Vec<u8, A>>where
    A: Allocator,
Source
fn write(&mut self, buf: &[u8]) -> Result<usize>
Writes a buffer into this writer, returning how many bytes were written. Read more
Source
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>
Like write, except that it writes from a slice of buffers. Read more
Source
fn is_write_vectored(&self) -> bool
🔬This is a nightly-only experimental API. (can_vector #69941)
Determines if this Writer has an efficient write_vectored implementation. Read more
Source
fn write_all(&mut self, buf: &[u8]) -> Result<()>
Attempts to write an entire buffer into this writer. Read more
Source
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()>
🔬This is a nightly-only experimental API. (write_all_vectored #70436)
Attempts to write multiple buffers into this writer. Read more
Source
fn flush(&mut self) -> Result<()>
Flushes this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
1.0.0Source
fn write_fmt(&mut self, args: Arguments<'_>) -> Result<()>
Writes a formatted string into this writer, returning any error encountered. Read more
1.0.0Source
fn by_ref(&mut self) -> &mut Selfwhere
    Self: Sized,
Creates a “by reference” adapter for this instance of Write. Read more
1.0.0Source
impl<T: Eq> Eq for Cursor<T>
1.0.0Source
impl<T> StructuralPartialEq for Cursor<T>

Auto Trait Implementations

impl<T> Freeze for Cursor<T>where
    T: Freeze,
impl<T> RefUnwindSafe for Cursor<T>where
    T: RefUnwindSafe,
impl<T> Send for Cursor<T>where
    T: Send,
impl<T> Sync for Cursor<T>where
    T: Sync,
impl<T> Unpin for Cursor<T>where
    T: Unpin,
impl<T> UnwindSafe for Cursor<T>where
    T: UnwindSafe,

Blanket Implementations

Source
impl<T> Any for Twhere
    T: 'static + ?Sized,
Source
fn type_id(&self) -> TypeId
Gets the TypeId of self. Read more
Source
impl<T> Borrow<T> for Twhere
    T: ?Sized,
Source
fn borrow(&self) -> &T
Immutably borrows from an owned value. Read more
Source
impl<T> BorrowMut<T> for Twhere
    T: ?Sized,
Source
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
Source
impl<T> CloneToUninit for Twhere
    T: Clone,
Source
unsafe fn clone_to_uninit(&self, dest: *mut u8)
🔬This is a nightly-only experimental API. (clone_to_uninit #126799)
Performs copy-assignment from self to dest. Read more
Source
impl<T> From<T> for T
Source
fn from(t: T) -> T

Returns the argument unchanged.

Source
impl<T, U> Into<U> for Twhere
    U: From<T>,
Source
fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source
impl<T> ToOwned for Twhere
    T: Clone,
Source
type Owned = T
The resulting type after obtaining ownership.
Source
fn to_owned(&self) -> T
Creates owned data from borrowed data, usually by cloning. Read more
Source
fn clone_into(&self, target: &mut T)
Uses borrowed data to replace owned data, usually by cloning. Read more
Source
impl<T, U> TryFrom<U> for Twhere
    U: Into<T>,
Source
type Error = Infallible
The type returned in the event of a conversion error.
Source
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
Performs the conversion.
Source
impl<T, U> TryInto<U> for Twhere
    U: TryFrom<T>,
Source
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
Source
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
Performs the conversion.

© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.
https://doc.rust-lang.org/std/io/struct.Cursor.html