Crate irox_bits

Bits & Bobs. No-std/No-alloc bit/byte manipulation of streams.

The main traits provided by this crate are Bits (analogous to std::io::Read), and MutBits (analogous to std::io::Write).

Also included are multi-OS wrappers SeekRead and SeekWrite, and a more organic UTF-8 encoding/decoding setup for chars.

This is an Irox foundational crate, it has no external dependencies, is no-std/no-alloc by default (but can be augmented by using the std and alloc features), and many other irox crates extend and augment the functionality contained herein. [irox_structs] is notable as it provides a derivable way to encode/decode structs as a sequence of bytes.

Features

• alloc:
  • Enables the implementation of Bits and MutBits on the types from the alloc crate:
    • alloc::string::String
    • alloc::vec::Vec
    • alloc::collections::VecDeque
  • Enables the following additional methods:
    • Bits::read_u8_blob() -> Vec<u8>
    • Bits::read_be_u16_blob()/Bits::read_le_u16_blob() -> Vec<u16>
    • Bits::read_be_u32_blob()/Bits::read_le_u32_blob() -> Vec<u32>
    • Bits::read_be_u64_blob()/Bits::read_le_u64_blob() -> Vec<u64>
    • Bits::read_all_vec() -> Vec<u8>
    • Bits::read_exact_vec() -> Vec<u8>
    • Bits::read_all_str_lossy() -> alloc::string::String
    • Bits::read_str_sized_lossy() -> alloc::string::String
    • Bits::read_str_u32_blob() -> alloc::string::String
    • Bits::read_until() -> Vec<u8>
    • Bits::consume_until() -> ()
• std:
  • Enables the implementation of Bits and MutBits on the types from the std crate:
    • std::fs::File
  • Also enables the SeekRead and SeekWrite traits, which wrap and normalize:
    • [std::os::windows::fs::FileExt::seek_read] and [std::os::windows::fs::FileExt::seek_write]
    • [std::os::unix::fs::FileExt:read_at] and std::os::unix::fs::FileExt::write_at

Modules

utf

UTF-8 Encoding & Decoding

Structs

BitStreamDecoder

BitStreamEncoder

BitsArray

This struct wraps a provided borrowed static array in a MutBits impl. Operates like a slice, walking through the array filling it up.

BitsError

Error returned from the various Bits methods.

FormatBits

Wraps a borrowed MutBits, providing an implementation of core::fmt::Write to permit the use of the core::write! macro with a target of &mutMutBits

MutBitsArray

This struct wraps a provided borrowed static array in a MutBits impl. Operates like a slice, walking through the array filling it up.

SharedCountingBitsalloc

A struct to count the number of bytes moving through it.

SharedROCounteralloc

A Read-Only counter that can be shared between threads. The owner of the underlying counter is free to update the value, but users of this object alone may not.

Tee

Simple output stream splitter. Writes the output value to both streams simultaneously.

Enums

BitsErrorKind

Enum originally modelled after std::io::ErrorKind, used to indicate the type of the error encountered.

BitsWrapper

Wraps a borrowed value and provides implementations of [Bits] and [MutBits] where applicable.

ByteOrder

SeekFrom

Enum to indicate how to move a read/write pointer.

Traits

Bits

Read methods for the primitive types

BufBits

Buffered bits - semantically equivalent to BufRead

FromBEBytes

Converts to the value from a constant number of bytes

FromLEBytes

Converts to the value from a constant number of bytes

MutBits

Write methods for the primitive types

ReadFromBEBits

ReadFromLEBits

Seek

Trait to move the current read/write position of a stream.

SeekRead

Trait to permit an atomic Seek+Read operation

SeekWrite

Trait to permit an atomic Seek+Write operation

ToBEBytes

Converts the value into a constant number of bytes

ToLEBytes

Converts the value into a constant number of bytes

WriteToBEBits

Writes ‘self’ to the provided MutBits impl in big endian order.

WriteToLEBits

Writes ‘self’ to the provided MutBits impl in little endian order.

Functions

array_concat_1

Splits the input into two equal sized arrays.

array_concat_2

Splits the input into two equal sized arrays.

array_concat_4

Splits the input into two equal sized arrays.

array_concat_8

Splits the input into two equal sized arrays.

array_concat_16

Splits the input into two equal sized arrays.

array_split_1

Splits the input into two equal sized arrays.

array_split_2

Splits the input into two equal sized arrays.

array_split_4

Splits the input into two equal sized arrays.

array_split_8

Splits the input into two equal sized arrays.

array_split_16

Splits the input into two equal sized arrays.

read_be_u32

Calls Bits::read_be_u32(). Provided for type-elusion purposes.

read_be_u64

Calls Bits::read_be_u64(). Provided for type-elusion purposes.

read_f32

Calls Bits::read_f32(). Provided for type-elusion purposes.

read_f64

Calls Bits::read_f64(). Provided for type-elusion purposes.

u16_to_u32

compile time u16x2 to u32 conversion

u16_to_u64

compile time u16 to u64 conversion

u16_to_u128

compile time u16 to u128 conversion

u32_to_u16

compile time u32 to u16 conversion

u32_to_u64

compile time u32x2 to u64 conversion

u32_to_u128

compile time u32x4 to u128 conversion

u64_to_u16

compile time u64 to u16 conversion

u64_to_u32

compile time u64 to u32 conversion

u64_to_u128

compile time u64x2 to u128 conversion

u128_to_u16

compile-time u128 to u16 conversion

u128_to_u32

compile time u128 to u32 conversion

u128_to_u64

compile time u128 to u64 conversion

Type Aliases

Error

Type alias to BitsError

ErrorKind

Type alias to BitsErrorKind