Struct AsyncPeekable 

pub struct AsyncPeekable<R, B = DefaultBuffer> { /* private fields */ }

Available on crate feature future only.

A wrapper around an AsyncRead types to make them support AsyncPeek methods.

Implementations

impl<R> AsyncPeekable<R>

pub fn new(reader: R) -> Self

Creates a new AsyncPeekable which will wrap the given reader.

The peek buffer will have the default capacity.

Examples

use peekable::future::AsyncPeekable;

let reader = futures::io::Cursor::new(&b"hello"[..]);
let peekable = AsyncPeekable::new(reader);

pub fn with_capacity(reader: R, capacity: usize) -> Self

Creates a new peekable wrapper around the given reader with the specified capacity for the peek buffer.

Examples

use peekable::future::AsyncPeekable;

let reader = futures::io::Cursor::new([0; 1024]);
let peekable = AsyncPeekable::with_capacity(reader, 1024);

impl<R, B> AsyncPeekable<R, B>

pub fn with_buffer(reader: R) -> Self

where B: Buffer,

Creates a new AsyncPeekable which will wrap the given reader. This method allows you to specify a custom buffer type.

The peek buffer will have the default capacity.

Examples

use peekable::future::AsyncPeekable;

let reader = futures::io::Cursor::new(&b"hello"[..]);
let peekable: AsyncPeekable<_, Vec<u8>> = AsyncPeekable::with_buffer(reader);

pub fn with_capacity_and_buffer(reader: R, capacity: usize) -> Self

where B: Buffer,

Creates a new peekable wrapper around the given reader with the specified capacity for the peek buffer. This method allows you to specify a custom buffer type.

Examples

use peekable::future::AsyncPeekable;
use std::vec::Vec;

let reader = futures::io::Cursor::new([0; 1024]);
let peekable: AsyncPeekable<_, Vec<u8>> = AsyncPeekable::with_capacity_and_buffer(reader, 1024);

pub fn consume(&mut self) -> B

where B: Buffer,

Consumes the peek buffer and returns the buffer.

Examples

use peekable::future::AsyncPeekable;

let reader = futures::io::Cursor::new([1, 2, 3, 4]);
let mut peekable: AsyncPeekable<_> = AsyncPeekable::from(reader);

let mut output = [0u8; 2];
let bytes = peekable.peek(&mut output).await.unwrap();
assert_eq!(bytes, 2);
assert_eq!(output, [1, 2]);

let buffer = peekable.consume();
assert_eq!(buffer.as_slice(), [1, 2].as_slice());

let mut output = [0u8; 2];
let bytes = peekable.peek(&mut output).await.unwrap();
assert_eq!(bytes, 2);
assert_eq!(output, [3, 4]);

pub fn consume_in_place(&mut self)

where B: Buffer,

Consumes the peek buffer in place so that the peek buffer can be reused and avoid allocating.

Examples

use peekable::future::AsyncPeekable;

let reader = futures::io::Cursor::new([1, 2, 3, 4]);
let mut peekable: AsyncPeekable<_> = AsyncPeekable::from(reader);

let mut output = [0u8; 2];
let bytes = peekable.peek(&mut output).await.unwrap();
assert_eq!(bytes, 2);
assert_eq!(output, [1, 2]);

peekable.consume_in_place();

let mut output = [0u8; 2];
let bytes = peekable.peek(&mut output).await.unwrap();
assert_eq!(bytes, 2);
assert_eq!(output, [3, 4]);

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

where B: Buffer,

Returns the bytes already be peeked into memory and a mutable reference to the underlying reader.

WARNING: If you invoke AsyncRead or AsyncReadExt methods on the underlying reader, may lead to unexpected read behaviors.

Examples

use peekable::future::AsyncPeekable;

let reader = futures::io::Cursor::new([1, 2, 3, 4]);
let mut peekable: AsyncPeekable<_> = AsyncPeekable::from(reader);

let mut output = [0u8; 2];
let bytes = peekable.peek(&mut output).await.unwrap();
assert_eq!(bytes, 2);
assert_eq!(output, [1, 2]);

let (buffer, reader) = peekable.get_mut();
assert_eq!(buffer, [1, 2].as_slice());

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

where B: Buffer,

Returns the bytes already be peeked into memory and a reference to the underlying reader.

WARNING: If you invoke AsyncRead or AsyncReadExt methods on the underlying reader, may lead to unexpected read behaviors.

