Fade away

Appearance

Struct std::io::Cursor ​

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

Cursor 包装内存中的缓冲区，并为其提供 Seek 实现。

Cursors 与内存缓冲区一起使用，任何实现 AsRef<[u8]>，以允许它们实现 Read 或者 Write，从而允许这些缓冲区在您可能使用进行实际 I/O 的读取器或写入器的任何地方使用。

标准库在通常用作缓冲区的各种类型上实现了一些 I/O traits，例如 Cursor<Vec<u8>> and Cursor<&[u8]>。

Cursor是什么

是一个 实现了 Read/ Write/ Seek的内存缓冲区

内部包裹一个 T（通常是 Vec<u8>或 &[u8]）

自己维护一个 当前读写位置（position）

它不是文件，也不是网络流，只是内存 I/O

Cursor能做什么

Read：像文件一样 .read()

Write：写入内存

Seek：seek(SeekFrom::Start(100))

内部position：自动移动指针

rust
use std::io::{Cursor, Read, Seek, SeekFrom};

let mut c = Cursor::new(vec![1,2,3,4]);
let mut buf = [0u8; 2];

c.read_exact(&mut buf); // 读到 [1,2]
c.seek(SeekFrom::Start(0)); // 回到开头

示例

我们可能想在生产代码中将字节写入 File，但在测试中使用内存缓冲区。我们可以做到这一点 Cursor:

rust
use std::io::prelude::*;
use std::io::{self, SeekFrom};
use std::fs::File;

// 我们编写的库函数
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])?;
    }

    // 一切顺利
    Ok(())
}

// 这是一些使用此库函数的代码。
// 我们可能想在此处使用 BufReader 来提高效率，但让我们继续关注此示例。
let mut file = File::create("foo.txt")?;

write_ten_bytes_at_end(&mut file)?;

// 现在让我们编写一个测试
#[test]
fn test_writes_bytes() {
    // 设置一个真实的文件要比内存中的缓冲区慢得多，让我们用游标代替
    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 ​

impl<T> Cursor<T> ​

new ​

创建一个新的游标来包装所提供的底层内存缓冲区。

即使底层缓冲区 (例如 Vec) 不为空，游标的初始位置也为 0。 因此，写入游标是从覆盖 Vec 内容开始的，而不是追加到它的上面。

rust
pub fn new(inner: T) -> Cursor<T>

返回值：

rust
fn main() {
    use std::io::Cursor;
    let v = vec![1, 2, 3];
    let buff = Cursor::new(v);

    println!("{:#?}", buff);
    /*
    Cursor {
        inner: [
            1,
            2,
            3,
        ],
        pos: 0,
    }
     */
}

into_inner ​

消费这个游标，返回底层值。

rust
pub fn into_inner(self) -> T

返回值：返回底层值

rust
use std::io::Cursor;

fn main() {
    let v = vec![1, 2, 3];
    let buff = Cursor::new(v);

    let vec = buff.into_inner();

    println!("{:#?}", vec);
	/*
	[
		1,
		2,
		3,
	]
	 */
}

get_ref ​

获取此游标中的底层值的引用

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

返回值：返回底层值的不可变引用

rust
use std::io::Cursor;

fn main() {
    let v = vec![1, 2, 3];
    let buff = Cursor::new(v);

    let vec = buff.get_ref();

    println!("{:#?}", vec);
	/*
	[
		1,
		2,
		3,
	]
	 */
}

get_mut ​

获取此游标中底层值的可变引用。

应注意避免修改底层值的内部 I/O 状态，因为它可能破坏此游标的位置。

rust
pub fn get_mut(&self) -> &mut T

返回值：返回底层值的可变引用

rust
use std::io::Cursor;

fn main() {
    let v = vec![1, 2, 3];
    let mut buff = Cursor::new(v);

    let vec = buff.get_mut();
	vec.push(4);

    println!("{:#?}", vec);
    /*
    [
        1,
        2,
        3,
		4,
    ]
     */
}

position ​

返回此游标的当前位置。

rust
pub fn position(&self) -> u64

返回值：返回此游标的当前位置。

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

set_position ​

设置此游标的位置。

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

参数：

  • pos：需要设置的位置
rust
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);

impl<T: AsRef<[u8]>> Cursor<T> ​

remaining_slice ​

获取还没读过的内存切片

rust
pub fn remaining_slice(&self) -> &[u8]

