enum

README

go-enum

Object as the next best thing before Go supports a more useable enum.

Motivation

Go does not have an explicit enum keyword to associate string based values with integer based indexes. String values are necessary for human consumption while integer based indexes are necessary to save storage spaces. The lack of a automatic conversion mechanism makes writing persistence layer quite painful. This small library is to cover the simple use case of converting between string values and integer indexes.

Install

go get -u github.com/imulab/go-enum

Usage

The simple use case is to create an enum for single value purposes:

options := enum.New("red", "green", "blue")

// Get indexes (which could be saved to database)
options.Index("red")   // 1
options.Index("green") // 2
options.Index("blue")  // 3

// Restore values from indexes
options.Value(1) // red
options.Value(2) // green
options.Value(3) // blue

The second use case is to create an enum for multiple value purposes:

multiSelect := enum.NewComposite("one", "two", "three")

// Get indexes, same as before, but in the order of 2
options.Index("one")   // 1
options.Index("two")   // 2
options.Index("three") // 4

// Compute a bitmap to represent multiple values together
multiSelect.BitMap("one", "three") // 5

// Hydrate/Restore values from bitmap
multiSelect.Hydrate(5) // ["one", "three"]

For details, please consult Go Doc.

Documentation

Index

• Constants
• type Enum
  • func New(values ...string) *Enum
  • func NewComposite(values ...string) *Enum
  • func NewCustom(values []string, indexFunc func(int) uint) *Enum
  • func (e *Enum) BitMap(values ...string) uint
  • func (e *Enum) Contains(values ...string) bool
  • func (e *Enum) Hydrate(bits uint) []string
  • func (e *Enum) Index(value string) uint
  • func (e *Enum) Value(index uint) string
  • func (e *Enum) ValueOK(index uint) (string, bool)

Constants

const (
	// NoRecord is the special index returned for non-member enums. Notice that the member
	// indexes always start from 1, hence 0 is never used.
	NoRecord uint = 0
)

Types

type Enum

type Enum struct {
	// contains filtered or unexported fields
}

Enum is the enumeration object, which holds one or more string values. Each string value is assigned a unique uint index and allows for quick lookup. An Enum is read-only after creation.

func New

func New(values ...string) *Enum

New creates an Enum with the given values. The items in the Enum will be indexed sequentially in the order of values, starting at 1. For instance:

// one is indexed at 1
// two is indexed at 2
// three is indexed at 3
New("one", "two", "three")

This constructor fits the most use cases where a value is assigned a single enumeration. For instance:

var someType = New("one", "two", "three")
var some = "one" // or "two", or "three"
var indexOfOne = someType.Index(some)
var _some = someType.Value(indexOfOne)

This constructor does NOT cover cases where a value may correspond to several values of enumerations, such as in a "Set" data structure. See NewComposite for this case.

func NewComposite

func NewComposite(values ...string) *Enum

NewComposite creates an Enum with the given values. The items in the Enum will be indexed sequentially in the order of 2. For instance:

// one is indexed at 1
// two is indexed at 2
// three is indexed at 4
NewComposite("one", "two", "three")

This constructor fits the most use cases where a value is assigned one or more enumeration. For instance:

var someType = NewComposite("one", "two", "three")
var some = []string{"one", "three"}
var bitmap = someType.BitMap(some...)	// bitmap == 5
var values = someType.Hydrate(bitmap)	// values == ["one", "three"]

func NewCustom

func NewCustom(values []string, indexFunc func(int) uint) *Enum

NewCustom creates an Enum with the given values and the indexFunc will be used to index each value at position i.

func (*Enum) BitMap

func (e *Enum) BitMap(values ...string) uint

BitMap returns a bit map of given values in the Enum. Caution that only Enum created with NewComposite should use this method, as other Enum could have applied overlapping indexed which result in a irreversible bitmap.

func (*Enum) Contains

func (e *Enum) Contains(values ...string) bool

Contains returns true if all the given values are registered with Enum.

func (*Enum) Hydrate

func (e *Enum) Hydrate(bits uint) []string

Hydrate reverses the computed bitmap and returns the corresponding values. Caution that only Enum created with NewComposite should use this method.

func (*Enum) Index

func (e *Enum) Index(value string) uint

Index returns the index of the given value. If the value does not exist in the Enum, a special NoRecord index is returned.

func (*Enum) Value

func (e *Enum) Value(index uint) string

Value returns the value that corresponds to the given index. If the provided index does not map to a value, empty string is returned.

func (*Enum) ValueOK

func (e *Enum) ValueOK(index uint) (string, bool)

ValueOK is an alternative to Value in that it explicitly returns a boolean value indicating whether is value is found. This is useful when the member values include the empty string