# [−][src]Crate pow2

Represents a non-negative power of 2, by storing its exponent.

The `Pow2` type is limited in range to `1 .. 2^255` (inclusive). It is simply a wrapper around `u8`, which stores the exponent.

`Pow2` is typically used for aligning integer values, such as I/O buffer sizes, page sizes, etc.

Negative powers of 2 are not supported because they have little or no application in managing memory, quick multiplication, etc.

`Pow2` can represent values outside of the range of specific integer types. For example, `Pow2::from_exponent(40)` cannot be converted to `u32`. The conversion implementations treat this in a way similar to arithmetic overflow for operations such as `x * y`; the operation is defined, but may fail at runtime.

It would be possible to define a family of `Pow2` variants, one for each primitive integer type. However, the ergonomics of that design might be undesireable; it is left for future study.

The operators defined for `Pow2` are defined in terms of the value of the power of 2, not the exponent. For example, `Pow2 * Pow2` results in adding the exponents, not in multiplying the exponents.

# Examples

```const PAGE_SIZE: Pow2 = Pow2::from_exponent(12);
assert_eq!(u32::from(PAGE_SIZE), 0x1000);
let x: u32 = 0x1eee;
assert_eq!(PAGE_SIZE.align_down(x), 0x1000);
assert_eq!(PAGE_SIZE.align_up(x), Some(0x2000));
assert_eq!(PAGE_SIZE.align_up_unchecked(x), 0x2000);```

The `pow2_const!` macro can be used for writing constant powers of 2, using a value rather than an exponent. Due to current limitations of const fns, the `pow2_const!` macro does not check whether the input is a valid power of 2. If it is not a power of 2, then its behavior is undefined.

```use pow2::{Pow2, pow2_const};
const PAGE_SIZE: Pow2 = pow2_const!(0x1000);
assert_eq!(PAGE_SIZE.exponent(), 12);```

# Signed examples

`Pow2` works with signed types as well as unsigned.

```use pow2::Pow2;
const ALIGN4: Pow2 = Pow2::from_exponent(2);
assert_eq!(ALIGN4.align_up(4i32), Some(4i32));
assert_eq!(ALIGN4.align_up(3i32), Some(4i32));
assert_eq!(ALIGN4.align_up(2i32), Some(4i32));
assert_eq!(ALIGN4.align_up(1i32), Some(4i32));
assert_eq!(ALIGN4.align_up(-0i32), Some(0i32));
assert_eq!(ALIGN4.align_up(-1i32), Some(0i32));
assert_eq!(ALIGN4.align_up(-2i32), Some(0i32));
assert_eq!(ALIGN4.align_up(-3i32), Some(0i32));
assert_eq!(ALIGN4.align_up(-4i32), Some(-4i32));
assert_eq!(ALIGN4.align_up(-5i32), Some(-4i32));
assert_eq!(ALIGN4.align_up(-6i32), Some(-4i32));
assert_eq!(ALIGN4.align_up(-7i32), Some(-4i32));
assert_eq!(ALIGN4.align_up(-8i32), Some(-8i32));```

# Unsafe code examples

This library does not contain unsafe code, but it can be used by unsafe code to operate on pointers. This is because Rust allows safe code to operate on the values of unsafe pointers, but not to dereference them.

```use pow2::{Pow2, pow2_const};

const U32_ALIGN: Pow2 = Pow2::align_of::<u32>();

let array: [u32; 4] = [ 111, 222, 333, 444 ];
let item_0_address: *const u8 = &array as *const u32 as *const u8;
let item_1_address: *const u8 = &array as *const u32 as *const u8;

assert_eq!(
U32_ALIGN.align_up((item_0_address as usize + 1) as *const u8).unwrap(),
);```

## Macros

 pow2_const A helper macro for defining constant values of `Pow2` using constant inputs.

## Structs

 NotPow2 A zero-sized error type for reporting failures to convert to a `Pow2`. Pow2 Represents a non-negative power of 2, by storing its exponent.

## Constants

 GIB The number of bytes in one gibibyte (1,073,741,824). KIB The number of bytes in one kebibyte (1,024). MIB The number of bytes in one mebibyte (1,048,576). TIB The number of bytes in one tebibyte (1,099,511,627,776).

## Traits

 IntPow2 Integers that can be represented as powers of 2.