Struct PowerOfTwo 

pub struct PowerOfTwo<T> { /* private fields */ }

Proof that a value is a power of two (2^k, k ≥ 0), for an unsigned integer type T.

Representation is the exponent k, not the value — so the consuming operations in PowerOfTwoOps are pure shifts and masks with nothing recomputed per call, and a (future) big-integer backend carries a tiny u32 proof regardless of its width. The field is private, so the representation is an implementation detail. Consequently PowerOfTwo does not deref to T; use get (which reconstructs 1 << k) or exp.

PowerOfTwo<T> is always Copy (it stores only a u32), independent of whether T is.

Examples

use const_num_traits::{PowerOfTwo, PowerOfTwoOps};

let p = PowerOfTwo::<u32>::new(16).unwrap();
assert_eq!(p.exp(), 4);
assert_eq!(p.get(), 16);
assert_eq!(100u32.div_pow2(p), 6); // 100 / 16
assert_eq!(100u32.rem_pow2(p), 4); // 100 % 16
assert!(PowerOfTwo::<u32>::new(6).is_none());

Implementations

impl PowerOfTwo<u8>

pub fn new_ct(value: u8) -> CtOption<PowerOfTwo<u8>>

Available on crate feature ct only.

Constant-time new: a CtOption that is None-masked when value is not a power of two.

impl PowerOfTwo<u16>

pub fn new_ct(value: u16) -> CtOption<PowerOfTwo<u16>>

Available on crate feature ct only.

Constant-time new: a CtOption that is None-masked when value is not a power of two.

impl PowerOfTwo<u32>

pub fn new_ct(value: u32) -> CtOption<PowerOfTwo<u32>>

Available on crate feature ct only.

Constant-time new: a CtOption that is None-masked when value is not a power of two.

impl PowerOfTwo<u64>

pub fn new_ct(value: u64) -> CtOption<PowerOfTwo<u64>>

Available on crate feature ct only.

Constant-time new: a CtOption that is None-masked when value is not a power of two.

impl PowerOfTwo<u128>

pub fn new_ct(value: u128) -> CtOption<PowerOfTwo<u128>>

Available on crate feature ct only.

Constant-time new: a CtOption that is None-masked when value is not a power of two.

impl PowerOfTwo<usize>

pub fn new_ct(value: usize) -> CtOption<PowerOfTwo<usize>>

Available on crate feature ct only.

Constant-time new: a CtOption that is None-masked when value is not a power of two.

impl<T> PowerOfTwo<T>

pub const unsafe fn from_exp_unchecked(exp: u32) -> Self

Constructs the proof directly from an exponent, without checking.

Safety

exp must be < T::BITS (so that 1 << exp is a valid power of two of T). Passing a too-large exponent makes the consuming ops produce nonsense or overflow.

pub const fn exp(self) -> u32

The exponent k such that the proven value is 2^k. Free (no recompute).

impl<T> PowerOfTwo<T>

pub fn new_checked(value: T) -> Option<Self>

where T: IsPowerOfTwo + PrimBits,

Safe constructor for any carrier, not just the primitives: Some iff value is a power of two. Keeps the unsafe crate-internal; the per-primitive new stays the const fast path.

impl PowerOfTwo<u8>

pub const fn new(value: u8) -> Option<Self>

Checked constructor: Some iff value is a power of two.

const fn on stable and nightly (delegates to the inherent is_power_of_two/ilog2, both const since ≤ 1.67).

pub const fn get(self) -> u8

Reconstructs the proven value, 1 << exp.

impl PowerOfTwo<u16>

pub const fn new(value: u16) -> Option<Self>

Checked constructor: Some iff value is a power of two.

const fn on stable and nightly (delegates to the inherent is_power_of_two/ilog2, both const since ≤ 1.67).

pub const fn get(self) -> u16

Reconstructs the proven value, 1 << exp.

impl PowerOfTwo<u32>

pub const fn new(value: u32) -> Option<Self>

Checked constructor: Some iff value is a power of two.

const fn on stable and nightly (delegates to the inherent is_power_of_two/ilog2, both const since ≤ 1.67).

pub const fn get(self) -> u32

