enumbitmap

Documentation

Overview

Package enumbitmap provides helpers to encode and decode enumeration values as bitmaps.

It solves the problem of compactly representing sets of named flags using a single integer, while still allowing easy conversion back to human-readable values.

Each bit corresponds to a unique enumeration value. The package processes up to 32 bit positions (1<<0 through 1<<31), making it suitable for compact flag sets and feature toggles.

Contract:

Enum IDs must be distinct single-bit powers of two in the range 1<<0 through 1<<31. An ID of 0, or any multi-bit value, cannot be represented as a set bit and is therefore never produced by BitMapToStrings; such IDs make encoding and decoding asymmetric and should be avoided. The value 0 always decodes to an empty slice.

Portability:

Values are treated as the low 32 bits of a host int. Bit 31 is the sign bit on platforms where int is 32 bits wide, so this package is intended for 64-bit platforms; on a 32-bit build, inputs at or above 1<<31 behave in implementation-defined ways and should be avoided.

Top features:

• convert string slices to bitmap integers with StringsToBitMap
• convert bitmap integers back to string slices with BitMapToStrings
• report unknown names or bit positions with clear aggregated errors
• preserve partial conversion results even when unknown values are found (useful for tolerant parsing and diagnostics)

Benefits:

• compact in-memory and storage representation for enum sets
• easy interoperability with bitmask-based APIs and database fields
• predictable conversion behavior for both strict and best-effort workflows

Example with 8 bits:

00000000 =   0 dec = NONE
00000001 =   1 dec = FIRST
00000010 =   2 dec = SECOND
00000100 =   4 dec = THIRD
00001000 =   8 dec = FOURTH
00010000 =  16 dec = FIFTH
00100000 =  32 dec = SIXTH
01000000 =  64 dec = SEVENTH
10000000 = 128 dec = EIGHTH
00001001 = 1 + 8 = 9 dec = FIRST + FOURTH

Index

• Variables
• func BitMapToStrings(enum map[int]string, v int) ([]string, error)
• func StringsToBitMap(enum map[string]int, s []string) (int, error)

Examples

• BitMapToStrings
• StringsToBitMap

Variables

var (
	// ErrUnknownBitValues is returned by BitMapToStrings when v has set bits that
	// are not present in the enum map. Any known bits are still returned, so the
	// partial slice remains usable for tolerant parsing. Match it with errors.Is.
	ErrUnknownBitValues = errors.New("enumbitmap: unknown bit values")

	// ErrUnknownStringValues is returned by StringsToBitMap when s contains names
	// that are not present in the enum map. Any known names are still combined into
	// the returned bitmap. Match it with errors.Is.
	ErrUnknownStringValues = errors.New("enumbitmap: unknown string values")
)

Functions

func BitMapToStrings

func BitMapToStrings(enum map[int]string, v int) ([]string, error)

BitMapToStrings expands a bitmap value into its enum names.

Unknown set bits are reported in the returned error as their bit mask values (1, 2, 4, …), while known values are still returned, enabling tolerant parsing and diagnostics.

Only the lowest 32 bits (masks 1<<0 through 1<<31) are inspected; any bits set at position 32 or higher are silently ignored.

When one or more set bits are missing from enum, the returned error wraps ErrUnknownBitValues and lists the unknown masks, while the known names are still returned.

Example

package main

import (
	"fmt"
	"log"

	"github.com/tecnickcom/nurago/pkg/enumbitmap"
)

func main() {
	// create a binary map
	// each bit correspond to a different entry (IDs are single-bit powers of two)
	eis := map[int]string{
		1:   "first",   // 00000001
		2:   "second",  // 00000010
		4:   "third",   // 00000100
		8:   "fourth",  // 00001000
		16:  "fifth",   // 00010000
		32:  "sixth",   // 00100000
		64:  "seventh", // 01000000
		128: "eighth",  // 10000000
	}

	// convert binary code to a slice of strings
	s, err := enumbitmap.BitMapToStrings(eis, 0b00101010) // 42
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(s)

}

Output:
[second fourth sixth]

func StringsToBitMap

func StringsToBitMap(enum map[string]int, s []string) (int, error)

StringsToBitMap converts enum names into a combined bitmap value.

Unknown names are aggregated in the returned error, which wraps ErrUnknownStringValues, while known values are still included in the bitmap.

The IDs in enum are combined with a bitwise OR and are not validated: for the result to round-trip through BitMapToStrings, every ID must be a distinct single-bit power of two in the range 1<<0 through 1<<31 (see the package Contract). An ID of 0 contributes nothing, and a multi-bit ID sets several bits at once.

Example

package main

import (
	"fmt"
	"log"

	"github.com/tecnickcom/nurago/pkg/enumbitmap"
)

func main() {
	// create a binary map
	// each entry is assigned to a different bit (single-bit powers of two)
	esi := map[string]int{
		"first":   1,   // 00000001
		"second":  2,   // 00000010
		"third":   4,   // 00000100
		"fourth":  8,   // 00001000
		"fifth":   16,  // 00010000
		"sixth":   32,  // 00100000
		"seventh": 64,  // 01000000
		"eighth":  128, // 10000000
	}

	// convert a slice of string to the equivalent binary code
	b, err := enumbitmap.StringsToBitMap(
		esi,
		[]string{
			"second",
			"fourth",
			"sixth",
		},
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(b)

}

Output:
42