bittersweet

Bittersweet is a library for bit manipulation.

Motivation

Bit-wise operations are often used in low-level programming and it sometimes contains magical bugs. I want to manipulate bits with more

• type-safe
• well-tested
• well-documented
• fast and efficient

Usage

Installation

You can install this library via cargo.

$ cargo add bittersweet

Or you can add this to your Cargo.toml manually.

For no_std environments, disable the default std feature:

[dependencies]
bittersweet = { version = "0.3", default-features = false }

The crate enables std by default. With default-features = false, the core bitline traits and integer implementations remain available without linking the standard library. Re-enable std when you need APIs gated behind that feature.

Minimum Supported Rust Version

bittersweet supports Rust 1.56 and newer. This is the first stable release with Rust 2021 edition support, which matches the crate's edition setting.

Example

use bittersweet::bitline::{Bitline, Bitline8};
fn main() {
    let t = 0b00111000_u8 as Bitline8;
    if t.includes(0b00110000_u8) {
        println!("Yes!");
    }
}

Supported bitline length

Following Bitline traits are implemented for u8, u16, u32, u64, u128. So these operations keep zero-cost abstraction.

• Bitline8 ... 8 bits (u8)
• Bitline16 ... 16 bits (u16)
• Bitline32 ... 32 bits (u32)
• Bitline64 ... 64 bits (u64)
• Bitline128 ... 128 bits (u128)

Documentation

See docs.rs

Release Notes

See CHANGELOG.md for release notes.

Deprecated API lifecycle

is_not_empty and is_not_full were deprecated in 0.2.1. They remain available throughout the 0.3.x line so downstream users can migrate to !is_empty() and !is_full() without an immediate break. Both aliases are scheduled for removal in 0.4.0.

rank(index, bit), rank_range(begin, end, bit), try_rank(index, bit), and try_rank_range(begin, end, bit) are deprecated in 0.3.1. They remain available throughout the 0.3.x line so downstream users can migrate to the explicit _0 / _1 variants without an immediate break. These bool-dispatch aliases are scheduled for removal in 0.4.0.

Bit indexing

Bitline position APIs use MSB-first indexing. Index 0 is the most significant bit, shown at the left edge of a binary literal or bit_repr(). The last valid index is the least significant bit.

Range arguments use the same ordering and follow Rust's half-open convention: [begin, end). For example, 0b10000000_u8.access(0) is true, and Bitline8::by_range(2, 5) returns 0b00111000_u8.

Manipulations

https://docs.rs/bittersweet/latest/bittersweet/bitline/trait.Bitline.html

• as_empty
• as_full
• mask_01
• mask_10
• by_range
• bytes_length
• length
• is_empty
• is_not_empty (deprecated since 0.2.1 — use !is_empty() instead; retained through 0.3.x and scheduled for removal in 0.4.0)
• is_full
• is_not_full (deprecated since 0.2.1 — use !is_full() instead; retained through 0.3.x and scheduled for removal in 0.4.0)
• first_index
• last_index
• radius
• around
• with_around
• first_bit
• last_bit
• first_bits
• last_bits
• filled_first_bit_to_last_bit
• num_bits
• bit_repr
• range
• includes
• overlaps
• remove
• left_rotate
• right_rotate
• bin_to_gray_code
• gray_code_to_bin
• bit_reversal_permutation_to_bin
• bin_to_bit_reversal_permutation
• two_bits_gray_code_rotation
• access
• rank_0
• rank_1
• rank (deprecated since 0.3.1 — use rank_0 / rank_1 instead; retained through 0.3.x and scheduled for removal in 0.4.0)
• rank_range_0
• rank_range_1
• rank_range (deprecated since 0.3.1 — use rank_range_0 / rank_range_1 instead; retained through 0.3.x and scheduled for removal in 0.4.0)
• try_access
• try_rank_0
• try_rank_1
• try_rank (deprecated since 0.3.1 — use try_rank_0 / try_rank_1 instead; retained through 0.3.x and scheduled for removal in 0.4.0)
• try_rank_range_0
• try_rank_range_1
• try_rank_range (deprecated since 0.3.1 — use try_rank_range_0 / try_rank_range_1 instead; retained through 0.3.x and scheduled for removal in 0.4.0)
• select_0
• select_1
• select

Development

This repository uses lefthook to run the same checks as CI locally, so problems surface before they reach CI.

# Install the Git hooks (once; requires lefthook on your PATH)
lefthook install

Once installed, the hooks run automatically:

• pre-commit: cargo fmt --all -- --check and cargo clippy -- -D warnings
• pre-push: the above plus cargo test

CI still runs the full suite (see .github/workflows/); the hooks only bring that feedback earlier on your machine.

License

BSD-3-Clause