返回值：返回 从当前 position 开始，到末尾的所有未读字节

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

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

assert_eq!(buff.remaining_slice(), &[1, 2, 3, 4, 5]);

buff.set_position(2);
assert_eq!(buff.remaining_slice(), &[3, 4, 5]);

buff.set_position(4);
assert_eq!(buff.remaining_slice(), &[5]);

buff.set_position(6);
assert_eq!(buff.remaining_slice(), &[]);

is_empty ​

判断是否已经没有数据可读

rust
pub fn is_empty(&self) -> bool

返回值：根据是否有剩余可读数据，返回bool值

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

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

buff.set_position(2);
assert!(!buff.is_empty());

buff.set_position(5);
assert!(buff.is_empty());

buff.set_position(10);
assert!(buff.is_empty());

Trait Implementations ​

impl<T> BufRead for Cursor<T> ​

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

fill_buf ​

返回内部缓冲区的内容，如果内部缓冲区为空，则使用内部 reader 中的更多数据填充内部缓冲区。

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

consume ​

告诉此缓冲区 amt 字节已从缓冲区中消耗掉，因此在调用 read 时不再应返回它们。

rust
fn consume(&mut self, amt: usize)

has_data_left ​

检查底层 Read 是否有任何数据可供读取。

rust
fn has_data_left(&mut self) -> Result<bool>

read_until ​

将所有字节读入 buf，直到到达定界符 byte 或 EOF。

rust
fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> Result<usize>

read_line ​

读取所有字节直到到达换行符 (0xA 字节)，并将它们，追加，到提供的 String 缓冲区。

rust
fn read_line(&mut self, buf: &mut String) -> Result<usize>

split ​

返回对该字节 byte 上的 reader 拆分内容的迭代器。

rust
fn split(self, byte: u8) -> Split<Self> 
where
  Self: Sized,

lines ​

返回此 reader 的各行上的迭代器。

rust
fn lines(self) -> Lines<Self> 
where
  Self: Sized,

impl<T> Clone for Cursor<T> ​

rust
impl<T> Clone for Cursor<T>
where
  T: Clone,

clone ​

返回值的副本。

rust
fn clone(&self) -> Self

clone_from ​

从 other执行复制分配。

rust
fn clone_from(&mut self, other: &Self)

impl<T: Debug> Debug for Cursor<T> ​

fmt ​

使用给定的格式化程序格式化该值。

