# `bit_arch`
Fast and efficient architecture-tuned bit operations.
## Features
This crate implements safe wrappers around `x86` instructions.
```rust
let int1_mask = 0b0011_1110; // saves 5 bits of int1
let int2_mask = 0b0000_0111;
let int2_val = 5_u32; // 0b0000_0101
let int1_packed = bit_arch::extract(int1_val, int1_mask);
let int2_packed = bit_arch::extract(int2_val, int2_mask);
// pack two u32s into one u8
let packed8 = (int1_packed | (int2_packed << 5)) as u8;
// do something with that like copy it into a struct field
// deposit only works on u32/u64
let packed32 = packed8 as u32;
// `| 1` recovers the one bit we ignored at the start of int1_mask
let extracted_int1 = bit_arch::deposit(packed32, int1_mask) | 1;
let extracted_int2 = bit_arch::deposit(packed32 >> 5, int2_mask);
assert_eq!(extracted_int1, int1_val);
assert_eq!(extracted_int2, int2_val);
```
It may look like just some bit shifts, but it's much more than that. Mask can be anything at all. Maybe you want to ignore bits 2, 7, and 31 of a `u64` but keep the rest. That's not even the best part though; it's FAST.
Still not fast enough? You need to go a level lower. Below the abstract API of `bit_arch` is `bit_arch::arch`. Everyone knows double the "arch"es means double the performance:
```rust
let mask = 0xAC5;
let initial_val = 0xABC;
let packed = bit_arch::arch::extract_u32(initial_val, mask);
let low_contiguous = bit_arch::arch::extract_bitfield_u32(packed, 2, 7);
let lowest_clear = bit_arch::arch::isolate_lowest_clear_u32(initial_val);
let new_mask = bit_arch::arch::trailing_one_mask_u32(lowest_clear);
let new_val = bit_arch::arch::deposit_u32(low_contiguous, new_mask);
assert_eq!(new_val, 14);
```
There is also one optional feature:
- `dynamic`: Enables dynamic operation dispatch. This should only be used for testing or debugging! Using it in production will severely hurt performance. It also requires `std`.
By default, this crate depends on `x86_intr`. This will be removed when `core::arch::x86_64` stabilizes `_mm_popcnt_u32`/`_mm_popcnt_u64`.
## Performance
Assembly output has been carefully analyzed and is guaranteed to include the desired instructions. These instructions are listed below. Regardless, compiling with `target-cpu=native` has proven to greatly improved performance. Dropping from ~22.839 ns to ~521.33 ps for `extract`/`deposit` (or `pext`/`pdep`) roundtrips. That's a 44x improvement!
## Architecture-Specific Details
Particularly operations in BMI 1/2, TBM, and ABM extensions. It implements most operations through a safe API. All supported operations are listed below:
| `_andn_*` | `bmi1` | `inverted_and_*` |
| `_bextr_*` | `bmi1`, `tbm` | `extract_bitfield_*` |
| `_blci_*` | `tbm` | `isolate_lowest_clear_*` |
| `_blcic_*` | `tbm` | `set_lowest_clear_*` |
| `_blcs_*` | `tbm` | `set_lowest_zero_*` |
| `_blsfill_*` | `tbm` | `from_lowest_set_*` |
| `_blsi_*` | `bmi1` | `isolate_lowest_set_*` |
| `_blsic_*` | `tbm` | `complement_lowest_set_*` |
| `_blsmsk_*` | `bmi1` | `through_lowest_set_*` |
| `_blsr_*` | `bmi1` | `clear_lowest_set_*` |
| `_bzhi_*` | `bmi2` | `zero_upper_*` |
| `_lzcnt_*` | `abm` | `leading_zeros_*` |
| `_pdep_*` | `bmi2` | `deposit_*` |
| `_pext_*` | `bmi2` | `extract_*` |
| `_popcnt*` | `abm` | `count_ones_*`* |
| `_t1mskc_*` | `tbm` | `trailing_one_mask_*` |
| `_tzcnt_*` | `bmi1` | `trailing_zeros_*` |
| `_tzmskc_*` | `tbm` | `trailing_zero_mask_*` |
[*] `count_ones` only uses the corresponding `_popcnt*` intrinsics if the `popcnt_uint` feature is enabled.
All functions defined in `bit_arch::arch` are completely safe and have optimized fallback paths. Despite this, there is a preferred higher level API that offers the same level of performance, but is generic over the type `u32` or `u64`.
There are also more intrinsics listed below, but these don't have a high-level API in the crate. They may never get a abstraction either. They will recieve updates and will be maintained.
| `_bextr2_*` | `bmi1`, `tbm` | `extract_bitfield_control_*` |
| `_bswap*` | None | `swap_bytes_*` |
| `bittest*` | None | `bit_test_*` |
| `bittestandset*` | None | `bit_test_set_*` |
| `bittestandreset*` | None | `bit_test_reset_*` |
| `bittestandcomplement*` | None | `bit_test_complement_*` |
`trailing_zeros` also has an intrinsic only accessible from `arch`, `trailing_zeros_u16`.