Struct tokio_util::io::StreamReader
source · pub struct StreamReader<S, B> { /* private fields */ }
Expand description
Convert a Stream
of byte chunks into an AsyncRead
.
This type performs the inverse operation of ReaderStream
.
This type also implements the AsyncBufRead
trait, so you can use it
to read a Stream
of byte chunks line-by-line. See the examples below.
§Example
use bytes::Bytes;
use tokio::io::{AsyncReadExt, Result};
use tokio_util::io::StreamReader;
// Create a stream from an iterator.
let stream = tokio_stream::iter(vec![
Result::Ok(Bytes::from_static(&[0, 1, 2, 3])),
Result::Ok(Bytes::from_static(&[4, 5, 6, 7])),
Result::Ok(Bytes::from_static(&[8, 9, 10, 11])),
]);
// Convert it to an AsyncRead.
let mut read = StreamReader::new(stream);
// Read five bytes from the stream.
let mut buf = [0; 5];
read.read_exact(&mut buf).await?;
assert_eq!(buf, [0, 1, 2, 3, 4]);
// Read the rest of the current chunk.
assert_eq!(read.read(&mut buf).await?, 3);
assert_eq!(&buf[..3], [5, 6, 7]);
// Read the next chunk.
assert_eq!(read.read(&mut buf).await?, 4);
assert_eq!(&buf[..4], [8, 9, 10, 11]);
// We have now reached the end.
assert_eq!(read.read(&mut buf).await?, 0);
If the stream produces errors which are not std::io::Error
,
the errors can be converted using StreamExt
to map each
element.
use bytes::Bytes;
use tokio::io::AsyncReadExt;
use tokio_util::io::StreamReader;
use tokio_stream::StreamExt;
// Create a stream from an iterator, including an error.
let stream = tokio_stream::iter(vec![
Result::Ok(Bytes::from_static(&[0, 1, 2, 3])),
Result::Ok(Bytes::from_static(&[4, 5, 6, 7])),
Result::Err("Something bad happened!")
]);
// Use StreamExt to map the stream and error to a std::io::Error
let stream = stream.map(|result| result.map_err(|err| {
std::io::Error::new(std::io::ErrorKind::Other, err)
}));
// Convert it to an AsyncRead.
let mut read = StreamReader::new(stream);
// Read five bytes from the stream.
let mut buf = [0; 5];
read.read_exact(&mut buf).await?;
assert_eq!(buf, [0, 1, 2, 3, 4]);
// Read the rest of the current chunk.
assert_eq!(read.read(&mut buf).await?, 3);
assert_eq!(&buf[..3], [5, 6, 7]);
// Reading the next chunk will produce an error
let error = read.read(&mut buf).await.unwrap_err();
assert_eq!(error.kind(), std::io::ErrorKind::Other);
assert_eq!(error.into_inner().unwrap().to_string(), "Something bad happened!");
// We have now reached the end.
assert_eq!(read.read(&mut buf).await?, 0);
Using the AsyncBufRead
impl, you can read a Stream
of byte chunks
line-by-line. Note that you will usually also need to convert the error
type when doing this. See the second example for an explanation of how
to do this.
use tokio::io::{Result, AsyncBufReadExt};
use tokio_util::io::StreamReader;
// Create a stream of byte chunks.
let stream = tokio_stream::iter(vec![
Result::Ok(b"The first line.\n".as_slice()),
Result::Ok(b"The second line.".as_slice()),
Result::Ok(b"\nThe third".as_slice()),
Result::Ok(b" line.\nThe fourth line.\nThe fifth line.\n".as_slice()),
]);
// Convert it to an AsyncRead.
let mut read = StreamReader::new(stream);
// Loop through the lines from the `StreamReader`.
let mut line = String::new();
let mut lines = Vec::new();
loop {
line.clear();
let len = read.read_line(&mut line).await?;
if len == 0 { break; }
lines.push(line.clone());
}
// Verify that we got the lines we expected.
assert_eq!(
lines,
vec![
"The first line.\n",
"The second line.\n",
"The third line.\n",
"The fourth line.\n",
"The fifth line.\n",
]
);
Implementations§
source§impl<S, B, E> StreamReader<S, B>
impl<S, B, E> StreamReader<S, B>
sourcepub fn into_inner_with_chunk(self) -> (S, Option<B>)
pub fn into_inner_with_chunk(self) -> (S, Option<B>)
Consumes this StreamReader
, returning a Tuple consisting
of the underlying stream and an Option of the internal buffer,
which is Some in case the buffer contains elements.
source§impl<S, B> StreamReader<S, B>
impl<S, B> StreamReader<S, B>
sourcepub fn get_ref(&self) -> &S
pub fn get_ref(&self) -> &S
Gets a reference to the underlying stream.
It is inadvisable to directly read from the underlying stream.
sourcepub fn get_mut(&mut self) -> &mut S
pub fn get_mut(&mut self) -> &mut S
Gets a mutable reference to the underlying stream.
It is inadvisable to directly read from the underlying stream.
sourcepub fn get_pin_mut(self: Pin<&mut Self>) -> Pin<&mut S>
pub fn get_pin_mut(self: Pin<&mut Self>) -> Pin<&mut S>
Gets a pinned mutable reference to the underlying stream.
It is inadvisable to directly read from the underlying stream.
sourcepub fn into_inner(self) -> S
pub fn into_inner(self) -> S
Consumes this BufWriter
, returning the underlying stream.
Note that any leftover data in the internal buffer is lost.
If you additionally want access to the internal buffer use
into_inner_with_chunk
.
Trait Implementations§
source§impl<S, B, E> AsyncBufRead for StreamReader<S, B>
impl<S, B, E> AsyncBufRead for StreamReader<S, B>
source§impl<S, B, E> AsyncRead for StreamReader<S, B>
impl<S, B, E> AsyncRead for StreamReader<S, B>
source§impl<S: Sink<T, Error = E>, B, E, T> Sink<T> for StreamReader<S, B>
impl<S: Sink<T, Error = E>, B, E, T> Sink<T> for StreamReader<S, B>
source§fn poll_ready(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
) -> Poll<Result<(), Self::Error>>
fn poll_ready( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Self::Error>>
Sink
to receive a value. Read moresource§fn start_send(self: Pin<&mut Self>, item: T) -> Result<(), Self::Error>
fn start_send(self: Pin<&mut Self>, item: T) -> Result<(), Self::Error>
poll_ready
which returned Poll::Ready(Ok(()))
. Read moreimpl<S: Unpin, B> Unpin for StreamReader<S, B>
Auto Trait Implementations§
impl<S, B> Freeze for StreamReader<S, B>
impl<S, B> RefUnwindSafe for StreamReader<S, B>where
S: RefUnwindSafe,
B: RefUnwindSafe,
impl<S, B> Send for StreamReader<S, B>
impl<S, B> Sync for StreamReader<S, B>
impl<S, B> UnwindSafe for StreamReader<S, B>where
S: UnwindSafe,
B: UnwindSafe,
Blanket Implementations§
source§impl<R> AsyncBufReadExt for Rwhere
R: AsyncBufRead + ?Sized,
impl<R> AsyncBufReadExt for Rwhere
R: AsyncBufRead + ?Sized,
source§fn read_until<'a>(
&'a mut self,
byte: u8,
buf: &'a mut Vec<u8>,
) -> ReadUntil<'a, Self>where
Self: Unpin,
fn read_until<'a>(
&'a mut self,
byte: u8,
buf: &'a mut Vec<u8>,
) -> ReadUntil<'a, Self>where
Self: Unpin,
source§fn read_line<'a>(&'a mut self, buf: &'a mut String) -> ReadLine<'a, Self>where
Self: Unpin,
fn read_line<'a>(&'a mut self, buf: &'a mut String) -> ReadLine<'a, Self>where
Self: Unpin,
source§fn split(self, byte: u8) -> Split<Self>
fn split(self, byte: u8) -> Split<Self>
byte
. Read moresource§fn fill_buf(&mut self) -> FillBuf<'_, Self>where
Self: Unpin,
fn fill_buf(&mut self) -> FillBuf<'_, Self>where
Self: Unpin,
source§impl<R> AsyncReadExt for R
impl<R> AsyncReadExt for R
source§fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self>where
Self: Unpin,
fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self>where
Self: Unpin,
source§fn read_buf<'a, B>(&'a mut self, buf: &'a mut B) -> ReadBuf<'a, Self, B>
fn read_buf<'a, B>(&'a mut self, buf: &'a mut B) -> ReadBuf<'a, Self, B>
source§fn read_exact<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, Self>where
Self: Unpin,
fn read_exact<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, Self>where
Self: Unpin,
buf
. Read moresource§fn read_u8(&mut self) -> ReadU8<&mut Self>where
Self: Unpin,
fn read_u8(&mut self) -> ReadU8<&mut Self>where
Self: Unpin,
source§fn read_i8(&mut self) -> ReadI8<&mut Self>where
Self: Unpin,
fn read_i8(&mut self) -> ReadI8<&mut Self>where
Self: Unpin,
source§fn read_u16(&mut self) -> ReadU16<&mut Self>where
Self: Unpin,
fn read_u16(&mut self) -> ReadU16<&mut Self>where
Self: Unpin,
source§fn read_i16(&mut self) -> ReadI16<&mut Self>where
Self: Unpin,
fn read_i16(&mut self) -> ReadI16<&mut Self>where
Self: Unpin,
source§fn read_u32(&mut self) -> ReadU32<&mut Self>where
Self: Unpin,
fn read_u32(&mut self) -> ReadU32<&mut Self>where
Self: Unpin,
source§fn read_i32(&mut self) -> ReadI32<&mut Self>where
Self: Unpin,
fn read_i32(&mut self) -> ReadI32<&mut Self>where
Self: Unpin,
source§fn read_u64(&mut self) -> ReadU64<&mut Self>where
Self: Unpin,
fn read_u64(&mut self) -> ReadU64<&mut Self>where
Self: Unpin,
source§fn read_i64(&mut self) -> ReadI64<&mut Self>where
Self: Unpin,
fn read_i64(&mut self) -> ReadI64<&mut Self>where
Self: Unpin,
source§fn read_u128(&mut self) -> ReadU128<&mut Self>where
Self: Unpin,
fn read_u128(&mut self) -> ReadU128<&mut Self>where
Self: Unpin,
source§fn read_i128(&mut self) -> ReadI128<&mut Self>where
Self: Unpin,
fn read_i128(&mut self) -> ReadI128<&mut Self>where
Self: Unpin,
source§fn read_f32(&mut self) -> ReadF32<&mut Self>where
Self: Unpin,
fn read_f32(&mut self) -> ReadF32<&mut Self>where
Self: Unpin,
source§fn read_f64(&mut self) -> ReadF64<&mut Self>where
Self: Unpin,
fn read_f64(&mut self) -> ReadF64<&mut Self>where
Self: Unpin,
source§fn read_u16_le(&mut self) -> ReadU16Le<&mut Self>where
Self: Unpin,
fn read_u16_le(&mut self) -> ReadU16Le<&mut Self>where
Self: Unpin,
source§fn read_i16_le(&mut self) -> ReadI16Le<&mut Self>where
Self: Unpin,
fn read_i16_le(&mut self) -> ReadI16Le<&mut Self>where
Self: Unpin,
source§fn read_u32_le(&mut self) -> ReadU32Le<&mut Self>where
Self: Unpin,
fn read_u32_le(&mut self) -> ReadU32Le<&mut Self>where
Self: Unpin,
source§fn read_i32_le(&mut self) -> ReadI32Le<&mut Self>where
Self: Unpin,
fn read_i32_le(&mut self) -> ReadI32Le<&mut Self>where
Self: Unpin,
source§fn read_u64_le(&mut self) -> ReadU64Le<&mut Self>where
Self: Unpin,
fn read_u64_le(&mut self) -> ReadU64Le<&mut Self>where
Self: Unpin,
source§fn read_i64_le(&mut self) -> ReadI64Le<&mut Self>where
Self: Unpin,
fn read_i64_le(&mut self) -> ReadI64Le<&mut Self>where
Self: Unpin,
source§fn read_u128_le(&mut self) -> ReadU128Le<&mut Self>where
Self: Unpin,
fn read_u128_le(&mut self) -> ReadU128Le<&mut Self>where
Self: Unpin,
source§fn read_i128_le(&mut self) -> ReadI128Le<&mut Self>where
Self: Unpin,
fn read_i128_le(&mut self) -> ReadI128Le<&mut Self>where
Self: Unpin,
source§fn read_f32_le(&mut self) -> ReadF32Le<&mut Self>where
Self: Unpin,
fn read_f32_le(&mut self) -> ReadF32Le<&mut Self>where
Self: Unpin,
source§fn read_f64_le(&mut self) -> ReadF64Le<&mut Self>where
Self: Unpin,
fn read_f64_le(&mut self) -> ReadF64Le<&mut Self>where
Self: Unpin,
source§fn read_to_end<'a>(&'a mut self, buf: &'a mut Vec<u8>) -> ReadToEnd<'a, Self>where
Self: Unpin,
fn read_to_end<'a>(&'a mut self, buf: &'a mut Vec<u8>) -> ReadToEnd<'a, Self>where
Self: Unpin,
buf
. Read more