Struct TeeReader 

pub struct TeeReader<R, W> { /* private fields */ }

Reader wrapper that mirrors read bytes into a branch writer.

TeeReader forwards reads to the source reader and writes every successfully read byte into the branch writer while the stream is consumed. If the branch writer fails, the source bytes have already been read from the inner reader and the branch error is returned.

Seeking a TeeReader seeks only the source reader. It does not seek or otherwise modify the branch writer; bytes mirrored after the seek are simply appended or written according to the branch writer’s own state.

TeeReader intentionally does not implement std::io::BufRead. Mirroring from fill_buf would copy bytes before the caller commits to consuming them, while mirroring from consume could not report branch write failures because BufRead::consume has no error return.

If buffered access is needed, wrap this reader outside the tee layer, for example BufReader<TeeReader<R, W>>. In that composition bytes are mirrored when the outer BufReader refills its internal buffer, which may be earlier than the application later consuming those bytes from fill_buf.

Failure and retry semantics

A branch error does not restore bytes already consumed from the source. Callers should therefore treat a branch write error as terminal unless they can reposition or otherwise recover the source. An outer buffering layer may discard a failed refill even though the source has already advanced:

source before refill: "abcdef"
refill reads "abc":   source advances to "def", branch returns an error
retry:                reading resumes at "def"; "abc" may be unavailable

After a branch error, the source and branch may be out of sync. This wrapper does not retain the consumed bytes or provide rollback.

Examples

use std::io::{
    Cursor,
    Read,
};

use qubit_io::TeeReader;

let source = Cursor::new(b"abc".to_vec());
let branch = Vec::new();
let mut reader = TeeReader::new(source, branch);

let mut data = Vec::new();
reader.read_to_end(&mut data)?;
let (_source, branch) = reader.into_inner();

assert_eq!(b"abc", data.as_slice());
assert_eq!(b"abc", branch.as_slice());

Implementations

impl<R, W> TeeReader<R, W>

pub fn new(reader: R, branch: W) -> Self

Creates a tee reader.

Parameters

• reader: Source reader.
• branch: Writer that receives the bytes successfully read.

Returns

A new tee reader.

pub fn with_sync_branch_seek(reader: R, branch: W) -> SyncSeekTeeReader<R, W>

Creates a tee reader that synchronizes branch seeks with source seeks.

The returned wrapper mirrors read bytes like TeeReader, but its Seek implementation also seeks the branch writer to the source reader’s resulting absolute position. If the branch seek fails, the source reader may already have moved.

Parameters

• reader: Source reader.
• branch: Writer that receives bytes successfully read and is sought to the same absolute position as the source reader.

Returns

A sync-seek tee reader.

pub fn inner(&self) -> &R

Returns an immutable reference to the source reader.

Returns

The source reader reference.

pub fn inner_mut(&mut self) -> &mut R

Returns a mutable reference to the source reader.

Returns

The source reader reference.

pub fn branch(&self) -> &W

Returns an immutable reference to the branch writer.

Returns

The branch writer reference.

pub fn branch_mut(&mut self) -> &mut W

Returns a mutable reference to the branch writer.

Returns

The branch writer reference.

pub fn into_inner(self) -> (R, W)

Consumes this wrapper and returns the source reader and branch writer.

Returns

A tuple containing the source reader and branch writer.

Trait Implementations

impl<R, W> Read for TeeReader<R, W>

where R: Read, W: Write,

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

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

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

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

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

Reads all bytes until EOF in this source, placing them into buf.

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

Reads all bytes until EOF in this source, appending them to buf.

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

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_, u8>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

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

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

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

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

fn read_array<const N: usize>(&mut self) -> Result<[u8; N], Error>

where Self: Sized,

🔬This is a nightly-only experimental API. (read_array)

Read and return a fixed array of bytes from this source.

fn read_le<T>(&mut self) -> Result<T, Error>

where T: FromEndianBytes, Self: Sized,

🔬This is a nightly-only experimental API. (read_le)

Read and return a type (e.g. an integer) in little-endian order.

fn read_be<T>(&mut self) -> Result<T, Error>

where T: FromEndianBytes, Self: Sized,

🔬This is a nightly-only experimental API. (read_le)

Read and return a type (e.g. an integer) in big-endian order.

impl<R, W> Seek for TeeReader<R, W>

where R: Seek,

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

Seeks the source reader without touching the branch writer.

Parameters

• position: Target position for the source reader.

Returns

The new source reader position.

Errors

Returns the seek error reported by the source reader.

fn rewind(&mut self) -> Result<(), Error>

Rewind to the beginning of a stream.

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

🔬This is a nightly-only experimental API. (seek_stream_len)

Returns the length of this stream (in bytes).

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

Returns the current seek position from the start of the stream.

fn seek_relative(&mut self, offset: i64) -> Result<(), Error>

Seeks relative to the current position.