Reconstructs the proven value, 1 << exp.

impl PowerOfTwo<u64>

pub const fn new(value: u64) -> Option<Self>

Checked constructor: Some iff value is a power of two.

const fn on stable and nightly (delegates to the inherent is_power_of_two/ilog2, both const since ≤ 1.67).

Examples found in repository

examples/typestates.rs (line 22)

fn power_of_two() {
    let radix = 256u64;
    let p = PowerOfTwo::<u64>::new(radix).expect("256 is 2^8");

    // `x % radix` and `x / radix` without a division instruction
    assert_eq!(700u64.rem_pow2(p), 700 % 256); // & 0xFF
    assert_eq!(700u64.div_pow2(p), 700 / 256); // >> 8

    // align-up to the next multiple, branch-free; checked form for the edge
    assert_eq!(700u64.next_multiple_of_pow2(p), 768);
    assert_eq!(u64::MAX.checked_next_multiple_of_pow2(p), None);

    // built once from a runtime value, spent in a loop with no per-iter recheck
    let mut folded = 0u64;
    for limb in [10u64, 600, 70_000] {
        folded ^= limb.rem_pow2(p);
    }
    assert_eq!(folded, (10 ^ 600 ^ 70_000) & 0xFF);
}

pub const fn get(self) -> u64

Reconstructs the proven value, 1 << exp.

impl PowerOfTwo<u128>

pub const fn new(value: u128) -> Option<Self>

Checked constructor: Some iff value is a power of two.

const fn on stable and nightly (delegates to the inherent is_power_of_two/ilog2, both const since ≤ 1.67).

pub const fn get(self) -> u128

Reconstructs the proven value, 1 << exp.

impl PowerOfTwo<usize>

pub const fn new(value: usize) -> Option<Self>

Checked constructor: Some iff value is a power of two.

const fn on stable and nightly (delegates to the inherent is_power_of_two/ilog2, both const since ≤ 1.67).

pub const fn get(self) -> usize

Reconstructs the proven value, 1 << exp.

Trait Implementations

impl<T> Clone for PowerOfTwo<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Copy for PowerOfTwo<T>

impl TryFrom<u8> for PowerOfTwo<u8>

Checked construction by value; mirrors PowerOfTwo::new. (The generic carrier path stays PowerOfTwo::new_checked.)

type Error = TypestateError

The type returned in the event of a conversion error.

fn try_from(value: u8) -> Result<Self, TypestateError>

Performs the conversion.

impl TryFrom<u16> for PowerOfTwo<u16>

Checked construction by value; mirrors PowerOfTwo::new. (The generic carrier path stays PowerOfTwo::new_checked.)

type Error = TypestateError

The type returned in the event of a conversion error.

fn try_from(value: u16) -> Result<Self, TypestateError>

Performs the conversion.

impl TryFrom<u32> for PowerOfTwo<u32>

Checked construction by value; mirrors PowerOfTwo::new. (The generic carrier path stays PowerOfTwo::new_checked.)

type Error = TypestateError

The type returned in the event of a conversion error.

fn try_from(value: u32) -> Result<Self, TypestateError>

Performs the conversion.

impl TryFrom<u64> for PowerOfTwo<u64>

Checked construction by value; mirrors PowerOfTwo::new. (The generic carrier path stays PowerOfTwo::new_checked.)

type Error = TypestateError

The type returned in the event of a conversion error.

fn try_from(value: u64) -> Result<Self, TypestateError>

Performs the conversion.

impl TryFrom<u128> for PowerOfTwo<u128>

Checked construction by value; mirrors PowerOfTwo::new. (The generic carrier path stays PowerOfTwo::new_checked.)

type Error = TypestateError

The type returned in the event of a conversion error.

fn try_from(value: u128) -> Result<Self, TypestateError>

Performs the conversion.

impl TryFrom<usize> for PowerOfTwo<usize>

Checked construction by value; mirrors PowerOfTwo::new. (The generic carrier path stays PowerOfTwo::new_checked.)

type Error = TypestateError

The type returned in the event of a conversion error.

fn try_from(value: usize) -> Result<Self, TypestateError>

Performs the conversion.