box

README

box

The box package provides generic types to reduce memory footprint and GC pressure.

Installation

go get github.com/sevlyar/box

Documentation

https://pkg.go.dev/github.com/sevlyar/box

Documentation

Overview

Package box provides generic types to reduce memory footprint and GC pressure.

Index

• type Optional
  • func None[T any]() Optional[T]
  • func Some[T any](val T) Optional[T]
  • func (opt Optional[T]) Get() T
  • func (opt Optional[T]) IsNone() bool
  • func (opt Optional[T]) IsSome() bool
  • func (opt Optional[T]) IsZero() bool
  • func (opt Optional[T]) MarshalJSON() ([]byte, error)
  • func (opt *Optional[T]) Scan(src any) error
  • func (opt *Optional[T]) UnmarshalJSON(data []byte) error
  • func (opt Optional[T]) Value() (driver.Value, error)
• type Optional2
  • func None2[T any]() Optional2[T]
  • func Some2[T any](val Optional[T]) Optional2[T]
  • func (opt2 Optional2[T]) IsZero() bool
  • func (opt2 Optional2[T]) MarshalJSON() ([]byte, error)
  • func (opt2 *Optional2[T]) UnmarshalJSON(data []byte) error

Examples

• Optional (Check)
• Optional (Compare)
• Optional (Constructor)
• Optional (Marshalling)
• Optional2 (Use)

Types

type Optional

type Optional[T any] struct {
	// contains filtered or unexported fields
}

Optional represents optional value of type T. Optional value must be Some (i.e. having a value) or None (i.e. doesn't have a value). Optional is a comparable value-type. Don't recommend to use with big or complex types. Zero value of Optional is None.

Optional implements sql.Scanner and driver.Valuer interfaces. To database value conversion works, T should be one of the types accepted by driver.Value or implements the interfaces. None in database presented as NULL.

Optional implements (un)marshalling from/to JSON. None value presented as null.

Example (Check)

Get method allows you to get the underlying value, but checks whether the value is present and panics if it is not. So you should protect the Get method call with check the value is Some.

list := []Optional[int]{
	Some(1),
	None[int](),
	Some(2),
}

for _, opt := range list {
	if opt.IsSome() {
		v := opt.Get()
		fmt.Println(v)
	}
}

Output:
1
2

Example (Compare)

Optional is a comparable value-type.

fmt.Println(
	Some("a") == Some("a"),
	None[string]() == None[string](),
	Some("a") != Some("b"),
	Some("a") != None[string](),
)

Output:
true true true true

Example (Constructor)

Zero value of Optional type is None. Use Some and None functions to construct value of Optional type.

var none1 Optional[string]
none2 := None[string]()
some := Some("value")

fmt.Println(
	none1.IsNone(),
	none2.IsNone(),
	some.IsSome(),
)

Output:
true true true

Example (Marshalling)

None presented in JSON as null. Use annotation `json:",omitzero"` to omit fields with None value from the encoding.

type User struct {
	FirstName  string
	LastName   string
	MiddleName Optional[string] `json:",omitzero"`
	Age        Optional[int]
}

u := User{
	FirstName: "John",
	LastName:  "Doe",
}

b, _ := json.MarshalIndent(&u, "", "  ")

fmt.Println(string(b))

Output:
{
  "FirstName": "John",
  "LastName": "Doe",
  "Age": null
}

func None

func None[T any]() Optional[T]

None returns None value of Optional. It means no value.

func Some

func Some[T any](val T) Optional[T]

Some returns Optional with the given value.

func (Optional[T]) Get

func (opt Optional[T]) Get() T

Get returns underlying value if Optional is Some. Panics in case Optional is None.

func (Optional[T]) IsNone

func (opt Optional[T]) IsNone() bool

IsNone returns true if the Optional value is None.

func (Optional[T]) IsSome

func (opt Optional[T]) IsSome() bool

IsSome returns true if the Optional value is Some.

func (Optional[T]) IsZero

func (opt Optional[T]) IsZero() bool

func (Optional[T]) MarshalJSON

func (opt Optional[T]) MarshalJSON() ([]byte, error)

func (*Optional[T]) Scan

func (opt *Optional[T]) Scan(src any) error

func (*Optional[T]) UnmarshalJSON

func (opt *Optional[T]) UnmarshalJSON(data []byte) error

func (Optional[T]) Value

func (opt Optional[T]) Value() (driver.Value, error)

type Optional2

type Optional2[T any] struct {
	Optional[Optional[T]]
}

Optional2 presents twice optional value: Optional[Optional[T]].

Marshalling of Optional2 type to JSON is decorated. None2 value can't marshalled to JSON directly. Calling of marshalling method for None2 value will cause panic. So fields of type Optional2 should be annotated by `json:",omitzero"` to omit from the encoding when value is None2.

Example (Use)

Use Optional2 type to work with twice optional values, when you need to build a modifying form of object with optional fields.

var form struct {
	A Optional2[string]
	B Optional2[string]
	C Optional2[string]
}

input := `
	{
		"A": "str",
		"B": null
	}`

_ = json.Unmarshal([]byte(input), &form)

fmt.Println(
	form.A == Some2(Some("str")),
	form.B == Some2(None[string]()),
	form.C == None2[string](),
)

Output:
true true true

func None2

func None2[T any]() Optional2[T]

func Some2

func Some2[T any](val Optional[T]) Optional2[T]

func (Optional2[T]) IsZero

func (opt2 Optional2[T]) IsZero() bool

func (Optional2[T]) MarshalJSON

func (opt2 Optional2[T]) MarshalJSON() ([]byte, error)

func (*Optional2[T]) UnmarshalJSON

func (opt2 *Optional2[T]) UnmarshalJSON(data []byte) error