qubit-io 0.6.0

# Qubit IO User Guide

Use `qubit-io` when code needs reusable `std::io` helpers without choosing a
binary or text encoding format. The crate stays at the generic I/O layer.

## Capability Map

| Area | API | Use when |
| --- | --- | --- |
| Composition traits | `ReadSeek`, `ReadWrite`, `ReadWriteSeek`, `BufReadSeek`, `WriteSeek` | an API needs a trait object for combined I/O capabilities |
| Read helpers | `ReadExt` | exact-or-EOF reads, bounded reads, and copy helpers |
| Buffered helpers | `BufReadExt` | bounded delimiter and line reads |
| Seek helpers | `SeekExt`, `ReadSeekExt`, `WriteSeekExt` | stream-size queries and position-preserving reads or writes |
| Stream utilities | `Streams` | namespaced copy and content comparison |
| Wrappers | `CountingReader`, `LimitReader`, `TeeReader`, checksum wrappers, `PositionGuard` | small behavior adapters around existing streams |

## Installation

```toml
[dependencies]
qubit-io = "0.6"
```

## Extension Traits

Import the trait whose methods you want to call.

```rust
use std::io::Cursor;

use qubit_io::ReadExt;

let mut input = Cursor::new(b"abc".to_vec());
let mut bytes = [0_u8; 8];

let read = input.read_exact_or_eof(&mut bytes)?;

assert_eq!(3, read);
assert_eq!(b"abc", &bytes[..read]);
# Ok::<(), std::io::Error>(())
```

`ReadExt` includes bounded helpers such as `read_to_end_limited` and
`read_exact_vec_limited`. These are useful at protocol and file-format
boundaries where unbounded allocation would be a bug.

`BufReadExt` provides bounded delimiter operations:

```rust
use std::io::Cursor;

use qubit_io::BufReadExt;

let mut input = Cursor::new(b"first\nsecond".to_vec());
let line = input.read_line_limited(16)?;

assert_eq!("first\n", line);
# Ok::<(), std::io::Error>(())
```

## Position-Preserving I/O

`ReadSeekExt` and `WriteSeekExt` are for APIs that need temporary random access
without changing the caller-visible position.

```rust
use std::io::Cursor;

use qubit_io::ReadSeekExt;

let mut input = Cursor::new(b"abcdef".to_vec());
let mut header = [0_u8; 2];

input.read_exact_or_eof_at(2, &mut header)?;

assert_eq!(b"cd", &header);
assert_eq!(0, input.position());
# Ok::<(), std::io::Error>(())
```

## Streams

`Streams` is an uninstantiable namespace for operations involving one or more
streams.

```rust
use std::io::Cursor;

use qubit_io::Streams;

let mut input = Cursor::new(b"abcdef".to_vec());
let mut output = Vec::new();

let copied = Streams::copy_to_end_limited(&mut input, &mut output, 8)?;

assert_eq!(6, copied);
assert_eq!(b"abcdef", output.as_slice());
# Ok::<(), std::io::Error>(())
```

Use `Streams::content_eq` or `Streams::compare_content` when comparing remaining
stream contents from their current positions.

## Wrappers

Wrappers compose small stream behaviors without owning the underlying resource
type.

```rust
use std::io::Read;

use qubit_io::CountingReader;

let inner = std::io::Cursor::new(b"abc".to_vec());
let mut reader = CountingReader::new(inner);
let mut bytes = [0_u8; 2];

reader.read_exact(&mut bytes)?;

assert_eq!(2, reader.count());
# Ok::<(), std::io::Error>(())
```

Common wrappers include:

| Wrapper | Purpose |
| --- | --- |
| `CountingReader`, `CountingWriter` | count successfully read or written bytes |
| `LimitReader`, `LimitWriter` | cap how many bytes can pass through |
| `TeeReader`, `TeeWriter` | copy successful reads or writes to a branch sink |
| `ChecksumReader`, `ChecksumWriter` | hash successful bytes through a caller-supplied hasher |
| `PositionGuard` | restore a seek position unless dismissed |

## What This Crate Does Not Contain

`qubit-io` deliberately does not contain binary scalar codecs, LEB128, ZigZag,
or text charset adapters. Use the sibling crates for those layers:

- `qubit-codec-binary` for buffer-level binary codecs;
- `qubit-io-binary` for binary stream extension traits and wrappers;
- `qubit-codec-text` for text codecs;
- `qubit-io-text` for text stream adapters.