# `octs`
[](https://crates.io/crates/octs)
[](https://docs.rs/octs)
Finally, a good byte manipulation library.
This crate builds on top of the types defined by [`bytes`] by replacing its panicking `get` and
`put` functions with fallible, non-panicking `read` and `write` functions via [`octs::Read`] and
[`octs::Write`].
## Features
* **Based on [`bytes`]** - which provides useful types for byte manipulation, and allows cheaply
cloning byte allocations via reference counting. Great for writing zero-copy networking code.
* **Panicking functions were a mistake** - in networking, you can't trust your inputs. So why should
it ever be possible to panic on malformed input?? All functions in `octs` which can fail return a
[`Result`].
* **Your types are first-class citizens** - instead of `get_u16`, `put_f32`, etc., just use one
[`read`] and [`write`] function for all types. This means you can implement [`Decode`] and be able
to [`read`] it from any buffer, and likewise for [`Encode`] and [`write`].
* **Dedicated varints** - one of the staples of networking primitives is implemented here, without
needing any extensions. Just `read` or `write` a [`VarInt`] as you would any other value.
* **Zero unsafe** - I'm not smart enough to write unsafe code.
* `#![no_std]` - just like [`bytes`], but it still requires `alloc`.
## Examples
### Writing
```rust
use octs::{Read, Write, VarInt};
fn write_packet(
mut buf: octs::BytesMut,
// ^^^^^^^^^^^^^^
// | re-exports the core `bytes` types
packet_id: u16,
timestamp: u64,
payload: &[u8],
) -> Result<(), octs::BufTooShort> {
// ^^^^^^^^^^^^^^^^^
// | the main error type
buf.write(packet_id)?;
// ^^^^^
// | one `write` function for all your types
buf.write(timestamp)?;
// +---------------^
// | just use ? for errors
// | no panics
buf.write(VarInt(payload.len()))?;
// ^^^^^^^
// | inbuilt support for varints
// | using the Protocol Buffers spec
buf.write_from(payload)?;
// ^^^^^^^^^^
// | copy from an existing buffer
Ok(())
}
```
### Reading
```rust
use core::num::NonZeroU8;
use octs::{Bytes, BufError, Decode, Read, BufTooShortOr, VarInt};
#[derive(Debug)]
struct Fragment {
num_frags: NonZeroU8,
payload: Bytes,
}
#[derive(Debug)]
enum FragmentError {
InvalidNumFrags,
PayloadTooLarge,
}
impl Decode for Fragment {
// ^^^^^^
type Error = FragmentError;
fn decode(mut buf: impl Read) -> Result<Self, BufTooShortOr<Self::Error>> {
let num_frags = buf
.read::<NonZeroU8>()
.map_err(|e| e.map_or(|_| FragmentError::InvalidNumFrags))?;
// +--------------^^^^^^^
// | map the `InvalidValue` error of reading
// | a `NonZeroU8` to your own error value
let VarInt(payload_len) = buf
.read::<VarInt<usize>>()
.map_err(|e| e.map_or(|_| FragmentError::PayloadTooLarge))?;
let payload = buf.read_next(payload_len)?;
// +-------------^^^^^^^^^^
// | read the next `payload_len` bytes directly into `Bytes`
// | if `buf` is also a `Bytes`, this is zero-copy!
Ok(Self {
num_frags,
payload
})
}
}
```
## Inspirations
* [`bytes`] - core byte manipulation primitives, such as the possibly-non-contiguous [`bytes::Buf`]
trait, and the cheaply-cloneable [`bytes::Bytes`] type.
* [`octets`] - general API style, and having varints be a core part of the API
* [`safer-bytes`] - making a good version of the [`bytes`] API
* [`integer-encoding`] - implementations of varint encode/decode
[`octs::Read`]: Read
[`octs::Write`]: Write
[`read`]: Read::read
[`write`]: Write::write
[`bytes`]: https://docs.rs/bytes
[`octets`]: https://docs.rs/octets
[`integer-encoding`]: https://docs.rs/integer-encoding
[`safer-bytes`]: https://docs.rs/safer-bytes