irox_bits/
lib.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2025 IROX Contributors
3//
4
5//! # [Bits & Bobs](https://www.wordnik.com/words/bits%20and%20bobs).  No-std/No-alloc bit/byte manipulation of streams.
6//!
7//! The main traits provided by this crate are [`Bits`] (analogous to [`std::io::Read`]),
8//! and [`MutBits`] (analogous to [`std::io::Write`]).
9//!
10//! Also included are multi-OS wrappers [`SeekRead`] and [`SeekWrite`], and a
11//! more organic UTF-8 encoding/decoding setup for chars.
12//!
13//! This is an Irox foundational crate, it has no external dependencies, is `no-std`/`no-alloc` by
14//! default (but can be augmented by using the `std` and `alloc` features), and many other irox
15//! crates extend and augment the functionality contained herein.  [`irox_structs`] is notable as
16//! it provides a derivable way to encode/decode structs as a sequence of bytes.
17//!
18//! ## Features ##
19//! * `alloc`:
20//!   * Enables the implementation of [`Bits`] and [`MutBits`] on the types from the [`alloc`] crate:
21//!       * [`alloc::string::String`]
22//!       * [`alloc::vec::Vec`]
23//!       * [`alloc::collections::VecDeque`]
24//!   * Enables the following additional methods:
25//!     * [`Bits::read_u8_blob()`]  -> [`Vec<u8>`]
26//!     * [`Bits::read_be_u16_blob()`]/[`Bits::read_le_u16_blob()`] -> [`Vec<u16>`]
27//!     * [`Bits::read_be_u32_blob()`]/[`Bits::read_le_u32_blob()`] -> [`Vec<u32>`]
28//!     * [`Bits::read_be_u64_blob()`]/[`Bits::read_le_u64_blob()`] -> [`Vec<u64>`]
29//!     * [`Bits::read_all_vec()`] -> [`Vec<u8>`]
30//!     * [`Bits::read_exact_vec()`] -> [`Vec<u8>`]
31//!     * [`Bits::read_all_str_lossy()`] -> [`alloc::string::String`]
32//!     * [`Bits::read_str_sized_lossy()`] -> [`alloc::string::String`]
33//!     * [`Bits::read_str_u32_blob()`] -> [`alloc::string::String`]
34//!     * [`Bits::read_until()`] -> [`Vec<u8>`]
35//!     * [`Bits::consume_until()`] -> `()`
36//! * `std`:
37//!     * Enables the implementation of [`Bits`] and [`MutBits`] on the types from the `std` crate:
38//!         * [`std::fs::File`]
39//!     * Also enables the [`SeekRead`] and [`SeekWrite`] traits, which wrap and normalize:
40//!         * [`std::os::windows::fs::FileExt::seek_read`] and [`std::os::windows::fs::FileExt::seek_write`]
41//!         * [`std::os::unix::fs::FileExt:read_at`] and [`std::os::unix::fs::FileExt::write_at`]
42//!
43
44#![forbid(unsafe_code)]
45#![cfg_attr(not(feature = "std"), no_std)]
46#![cfg_attr(docsrs, feature(doc_cfg))]
47
48extern crate alloc;
49
50#[macro_use]
51mod macros {
52    /// Enables feature-specific code.
53    /// Use this macro instead of `cfg(feature = "alloc")` to generate docs properly.
54    macro_rules! cfg_feature_alloc {
55        ($($item:item)*) => {
56            $(
57                #[cfg(any(all(doc, docsrs), feature = "alloc"))]
58                #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
59                $item
60            )*
61        }
62    }
63
64    /// Enables feature-specific code.
65    /// Use this macro instead of `cfg(feature = "std")` to generate docs properly.
66    macro_rules! cfg_feature_std {
67        ($($item:item)*) => {
68            $(
69                #[cfg(any(all(doc, docsrs), feature = "std"))]
70                #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
71                $item
72            )*
73        }
74    }
75}
76
77pub use bits::*;
78pub use bitstream::*;
79pub use buf::*;
80pub use codec::*;
81pub use error::*;
82pub use mutbits::*;
83pub use seek::*;
84pub use stdwrappers::*;
85pub use tee::*;
86
87cfg_feature_alloc! {
88    mod allocimpls;
89    pub use allocimpls::*;
90}
91mod bits;
92mod codec;
93mod error;
94mod mutbits;
95mod seek;
96
97cfg_feature_std! {
98    mod stdimpls;
99}
100mod bitstream;
101mod buf;
102mod stdwrappers;
103mod tee;
104pub mod utf;
irox_bits/lib.rs

irox_bits/
lib.rs