Examples

use peekable::future::AsyncPeekable;

let reader = futures::io::Cursor::new([1, 2, 3, 4]);
let mut peekable: AsyncPeekable<_> = AsyncPeekable::from(reader);

let mut output = [0u8; 2];
let bytes = peekable.peek(&mut output).await.unwrap();
assert_eq!(bytes, 2);
assert_eq!(output, [1, 2]);

let (buffer, reader) = peekable.get_ref();
assert_eq!(buffer, [1, 2].as_slice());

pub fn into_components(self) -> (B, R)

Consumes the AsyncPeekable, returning the a vec may contain the bytes already be peeked into memory and the wrapped reader.

Examples

use peekable::future::AsyncPeekable;

let reader = futures::io::Cursor::new([1, 2, 3, 4]);
let mut peekable = AsyncPeekable::from(reader);

let mut output = [0u8; 2];
let bytes = peekable.peek(&mut output).await.unwrap();
assert_eq!(bytes, 2);
assert_eq!(output, [1, 2]);

let (buffer, reader) = peekable.into_components();
assert_eq!(buffer.as_slice(), [1, 2].as_slice());

impl<R, B> AsyncPeekable<R, B>

where R: AsyncRead + Unpin, B: Buffer,

pub fn peek<'a>(&'a mut self, buf: &'a mut [u8]) -> Peek<'a, R, B>

where Self: Unpin,

Tries to peek some bytes directly into the given buf in asynchronous manner, returning a future type.

The returned future will resolve to the number of bytes read once the read operation is completed.

Examples

use futures::io::{AsyncReadExt, Cursor};
use peekable::future::AsyncPeekExt;


let mut peekable = Cursor::new([1, 2, 3, 4]).peekable();
let mut output = [0u8; 5];

let bytes = peekable.peek(&mut output[..3]).await?;

// This is only guaranteed to be 4 because `&[u8]` is a synchronous
// reader. In a real system you could get anywhere from 1 to
// `output.len()` bytes in a single read.
assert_eq!(bytes, 3);
assert_eq!(output, [1, 2, 3, 0, 0]);

// you can peek mutiple times

let bytes = peekable.peek(&mut output[..]).await?;
assert_eq!(bytes, 4);
assert_eq!(output, [1, 2, 3, 4, 0]);

// you can read after peek
let mut output = [0u8; 5];
let bytes = peekable.read(&mut output[..2]).await?;
assert_eq!(bytes, 2);
assert_eq!(output, [1, 2, 0, 0, 0]);

// peek after read
let mut output = [0u8; 5];
let bytes = peekable.peek(&mut output[..]).await?;
assert_eq!(bytes, 2);
assert_eq!(output, [3, 4, 0, 0, 0]);

pub fn peek_vectored<'a>( &'a mut self, bufs: &'a mut [IoSliceMut<'a>], ) -> PeekVectored<'a, R, B>

where Self: Unpin,

Creates a future which will peek from the AsyncPeek into bufs using vectored IO operations.

The returned future will resolve to the number of bytes read once the read operation is completed.

pub fn peek_exact<'a>(&'a mut self, buf: &'a mut [u8]) -> PeekExact<'a, R, B>

where Self: Unpin,

Creates a future which will peek exactly enough bytes to fill buf, returning an error if end of file (EOF) is hit sooner.

The returned future will resolve once the read operation is completed.

In the case of an error the buffer and the object will be discarded, with the error yielded.

Examples

use futures::io::{AsyncReadExt, Cursor};
use peekable::future::AsyncPeekExt;

let mut peekable = Cursor::new([1, 2, 3, 4]).peekable();
let mut output = [0u8; 4];

peekable.peek_exact(&mut output).await?;

assert_eq!(output, [1, 2, 3, 4]);

// read after peek
let mut output = [0u8; 2];

peekable.read_exact(&mut output[..]).await?;

assert_eq!(output, [1, 2]);

// peek after read
let mut output = [0u8; 2];
peekable.peek_exact(&mut output).await?;

assert_eq!(output, [3, 4]);

EOF is hit before buf is filled

use futures::io::{self, AsyncReadExt, Cursor};
use peekable::future::AsyncPeekExt;

let mut peekable = Cursor::new([1, 2, 3, 4]).peekable();
let mut output = [0u8; 5];

