Portable Bitwise Manipulation Intrinsics

0b0000_0010_1001_1010

The intrinsics are named after their CPU instruction and organized in modules named after their architecture/instruction set: bitintr::{arch}::{instruction_set}::{intrinsic_name}.

They are implemented for all integer types except u128/i128. Whether a fallback software implementation is used depends on the integer types involved and the instruction sets supported by the target.

The following instruction sets are implemented:

• x86 (bitintr::x86):

  • ABM: Advanced Bit Manipulation instructions (bitintr::x86::abm).
  • TBM: Trailing Bit Manipulation instructions (bitintr::x86::tbm).
  • BMI: Bit Manipulation Instruction Set 1.0 (bitintr::x86::bmi).
  • BMI2: Bit Manipulation Instruction Set 2.0 (bitintr::x86::bmi2).

• ARM (bitintr::arm):

  • ARMv5: bitintr::arm::v5.
  • ARMv6: bitintr::arm::v6.
  • ARMv7: bitintr::arm::v7.
  • ARMv8: bitintr::arm::v8.

Note: This library is low-level by purpose. For a portable higher-level bitwise manipulation algorithms library you might want to check out the [bitwise][bitwise_link] crate.

Example

extern crate bitintr;
use bitintr::x86::bmi2::*;

fn main() {
    // Intrinsics are provided as trait methods:
    let method_call = 1.pdep(0);
    // And as free functions:
    let free_call = pdep(1, 0);
    assert_eq!(method_call, free_call);
}

Supported compilers

The minimum required rustc version is >= 1.4.0.

When compiled with a rust stable compiler the intrinsics are implemented using the software fallback. In release builds LLVM often generates the corresponding CPU instruction.

When compiled with a rust nightly compiler the following unstable features are used to generate the corresponding CPU instruction in all cases:

• cfg_target_feature for target-dependent behavior,
• platform_intrinsics for using the bitwise manipulation compiler intrinsics, and
• i128_type support for efficient 64-bit multiplication (using u128).

License

Licensed under the MIT license.

Contribution

Yes please! Just note that all contributions shall be licensed as above without any additional terms or conditions.