BitPacking

bitwidth(T::Type)

Returns the number of used bits in T.

The bit representation of T is expected to not take on any value equal to or greater than 2^bitwidth(T). For example, a 1-bit type should be limited to 0b00000000 and 0b00000001.

Examples

julia> bitwidth(UInt8)
8

julia> bitwidth(Bool)
1

BitPackedArray{W,T,N,P<:AbstractArray{UInt8,N}} <: AbstractArray{T,N}

A wrapper for an array of packed bytes.

Use bitpacked to create a BitPackedArray, and bitunpacked to unpack it.

bitpacked(x::AbstractArray, W=bitwidth(T))

Returns a BitPackedArray of the same size as x, with each element packed into W bits.

bitpacked is a no-op if x is already a BitPackedArray with the same bitwidth.

Examples

julia> x = rand(Bool, 8, 2);

julia> packed = bitpacked(x, 1);

julia> packed == x
true

julia> packed .= [true false];

julia> all(packed[:,1])
true

julia> !any(packed[:,2])
true

bitunpacked(x::BitPackedArray)

Returns an array of the same size as x, with each element unpacked from W bits.

packbits!(w::Int, packed_bytes::AbstractArray{UInt8}, x::AbstractArray; groups::Val=Val(1))

Mutates packed_bytes in-place to pack x into W bits per element.

The keyword argument groups can be increased to improve performance, while limiting the allowed sizes of the first dimension of x.

See also packbits, unpackbits!, unpackbits.

packbits(w::Int, x::AbstractArray; groups::Val=Val(1))

Returns a BitPackedArray of the same size as x, with each element packed into W bits per element.

See also packbits!, unpackbits!, unpackbits.

unpackbits!(w::Int, x::AbstractArray, packed_bytes::AbstractArray{UInt8}; groups::Val=Val(1))

Mutates x in-place to unpack packed_bytes into byte-sized elements of type eltype(x).

The keyword argument groups can be increased to improve performance, while limiting the allowed sizes of the first dimension of x.

See also packbits!, packbits, unpackbits.

unpackbits(w::Int, packed_bytes::AbstractArray{UInt8}, T::Type=UInt8; groups::Val=Val(1))

Returns an array of the same size as packed_bytes, into byte-sized elements of type T.

See also packbits!, packbits, unpackbits!.