let result = peekable.peek_exact(&mut output).await;
assert_eq!(
  result.unwrap_err().kind(),
  std::io::ErrorKind::UnexpectedEof
);

let result = peekable.peek_exact(&mut output[..4]).await;
assert!(result.is_ok());
assert_eq!(output, [1, 2, 3, 4, 0]);

pub fn peek_to_end<'a>( &'a mut self, buf: &'a mut Vec<u8>, ) -> PeekToEnd<'a, R, B>

where Self: Unpin,

Creates a future which will peek all the bytes from this AsyncPeek.

On success the total number of bytes peek is returned.

Examples

use futures::io::{AsyncReadExt, Cursor};
use peekable::future::AsyncPeekExt;

let mut peekable = Cursor::new([1, 2, 3, 4]).peekable();
let mut output = Vec::with_capacity(4);

let bytes = peekable.peek_to_end(&mut output).await?;

assert_eq!(bytes, 4);
assert_eq!(output, vec![1, 2, 3, 4]);

// read after peek
let mut output = Vec::with_capacity(4);

let bytes = peekable.read_to_end(&mut output).await?;

assert_eq!(bytes, 4);
assert_eq!(output, vec![1, 2, 3, 4]);

pub fn peek_to_string<'a>( &'a mut self, buf: &'a mut String, ) -> PeekToString<'a, R, B>

where Self: Unpin,

Creates a future which will peek all the bytes from this AsyncPeek.

On success the total number of bytes peek is returned.

Examples

use futures::io::{AsyncReadExt, Cursor};
use peekable::future::AsyncPeekExt;

let mut peekable = Cursor::new(&b"1234"[..]).peekable();
let mut buffer = String::with_capacity(4);

let bytes = peekable.peek_to_string(&mut buffer).await?;

assert_eq!(bytes, 4);
assert_eq!(buffer, String::from("1234"));

// read after peek
let mut buffer = String::with_capacity(4);
let bytes = peekable.peek_to_string(&mut buffer).await?;

assert_eq!(bytes, 4);
assert_eq!(buffer, String::from("1234"));

// peek invalid utf-8
let mut peekable = Cursor::new([255; 4]).peekable();
let mut buffer = String::with_capacity(4);
assert!(peekable.peek_to_string(&mut buffer).await.is_err());

pub fn fill_peek_buf(&mut self) -> FillPeekBuf<'_, R, B>

Try to fill the peek buffer with more data. Returns the number of bytes peeked.

Examples

use futures::io::Cursor;
use futures::AsyncReadExt;
use peekable::future::AsyncPeekExt;


let mut peekable = Cursor::new([1, 2, 3, 4]).peekable_with_capacity(5);
let mut output = [0u8; 4];

peekable.peek_exact(&mut output[..1]).await.unwrap();
assert_eq!(output, [1, 0, 0, 0]);

let bytes = peekable.fill_peek_buf().await.unwrap();
assert_eq!(bytes, 3);

let bytes = peekable.peek(&mut output).await.unwrap();
assert_eq!(output, [1, 2, 3, 4].as_slice());

let readed = peekable.read(&mut output).await.unwrap();
assert_eq!(readed, 4);

Trait Implementations

impl<R, B> AsyncPeek for AsyncPeekable<R, B>

where R: AsyncRead, B: Buffer,

fn poll_peek( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize>>

Attempt to peek from the AsyncPeek into buf.

fn poll_peek_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize>>

Attempt to read from the AsyncPeek into bufs using vectored IO operations.

impl<R, B> AsyncRead for AsyncPeekable<R, B>

where R: AsyncRead, B: Buffer,

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize, Error>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl<W, B> AsyncWrite for AsyncPeekable<W, B>

where W: AsyncWrite,

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

Attempt to write bytes from bufs into the object using vectored IO operations.

impl<R: Debug, B: Debug> Debug for AsyncPeekable<R, B>

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

Formats the value using the given formatter.

impl<R> From<(usize, R)> for AsyncPeekable<R>

fn from((cap, reader): (usize, R)) -> Self

Converts to this type from the input type.

impl<R> From<R> for AsyncPeekable<R>

fn from(reader: R) -> Self

Converts to this type from the input type.

impl<'__pin, R, B> Unpin for AsyncPeekable<R, B>

where PinnedFieldsOf<__Origin<'__pin, R, B>>: Unpin,