flagged

type BitFlags interface {
	// Is reports whether the bit at index idx is set to true or not.
	// It panics if idx is out of the allowed range [0, Size-1].
	Is(idx BitIndex) (set bool)

	// Set sets the bit at index idx to true, returning its old value.
	// It panics if idx is out of the allowed range [0, Size-1].
	Set(idx BitIndex) (old bool)

	// Reset sets the bit at index idx to false, returning its old value.
	// It panics if idx is out of the allowed range [0, Size-1].
	Reset(idx BitIndex) (old bool)

	// SetTo sets the bit at index idx to new, returning its old value.
	// It panics if idx is out of the allowed range [0, Size-1].
	SetTo(idx BitIndex, new bool) (old bool)

	// Toggle toggles the bit at index idx, returning its new value.
	// It panics if idx is out of the allowed range [0, Size-1].
	Toggle(idx BitIndex) (new bool)

	// SetAll sets all bits to true.
	SetAll()

	// ResetAll sets all bits to false.
	ResetAll()

	// AnySet reports whether any of the bits are set to true.
	AnySet() bool

	// AllSet reports whether all the bits are set to true.
	AllSet() bool

	// AnyOf reports whether any of the bits at indexes idx are set to true.
	// If no indexes are passed, it acts as [BitFlags.AnySet].
	AnyOf(idx ...BitIndex) bool

	// AllOf reports whether all the bits at indexes idx are set to true.
	// If no indexes are passed, it acts as [BitFlags.AllSet].
	AllOf(idx ...BitIndex) bool

	// Size is the number of bits included in this [BitFlags] value.
	// It represents the bit width of the underlying uint.
	// It's one of 8, 16, 32, 64.
	Size() int

	// String returns the binary representation of this [BitFlags] value,
	// formatted like fmt's %b verb, but with leading zeros to preserve
	// the full bit width of the underlying type (Size).
	String() string

	// PrettyString returns a human-readable binary representation of
	// this [BitFlags] value, with 1 represented as 'I' and 0 as 'O', and
	// with '|' delimiter between each bit and '_' delimiter each 8 bits.
	//
	// Example:
	//
	//  String() // "0000010001000100"
	//  PrettyString() // "O|O|O|O|O|I|O|O_O|I|O|O|O|I|O|O"
	PrettyString() string
}

type BitFlags8 uint8

type BitFlags16 uint16

type BitFlags32 uint32

type BitFlags64 uint64

type BitIndex = int