feat(yaflags): Add minimal YaFlags

Author: YaCodesDevelopment

yaflags/errors.go

@@ -0,0 +1,8 @@
+package yaflags
+
+import "errors"
+
+var (
+	ErrTooManyBits        = errors.New("too many bits for target type")
+	ErrBitIndexOutOfRange = errors.New("bit index out of range")
+)

yaflags/yaflags.go

@@ -0,0 +1,79 @@
+package yaflags
+
+import (
+	"fmt"
+	"math/bits"
+	"net/http"
+
+	"github.com/YaCodeDev/GoYaCodeDevUtils/yaerrors"
+)
+
+type uints interface {
+	~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uint
+}
+
+func typeBitSize[T uints]() uint8 {
+	var zero T
+
+	return uint8(bits.Len64(uint64(^zero)))
+}
+
+// PackBitIndexes packs a list of bit positions into an unsigned integer of type T.
+// The function returns an error if the number of bits exceeds the size of T or if a bit index
+// is outside of the allowable range for T.
+func PackBitIndexes[T uints](bits []uint8) (T, yaerrors.Error) {
+	var flags T
+
+	maxBits := typeBitSize[T]()
+
+	if len(bits) > int(maxBits) {
+		return 0, yaerrors.FromError(
+			http.StatusBadRequest,
+			ErrTooManyBits,
+			fmt.Sprintf(
+				"pack bits: received %d bits but %T supports at most %d",
+				len(bits),
+				flags,
+				maxBits,
+			),
+		)
+	}
+
+	for _, bit := range bits {
+		if bit >= maxBits {
+			return 0, yaerrors.FromError(
+				http.StatusBadRequest,
+				ErrBitIndexOutOfRange,
+				fmt.Sprintf(
+					"pack bits: index %d out of range for %T (%d bits)",
+					bit,
+					flags,
+					maxBits,
+				),
+			)
+		}
+
+		flags |= T(1) << bit
+	}
+
+	return flags, nil
+}
+
+// UnpackBitIndexes unpacks a list of bit positions from an unsigned integer of type T.
+func UnpackBitIndexes[T uints](flags T) []uint8 {
+	if flags == 0 {
+		return nil
+	}
+
+	maxBits := typeBitSize[T]()
+
+	result := make([]uint8, 0, bits.OnesCount64(uint64(flags)))
+
+	for bit := range maxBits {
+		if flags&(T(1)<<bit) != 0 {
+			result = append(result, bit)
+		}
+	}
+
+	return result
+}

yaflags/yaflags_test.go

@@ -0,0 +1,76 @@
+package yaflags
+
+import (
+	"errors"
+	"net/http"
+	"reflect"
+	"testing"
+)
+
+type customFlags uint16
+
+func TestPackBitIndexesSuccess(t *testing.T) {
+	t.Parallel()
+
+	flags, err := PackBitIndexes[uint16]([]uint8{0, 3, 7})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	const want uint16 = (1 << 0) | (1 << 3) | (1 << 7)
+	if flags != want {
+		t.Fatalf("wrong flags: want %016b, got %016b", want, flags)
+	}
+}
+
+func TestPackBitIndexesTooManyBits(t *testing.T) {
+	t.Parallel()
+
+	_, err := PackBitIndexes[uint8]([]uint8{0, 1, 2, 3, 4, 5, 6, 7, 0})
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+
+	if !errors.Is(err, ErrTooManyBits) {
+		t.Fatalf("expected ErrTooManyBits, got %v", err)
+	}
+
+	if err.Code() != http.StatusBadRequest {
+		t.Fatalf("expected HTTP status %d in error code, got %d", http.StatusBadRequest, err.Code())
+	}
+}
+
+func TestPackBitIndexesBitIndexOutOfRange(t *testing.T) {
+	t.Parallel()
+
+	_, err := PackBitIndexes[uint8]([]uint8{0, 8})
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+
+	if !errors.Is(err, ErrBitIndexOutOfRange) {
+		t.Fatalf("expected ErrBitIndexOutOfRange, got %v", err)
+	}
+}
+
+func TestUnpackBitIndexesReturnsSortedIndexes(t *testing.T) {
+	t.Parallel()
+
+	const value customFlags = (1 << 0) | (1 << 4) | (1 << 9)
+
+	got := UnpackBitIndexes(value)
+	want := []uint8{0, 4, 9}
+
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("expected %v, got %v", want, got)
+	}
+}
+
+func TestUnpackBitIndexesZeroValue(t *testing.T) {
+	t.Parallel()
+
+	got := UnpackBitIndexes[uint32](0)
+	if got != nil {
+		t.Fatalf("expected nil slice, got %v", got)
+	}
+}