rust
fn fmt(&self, f: &mut Formatter<'_>) -> Result

impl<T: Default> Default for Cursor<T> ​

default ​

返回类型的 “默认值”。

rust
fn default() -> Cursor<T>

impl<T: PartialEq> PartialEq<Cursor<T>> for Cursor<T> ​

eq ​

此方法测试 self 和 other 值是否相等，并由 == 使用。

rust
fn eq(&self, other: &Cursor<T>) -> bool

ne ​

此方法测试 !=。 默认实现几乎总是足够的，并且不应在没有充分理由的情况下被覆盖。

rust
fn ne(&self, other: &Rhs) -> bool

impl<T> Read for Cursor<T> ​

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

read ​

从该源中提取一些字节到指定的缓冲区中，返回读取的字节数。

rust
fn read(&mut self, buf: &mut [u8]) -> Result<usize>

read_buf ​

从此源中提取一些字节到指定的缓冲区中。

rust
fn read_buf(&mut self, cursor: BorrowedCursor<'_>) -> Result<()>

read_vectored ​

与 read 相似，不同之处在于它读入缓冲区的一部分。

rust
fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

is_read_vectored ​

确定此 Read 是否具有有效的 read_vectored 实现。

rust
fn is_read_vectored(&self) -> bool

read_exact ​

读取填充 buf 所需的确切字节数。

rust
fn read_exact(&mut self, buf: &mut [u8]) -> Result<()>

read_to_end ​

读取所有字节，直到此源中的 EOF 为止，然后将它们放入 buf。

rust
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>

read_to_string ​

读取这个源中的所有字节，直到 EOF 为止，然后将它们追加到 buf。

rust
fn read_to_string(&mut self, buf: &mut String) -> Result<usize>

read_buf_exact ​

读取填充 cursor 所需的确切字节数。

rust
fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<()>

by_ref ​

为这个 Read 实例创建一个 “by reference” 适配器。

rust
fn by_ref(&mut self) -> &mut Self
where
  Self: Sized,

bytes ​

将此 Read 实例的字节数转换为 Iterator。

rust
fn bytes(self) -> Bytes<Self> 
where
  Self: Sized,

chain ​

创建一个适配器，将这个流与另一个链接起来。

rust
fn chain<R: Read>(self, next: R) -> Chain<Self, R> 
where
  Self: Sized,

take ​

创建一个适配器，最多从中读取 limit 个字节。

rust
fn take(self, limit: u64) -> Take<Self> 
where
  Self: Sized,

impl<T> Seek for Cursor<T> ​

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

seek ​

在流中寻找以字节为单位的偏移量。

rust
fn seek(&mut self, style: SeekFrom) -> Result<u64>

stream_len ​

返回此流的长度 (以字节为单位)。

rust
fn stream_len(&mut self) -> Result<u64>

stream_position ​

从流的开头返回当前查找位置。

rust
fn stream_position(&mut self) -> Result<u64>

rewind ​

返回到流的开头。

rust
fn rewind(&mut self) -> Result<()>

impl Write for Cursor<&mut [u8]> ​

write ​

在此 writer 中写入一个缓冲区，返回写入的字节数。

rust
fn write(&mut self, buf: &[u8]) -> Result<usize>

write_vectored ​

类似于 write，不同之处在于它是从缓冲区切片中写入数据的。

rust
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>

is_write_vectored ​

确定此 Writer 是否具有有效的 write_vectored 实现。

rust
fn is_write_vectored(&self) -> bool

flush ​

刷新此输出流，确保所有中间缓冲的内容均到达其目的地。

rust
fn flush(&mut self) -> Result<()>

write_all ​

尝试将整个缓冲区写入此 writer。

rust
fn write_all(&mut self, buf: &[u8]) -> Result<()>

write_all_vectored ​

尝试将多个缓冲区写入此 writer。

rust
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()>

write_fmt ​

将格式化的字符串写入此 writer，返回遇到的任何错误。

rust
fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<()>

by_ref ​

为这个 Write 实例创建一个 “by reference” 适配器。

rust
fn by_ref(&mut self) -> &mut Self
where
  Self: Sized,

impl<A> Write for Cursor<&mut Vec<u8, A>> ​

rust
impl<A> Write for Cursor<&mut Vec<u8, A>>
where
  A: Allocator,

write ​

在此 writer 中写入一个缓冲区，返回写入的字节数。

rust
fn write(&mut self, buf: &[u8]) -> Result<usize>

write_vectored ​

类似于 write，不同之处在于它是从缓冲区切片中写入数据的。

rust
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>

is_write_vectored ​

确定此 Writer 是否具有有效的 write_vectored 实现。

rust
fn is_write_vectored(&self) -> bool

flush ​

刷新此输出流，确保所有中间缓冲的内容均到达其目的地。

rust
fn flush(&mut self) -> Result<()>

write_all ​

尝试将整个缓冲区写入此 writer。

rust
fn write_all(&mut self, buf: &[u8]) -> Result<()>

write_all_vectored ​

尝试将多个缓冲区写入此 writer。

rust
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()>

write_fmt ​

将格式化的字符串写入此 writer，返回遇到的任何错误。

rust
fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<()>

by_ref ​

为这个 Write 实例创建一个 “by reference” 适配器。

rust
fn by_ref(&mut self) -> &mut Self
where
  Self: Sized,

impl<const N: usize> Write for Cursor<[u8; N]> ​

write ​

在此 writer 中写入一个缓冲区，返回写入的字节数。

rust
fn write(&mut self, buf: &[u8]) -> Result<usize>

write_vectored ​

类似于 write，不同之处在于它是从缓冲区切片中写入数据的。

rust
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>

is_write_vectored ​

确定此 Writer 是否具有有效的 write_vectored 实现。

rust
fn is_write_vectored(&self) -> bool

flush ​

刷新此输出流，确保所有中间缓冲的内容均到达其目的地。

rust
fn flush(&mut self) -> Result<()>

write_all ​

尝试将整个缓冲区写入此 writer。

rust
fn write_all(&mut self, buf: &[u8]) -> Result<()>

write_all_vectored ​

尝试将多个缓冲区写入此 writer。

rust
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()>

write_fmt ​

将格式化的字符串写入此 writer，返回遇到的任何错误。

rust
fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<()>

by_ref ​

为这个 Write 实例创建一个 “by reference” 适配器。

rust
fn by_ref(&mut self) -> &mut Self
where
  Self: Sized,

impl<A> Write for Cursor<Box<[u8], A>> ​

rust
impl<A> Write for Cursor<Box<[u8], A>>
where
  A: Allocator,

write ​

在此 writer 中写入一个缓冲区，返回写入的字节数。

rust
fn write(&mut self, buf: &[u8]) -> Result<usize>

write_vectored ​

类似于 write，不同之处在于它是从缓冲区切片中写入数据的。

rust
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>

is_write_vectored ​

确定此 Writer 是否具有有效的 write_vectored 实现。

rust
fn is_write_vectored(&self) -> bool

flush ​

刷新此输出流，确保所有中间缓冲的内容均到达其目的地。

rust
fn flush(&mut self) -> Result<()>

write_all ​

尝试将整个缓冲区写入此 writer。

rust
fn write_all(&mut self, buf: &[u8]) -> Result<()>

write_all_vectored ​

尝试将多个缓冲区写入此 writer。

rust
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()>

write_fmt ​

将格式化的字符串写入此 writer，返回遇到的任何错误。

rust
fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<()>

by_ref ​

为这个 Write 实例创建一个 “by reference” 适配器。

rust
fn by_ref(&mut self) -> &mut Self
where
  Self: Sized,

impl<A> Write for Cursor<Vec<u8, A>> ​

rust
impl<A> Write for Cursor<Vec<u8, A>>
where
  A: Allocator,

write ​

在此 writer 中写入一个缓冲区，返回写入的字节数。

rust
fn write(&mut self, buf: &[u8]) -> Result<usize>

write_vectored ​

类似于 write，不同之处在于它是从缓冲区切片中写入数据的。

rust
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>

is_write_vectored ​

确定此 Writer 是否具有有效的 write_vectored 实现。

rust
fn is_write_vectored(&self) -> bool

flush ​

刷新此输出流，确保所有中间缓冲的内容均到达其目的地。

rust
fn flush(&mut self) -> Result<()>

write_all ​

尝试将整个缓冲区写入此 writer。

rust
fn write_all(&mut self, buf: &[u8]) -> Result<()>

write_all_vectored ​

尝试将多个缓冲区写入此 writer。

rust
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()>

write_fmt ​

将格式化的字符串写入此 writer，返回遇到的任何错误。

rust
fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<()>

by_ref ​

为这个 Write 实例创建一个 “by reference” 适配器。

rust
fn by_ref(&mut self) -> &mut Self
where
  Self: Sized,

impl<T: Eq> Eq for Cursor<T> ​

impl<T> StructuralEq for Cursor<T> ​

impl<T> StructuralPartialEq for Cursor<T> ​

Auto Trait Implementations ​

impl<T> RefUnwindSafe for Cursor<T> ​

rust
impl<T> RefUnwindSafe for Cursor<T>
where
  T: RefUnwindSafe,

impl<T> Send for Cursor<T> ​

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

impl<T> Sync for Cursor<T> ​

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

impl<T> Unpin for Cursor<T> ​

rust
impl<T> Unpin for Cursor<T>
where
  T: Unpin,

impl<T> UnwindSafe for Cursor<T> ​

rust
impl<T> UnwindSafe for Cursor<T>
where
  T: UnwindSafe,

Blanket Implementations ​

impl<T> Any for T ​

rust
impl<T> Any for T
where
  T: 'static + ?Sized,

impl<T> Borrow<T> for T ​

rust
impl<T> Borrow<T> for T
where
  T: ?Sized,

impl<T> BorrowMut<T> for T ​

rust
impl<T> BorrowMut<T> for T
where
  T: ?Sized,

impl<T> From<T> for T ​

impl<T, U> Into<U> for T ​

rust
impl<T, U> Into<U> for T
where
  U: From<T>,

impl<T> ToOwned for T ​

rust
impl<T> ToOwned for T
where
  T: Clone,

impl<T, U> TryFrom<U> for T ​

rust
impl<T, U> TryFrom<U> for T
where
  U: Into<T>,

impl<T, U> TryInto<U> for T ​

rust
impl<T, U> TryInto<U> for T
where
  U: TryFrom<T>,

MIT Licensed

Copyright © 2024-present xarzhi