Macro bitvec::bits

macro_rules! bits {
    (static mut $order:ty, Cell<$store:ident>; $val:expr; $len:expr) => { ... };
    (static mut $order:ty, $store:ident; $val:expr; $len:expr) => { ... };
    (static mut $val:expr; $len:expr) => { ... };
    (static mut $order:ident, Cell<$store:ident>; $($val:expr),* $(,)?) => { ... };
    (static mut $order:ident, $store:ident; $($val:expr),* $(,)?) => { ... };
    (static mut $($val:expr),* $(,)?) => { ... };
    (static $order:ty, Cell<$store:ident>; $val:expr; $len:expr) => { ... };
    (static $order:ty, $store:ident; $val:expr; $len:expr) => { ... };
    (static $val:expr; $len:expr) => { ... };
    (static $order:ident, Cell<$store:ident>; $($val:expr),* $(,)?) => { ... };
    (static $order:ident, $store:ident; $($val:expr),* $(,)?) => { ... };
    (static $($val:expr),* $(,)?) => { ... };
    (mut $order:ty, $store:ty; $val:expr; $len:expr) => { ... };
    (mut $val:expr; $len:expr) => { ... };
    (mut $order:ident, Cell<$store:ident>; $($val:expr),* $(,)?) => { ... };
    (mut $order:ident, $store:ident; $($val:expr),* $(,)?) => { ... };
    (mut $order:path, Cell<$store:ident>; $($val:expr),* $(,)?) => { ... };
    (mut $order:path, $store:ident; $($val:expr),* $(,)?) => { ... };
    (mut $($val:expr),* $(,)?) => { ... };
    ($order:ty, $store:ty; $val:expr; $len:expr) => { ... };
    ($val:expr; $len:expr) => { ... };
    ($order:ident, Cell<$store:ident>; $($val:expr),* $(,)?) => { ... };
    ($order:ident, $store:ident; $($val:expr),* $(,)?) => { ... };
    ($order:path, Cell<$store:ident>; $($val:expr),* $(,)?) => { ... };
    ($order:path, $store:ident; $($val:expr),* $(,)?) => { ... };
    ($($val:expr),* $(,)?) => { ... };
}

Creates a borrowed BitSlice in the local scope.

This macro constructs a BitArray temporary and then immediately borrows it as a BitSlice. The compiler should extend the lifetime of the underlying BitArray for the duration of the expression’s lifetime.

This macro takes a superset of the vec! argument syntax: it may be invoked with either a sequence of bit expressions, or a single bit expression and a repetiton counter. Additionally, you may provide the names of a BitOrder and a BitStore implementor as the BitArray’s type arguments. You may also use mut as the first argument of the macro in order to produce an &mut BitSlice reference rather than a &BitSlice immutable reference.

Argument Rules

Bit expressions must be integer literals. Ambiguity restrictions in the macro syntax forbid the use of identifiers to existing variables, even const values. These are converted to bool through the expression $val != 0. Any non-zero enteger becomes true, and 0 becomes false.

You may use any name or path to a BitOrder implementation. However, the identifier tokens Lsb0, Msb0, and LocalBits are matched directly and specialized to have compile-time constructions, whereäs any other name or path will not be known to the macro, and will execute at runtime.

The BitStore argument must be the name of an unsigned integer fundamental, an atomic, or a Cell<> wrapper of that unsigned integer. These are matched by token, not by type, and no other identifier is accepted. Using any other token will cause the macro to fail.

static Production

Prepending the argument list with static or static mut (so bits!(ARGS…) becomes bits!(static [mut] ARGS…)) causes the macro to expand to code that emits a hidden static or static mut value, initialized with a bitarr!(const ARGS…) expansion and then reborrowed. The name of the hidden static object does not escape the macro invocation, and so the returned BitSlice handle is the single point of access to it.

Because both indexing and mutable reborrows are forbidden in const contexts, the produced BitSlice references can only be bound to let, not to static. They have the &'static lifetime, but to give the names a static binding, you must use bitarr!(const ARGS…) and then borrowed as a BitSlice at the point of use.

Examples

use bitvec::prelude::*;
use core::cell::Cell;

radium::if_atomic! { if atomic(16) {
  use core::sync::atomic::AtomicU32;
} }

let a: &BitSlice = bits![0, 1, 0, 1, 2];
assert_eq!(a.count_ones(), 3);

let b: &mut BitSlice = bits![mut 2; 5];
assert!(b.all());
assert_eq!(b.len(), 5);

let c = bits![Lsb0, Cell<u16>; 0, 1, 0, 0, 1];
c.set_aliased(0, true);
let d = bits![Msb0, AtomicU32; 0, 0, 1, 0, 1];
d.set_aliased(0, true);