概述

此crate定义了一个带有游标的缓冲区，以及一些对缓冲区的有用操作。

注意事项

1. PeekableBuffer的泛型参数必须实现Clone
2. 如果您的PeekableBuffer包含接近usize.MAX个元素，索引操作可能会失败

快速入门

在Cargo.toml

[dependencies]
peekable_buffer = "1.0.0"

使用

let v = vec![1, 2, 3, 4, 5];
let mut stream = PeekableBuffer::new(&v);

assert!(!stream.is_at_end());
assert_eq!(stream.pos(), 0);
assert_eq!(stream.current(), Some(&1));

stream.advance();
assert_eq!(stream.pos(), 1);
assert_eq!(stream.current(), Some(&2));

assert_eq!(stream.lookaround(-1), Some(&1));
assert_eq!(stream.lookaround(-10), None);

stream.shift(3);
assert_eq!(stream.current(), Some(&5));

assert_eq!(stream.consume(), Some(&5));
assert!(stream.is_at_end());
assert_eq!(stream.current(), None);

可用操作

这些直接来自源代码。

/// Creates a `Stream` object that owns all elements of `&[T]` via cloning.
pub fn new<E>(elements: E) -> Self
    where E: AsRef<[T]>;

/// Returns true if the stream has reached the end.
pub fn is_at_end(&self) -> bool;

/// Returns the number of elements in the stream.
pub fn len(&self) -> usize;

/// Returns a reference to the element `offset` positions away from the
/// element currently being pointed to by the stream pointer. If the
/// computed offset is outside the bounds of the stream, `None` is returned.
pub fn lookaround(&self, offset: i64) -> Option<&T>;

/// Returns a reference to the element just after the element currently
/// being pointed to by the stream pointer. This is equivalent to calling
/// `lookaround(1)`.
pub fn peek(&self) -> Option<&T>;

/// Returns a reference to the element currently being pointed to by the
/// stream pointer. This is equivalent to calling `lookaround(0)`.
pub fn current(&self) -> Option<&T>;

/// Shifts the stream pointer by `offset` positions. The computed offset
/// will be within the range `[0, len()]`. If the computed offset is less
/// than 0, the stream pointer will point to the first element. If the
/// computed offset is greater than `len() - 1`, the stream pointer will
/// point to the end and `is_at_end()` returns true.
pub fn shift(&mut self, offset: i64) -> ();

/// A convenience method that advances the stream pointer by 1. If the
/// stream is at the end, no action is taken. This is equivalent to calling
/// `shift(1)`.
pub fn advance(&mut self) -> ();

/// Sets the zero-indexed position of the stream pointer. If the
/// given `pos` is outside of the range of the stream length, the
/// stream pointer will be set to `len()`.
pub fn set_pos(&mut self, pos: usize) -> usize;

/// Returns the current zero-indexed position of the stream pointer. The
/// returned value is in the range `[0, len()]`.
pub fn pos(&self) -> usize;

/// Returns a reference to the element currently being pointed to by the
/// stream pointer, then advances the pointer by 1.
pub fn consume(&mut self) -> Option<&T>;

/// Returns an iterator containing elements that satisfy the given
/// predicate, starting from the element currently pointed to by the stream
/// pointer, up to either the end of the stream, or when the predicate
/// returns fall, whichever comes first.
pub fn take_while<P>(&mut self, predicate: P) -> impl Iterator<Item = &T>
    where P: Fn(&T) -> bool;

/// Returns an iterator containing all elements in the range
/// `[pos(), pos() + n)`. The stream pointer will point to either the
/// end of the stream, or the element at `pos() + n`, whichever is
/// first. If `pos() + n` is outside the bounds of the stream, then
/// the rest of the stream is consumed and `is_at_end()` returns true.
pub fn take(&mut self, n: usize) -> impl Iterator<Item = &T>;

/// Returns true if the current element matches the given predicate, false
/// otherwise. The function will return false if the stream is at the end
/// regardless of the predicate.
pub fn accept<P>(&self, predicate: P) -> bool
    where P: Fn(&T) -> bool;

/// Returns a new `PeekableBuffer` containing all elements from the range
/// `[from_inc, len() - 1]`, cloning the required elements into their
/// own iterable. If `from_inc` is outside the range of the stream, an
/// empty `PeekableBuffer` is returned.
pub fn slice_from(&self, from_inc: usize) -> PeekableBuffer<T>;

/// Returns a new `PeekableBuffer` containing all elements from the range
/// `[from_inc, to_exc - 1]`, cloning the required elements into their
/// own iterable. If `from_inc > to_exc`, this function will panic.
/// Otherwise, if `from_inc` are greater than `len()`, an
/// empty `PeekableBuffer` is returned. If `from_inc == to_exc`, an
/// empty `PeekableBuffer` is returned as well.
pub fn slice_between(&self, from_inc: usize, to_exc: usize) -> PeekableBuffer<T>;

错误处理

大多数API已为更常见的“奇怪输入”情况定义了行为，因此在此库中找不到错误处理。所有返回缓冲区中元素引用的库都返回为Option<&T>。

例外是函数slice_between，在from_inc > to_exc的情况下会panic。在传递参数给此特定函数之前，请先进行LBYL。