optional

README

Optional Go

Library for conveniently and safely dealing with optional (nullable) values.

Note: Requires Go 1.18 with generics support.

Installation

$ go get github.com/adolfo/optional-go

Usage

package main

import (
    "github.com/adolfo/optional-go"
)

Initialization with literal values

// Optional string
optStr := optional.Of("foo")

// Optional int
optInt := optional.Of(5)

// Optional float64
optFlt := optional.Of(9.99)

// Optional struct
type Thing struct {
    foo int
    bar string
}
optThing := optional.Of(Thing{42, "baz"})

Initialization with nil values

// Optional string with nil value
nilStr := optional.OfNil[string]()

// Optional int with nil value
nilInt := optional.OfNil[int]()

// Nil struct
nilThg := optional.OfNil[Thing]()

Alternative initialization with nil values

// Optional int with nil value
var nilInt optional.Value[int]

// Optional string with nil value
nilStr := optional.Value[string]{}

Updating optional values

o := optional.OfNil[int]

// Set new value
o.Set(42)

// Clearing value and resetting to nil
o.SetNil()

// Set invalid value
o.Set("fred") // compiler error; type is Optional.Value[int]

Getting optional values

o := optional.Of(42)

// Safely get underlying optional value
if ok, val := o.Get(); ok {
    fmt.Println(val) // prints 42
}

// Unsafely get value
fmt.Println(o.MustGet()) // prints 42
o.SetNil()
fmt.Println(o.MustGet()) // panics

Get value with default

o := optional.Of("foo")

fmt.Println(o.GetOr("fred")) // prints "foo"

o.SetNil()
fmt.Println(o.GetOr("fred")) // prints "fred"

Checking for value

if o.HasValue() {
    fmt.Println("has value")
}

if o.IsNil() {
    fmt.Println("value is nil")
}

JSON Marshaling & Unmarshaling

type Person struct {
    Name optional.Value[string] `json:"name"`
    Age  optional.Value[int]    `json:"age"`
}

j := `{ "name": null, "age": 42 }`
p := new(Person)
json.Unmarshal([]byte(j), p)

fmt.Println("name is %s", p.Name.GetOr("Unknown"))
// prints "name is Unknown" since `name` was null

License

Released under the MIT License

Documentation

Index

• type Value
  • func Of[T any](t T) Value[T]
  • func OfNil[T any]() Value[T]
  • func (o *Value[T]) Get() (ok bool, value T)
  • func (o *Value[T]) GetOr(value T) T
  • func (o *Value[T]) HasValue() bool
  • func (o *Value[T]) IsNil() bool
  • func (o Value[T]) MarshalJSON() ([]byte, error)
  • func (o *Value[T]) MustGet() (value T)
  • func (o *Value[T]) Scan(src any) error
  • func (o *Value[T]) Set(value T)
  • func (o *Value[T]) SetNil()
  • func (o *Value[T]) UnmarshalJSON(data []byte) error
  • func (o *Value[T]) Value() (driver.Value, error)

Types

type Value

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

Value wraps an optional value of type T

func Of

func Of[T any](t T) Value[T]

Of instantiates a new optional value with value t

func OfNil

func OfNil[T any]() Value[T]

OfNil instantiates a new optional value of type T with value set to nil

func (*Value[T]) Get

func (o *Value[T]) Get() (ok bool, value T)

Get returns true if optional value is non-nil, along with the underlying value

func (*Value[T]) GetOr

func (o *Value[T]) GetOr(value T) T

GetOr returns the underlying non-nil value or the provided fallback value

func (*Value[T]) HasValue

func (o *Value[T]) HasValue() bool

HasValue returns true if the underlying value is non-nil

func (*Value[T]) IsNil

func (o *Value[T]) IsNil() bool

IsNil returns true if the underlying value is nil

func (Value[T]) MarshalJSON

func (o Value[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface

func (*Value[T]) MustGet

func (o *Value[T]) MustGet() (value T)

MustGet returns the underlying value or PANICS if value is nil

func (*Value[T]) Scan

func (o *Value[T]) Scan(src any) error

Scan implements sql.Scanner interface

func (*Value[T]) Set

func (o *Value[T]) Set(value T)

Set sets the underlying optional value to the provided non-nil value

func (*Value[T]) SetNil

func (o *Value[T]) SetNil()

SetNil sets the underlying optional value to nil

func (*Value[T]) UnmarshalJSON

func (o *Value[T]) UnmarshalJSON(data []byte) error

MarshalJSON implements json.Unmarshaler interface

func (*Value[T]) Value

func (o *Value[T]) Value() (driver.Value, error)

Value implements driver.Valuer interface