JBlam.Collections.ValueBitArray 0.0.1-testing

JBlam.Collections.ValueBitArray

A thin value-type wrapper around an underlying integer value.

Designed to help represent heavily compacted low level datastructures you might find in microcontroller register values.

Usage

using JBlam.Collections.Immutable;

const byte B = 0b0101_0011;

// The backing type is generic. Use ushort, uint, ulong, BigInteger, etc.
var bitarray = ValueBitArray.Create(B);
bool isBit1Set = bitarray[1];
byte highNibble = bitarray.GetShifted(4..); // equals 0b0101

// you can also: enumerate each bit, enumerate the set indicies, work with unshifted masks,
// test equality, perform bitwise AND / OR / XOR / NOT, etc.

Not a re-implementation of BCL's BitArray or BitVector32

System.Collections.BitArray is a quite different design to this:

• The BCL BitArray type is a class, with a variable-length backing memory array of bytes. This type is a value type, and has a fixed size if the underlying T has a fixed size. (Most integer types are fixed-size, but BigInteger is not.)
• The BCL BitVector32 type is fixed to 32-bit integers. The JBlam type is generic, so it can be type-safe over your target integer size. (For example, you might be interacting with a microcontroller which uses a 16-bit integer registry.)
• The BCL BitVector32 type has a complex Section construct for subranges. The JBlam type indexes bits directly, and allows subrange access by index using Range.

Not the same as [Flags] enum

There is some functional overlap between ValueBitArray<T> and a flags enum. For example:

using JBlam.Collections.Immutable;

[Flags]
enum E
{
    None = 0,
    Sharks = 0b0001,
    Kittens = 0b0010,
    Asparagus = 0b01000,
}

var e = (E)(0b1010);
var enumHasKittens = e.HasFlag(E.Kittens);

const int KittensBit = 0b0010;
var bitarray = new ValueBitArray<byte>(0b1010);
var bitarrayHasKittens = bittarray[KittensBit];

My suggestion for how to choose:

• If you are interacting with 10 or more different bit patterns, use ValueBitArray. Supporting that many enum types is too hard.
• If there are logically "embedded integers" inside bitmasks, use ValueBitArray.
• If you need to flexibly support new bitmask layouts without recompiling your program, use ValueBitArray. Flags enums must be defined at compile time (or using Reflection, or ILEmit).
• Otherwise, use Flags enums. The declaration is somewhat nicer, and strong-typing the members is useful.