std.bit

std.bit provides bit-level helpers for integer values. Most functions are generic over the builtin Integer marker. swap_bytes uses the narrower closed ByteAlignedInteger capability because its logical-byte contract requires an integer width divisible by eight.

How It Works

Integer is an auto-imported compiler marker implemented by scalar signed and unsigned integers, including custom iN/uN widths. ByteAlignedInteger implies Integer and is implemented exactly when the scalar integer's semantic bit width is divisible by eight. User types cannot implement or forge either closed numeric capability. bool, non-byte-aligned custom integers, Vector, and Matrix do not implement ByteAlignedInteger.

swap_bytes reverses the order of the value's logical eight-bit chunks and returns the same type. It operates on the exact fixed-width bit pattern, so signed and unsigned values use identical bit manipulation. The operation does not depend on host endianness, ABI layout, storage padding, or a selected backend. It is the identity for i8/u8, applying it twice returns the original value, and byte-aligned custom widths such as i24 and u40 are valid.

The helpers do not allocate and do not throw. Invalid type use is rejected by their declared capability bounds. Bit representation matches the scalar integer type; these helpers do not define serialization, aggregate endianness, or memory layout for structs, Vectors, or Matrices.

import std.bit;

fn mirror<T: Integer>(value: T) -> T {
	return bit.reverse_bits(value);
}

fn main() {
	assert bit.swap_bytes(0x12 as u8) == (0x12 as u8);
	assert bit.swap_bytes(0x0102 as u16) == (0x0201 as u16);
	assert bit.swap_bytes(0x010203_u24) == 0x030201_u24;
	assert mirror<u8>(0b10110000 as u8) == (0b00001101 as u8);
	assert bit.count_ones(0b10110100 as u8) == (4 as u8);
	assert bit.rotate_left(0b10000001 as u8, 10 as u8) == (0b00000110 as u8);
}

API Reference

Builtin Numeric Interfaces

Type	Kind	Public fields	Methods	Description
Integer	closed builtin marker interface	N/A	None	Implemented by scalar signed and unsigned integers, including custom iN/uN; bool is excluded.
ByteAlignedInteger	closed builtin capability	N/A	None	Implies Integer; implemented exactly by scalar signed/unsigned integers whose semantic bit width is divisible by eight. User code cannot implement or forge it.
Signed	builtin marker interface	N/A	None	Implemented by signed integer types and implies Integer.
Unsigned	builtin marker interface	N/A	None	Implemented by unsigned integer types and implies Integer.

Functions

Name	Signature	Parameters	Returns	Description
swap_bytes	export const fn swap_bytes<T: ByteAlignedInteger>(x: T) -> T;	x: byte-aligned scalar integer value	T	Reverses logical-byte order; i8/u8 are identity and the operation is an involution.
reverse_bits	reverse_bits<T: Integer>(x: T) -> T	x: integer value	T	Reverses all bits in the value.
count_ones	count_ones<T: Integer>(x: T) -> T	x: integer value	T	Counts set bits and returns the count in the same integer type.
leading_zeros	leading_zeros<T: Integer>(x: T) -> T	x: integer value	T	Counts zero bits before the highest set bit.
trailing_zeros	trailing_zeros<T: Integer>(x: T) -> T	x: integer value	T	Counts zero bits after the lowest set bit.
rotate_left	rotate_left<T: Integer>(x: T, n: T) -> T	x: integer value, n: rotate count	T	Rotates bits left.
rotate_right	rotate_right<T: Integer>(x: T, n: T) -> T	x: integer value, n: rotate count	T	Rotates bits right.

Related Modules

Use std.arith for explicit integer overflow policies and std.mem for raw memory byte operations.

Status

std.bit is the current public bit-operation API. For the full exported surface, see Standard Library Inventory. swap_bytes has no Vector or Matrix overload; aggregate bit operations require a future coherent decision for the whole module.