gnum

README

Y Use gnum❔

• No code generation.
• Constant.
• Fast.
• Can be used as generic T.
• Concurrency safe.

Benchmarks💨

Getting Started

go get github.com/joelboim/gnum

Example

First lets declare an enum type:

package enums

import "github.com/joelboim/gnum"

type (
	Color = gnum.Enum[struct {
		Red,
		Blue,
		Green color
	}]
	color int
)

const (
	Red Color = iota
	Blue
	Green
)

Now we can use it like other languages Enums:

func main() {
	fmt.Println(Red, Blue, Green) // Red Blue Green

	fmt.Println(gnum.Names[Color]()) // [Red Blue Green]

	fmt.Println(fmt.Sprintf("%T", gnum.Enums[Color]())) // []gnum.Enum[struct { Red main.color; Blue main.color; Green main.color }]

	_, err := gnum.Parse[Color]("red")
	fmt.Println(err) // error

	colorJson, _ := json.Marshal(struct{ Color Color }{Blue})
	fmt.Println(string(colorJson)) // {"Color":"Blue"}
}

Can be also used as generic type:

func foo[T gnum.Enumer[T]](enum T) {
	fmt.Println(
		enum.Names(),
		enum.Type())
}

func main() {
    foo(Red)    // [red blue green] color
    foo(Square) // [Square] shape
}

If you need to customize elements of the enum you can do it with tags:

type (
	Color = gnum.Enum[struct {
		Red    color
		Blue   color `gnum:"value=3,name=b_l_u_e"`
		Green  color
		Yellow color
	}]
	color int
)

Documentation

Index

• func Enums[T Enumer[T]]() []T
• func Names[T Enumer[T]]() []string
• func Parse[T Enumer[T]](name string) (T, error)
• func SetOptions(options ...Option)
• func Strings[T Enumer[T]]() []string
• func Type[T Enumer[T]]() string
• func Values[T Enumer[T]]() []int
• type Enum
  • func (e Enum[T]) Enums() []Enum[T]
  • func (e Enum[T]) MarshalText() ([]byte, error)
  • func (e Enum[T]) Name() string
  • func (e Enum[T]) Names() []string
  • func (e Enum[T]) Parse(name string) (Enum[T], error)
  • func (e Enum[T]) String() string
  • func (e Enum[T]) Strings() []string
  • func (e Enum[T]) Type() string
  • func (e *Enum[T]) UnmarshalText(text []byte) error
  • func (e Enum[T]) Values() []int
• type Enumer
• type Option
  • func CaseInsensitive(caseInsensitive bool) Option
  • func ParseCallback(callback func(value string) string) Option
  • func StringCallback(callback func(enumName string) string) Option

Functions

func Enums

func Enums[T Enumer[T]]() []T

Enums is a static function to handel all enums that implements Enumer[T] interface. It returns a list of all Enum[T] declarations mapped to T.

func Names

func Names[T Enumer[T]]() []string

Names is a static function to handel all enums that implements Enumer[T] interface. It returns a list of all Enum[T] names. (the programmatic string representation of the enum value).

func Parse

func Parse[T Enumer[T]](name string) (T, error)

Parse is a static function to handel all enums that implements Enumer[T] interface. It will try to parse the given name with the underline Enum.Parse implementation.

func SetOptions

func SetOptions(options ...Option)

SetOptions Sets multiple Option on the global scope.

func Strings

func Strings[T Enumer[T]]() []string

Strings is a static function to handel all enums that implements Enumer[T] interface. It returns a list of all Enum[T] strings.

func Type

func Type[T Enumer[T]]() string

Type is a static function to handel all enums that implements Enumer[T] interface. It returns the underline type name.

func Values

func Values[T Enumer[T]]() []int

Values is a static function to handel all enums that implements Enumer[T] interface. It returns a list of all Enum[T] ints.

Types

type Enum

type Enum[T any] int

Enum uses T struct definition for it's mapping of enum name to value.

func (Enum[T]) Enums

func (e Enum[T]) Enums() []Enum[T]

Enums returns a list of all Enum[T] declarations mapped to T

func (Enum[T]) MarshalText

func (e Enum[T]) MarshalText() ([]byte, error)

MarshalText implements the TextMarshaler interface for T.

func (Enum[T]) Name

func (e Enum[T]) Name() string

Name returns the Enum[T] programmatic string representation.

func (Enum[T]) Names

func (e Enum[T]) Names() []string

Names returns all the Enum[T] programmatic string representations sorted by the enum values.

func (Enum[T]) Parse

func (e Enum[T]) Parse(name string) (Enum[T], error)

Parse tries to parse an enum name based on the underline enum name to enum value mapping. If CaseInsensitive(true) is set, Parse will use the lowered case name to value mapping instead.

func (Enum[T]) String

func (e Enum[T]) String() string

String returns the string representation of an Enum[T] value.

func (Enum[T]) Strings

func (e Enum[T]) Strings() []string

Strings returns all the Enum[T] string representations sorted by the enum values.

func (Enum[T]) Type

func (e Enum[T]) Type() string

Type returns the underline T type.

func (*Enum[T]) UnmarshalText

func (e *Enum[T]) UnmarshalText(text []byte) error

UnmarshalText implements the TextUnmarshaler interface for T.

func (Enum[T]) Values

func (e Enum[T]) Values() []int

Values returns all the Enum[T] int representations sorted by the enum values.

type Enumer

type Enumer[T ~int] interface {
	~int
	Enums() []T
	Name() string
	Names() []string
	Parse(name string) (T, error)
	String() string
	Strings() []string
	Type() string
	Values() []int
}

Enumer is an interface for using Enum instances with generics, e.g, `func foo[T Enumer[T]](enum T)` could do any Enum operations while preserving the original Enum type (T)

type Option

type Option func(config *config)

Option callback function that sets specific value on an *config instance.

func CaseInsensitive

func CaseInsensitive(caseInsensitive bool) Option

CaseInsensitive - when set to true, Enum.Parse and Enum.UnmarshalText, will ignore the string case when parsing.

func ParseCallback

func ParseCallback(callback func(value string) string) Option

ParseCallback will be applied for each Enum.Parse call and Enum.UnmarshalText.

func StringCallback

func StringCallback(callback func(enumName string) string) Option

StringCallback will be applied for each Enum.String call and Enum.Strings.