optional

README

optional

Optional ("nullable") value library for Go

Requirements

• Go 1.18 or newer

Installation

go get github.com/heucuva/optional

How to use

Import this library into your code:

import "github.com/heucuva/optional"

Then, you can easily add an optional value like so:

var testValue optional.Value[string]

func Example() {
    // testValue should be 'nil', as it's initially unset
    // the expected result here is that `value` is "" and `set` is false
    value, set := testValue.Get()
    
    // this will set the testValue variable to a new value
    // NOTE: setting an optional.Value to nil does not cause it to return `set` as false
    //       the preferred behavior for clearing a Value is to call Reset, as shown below
    testValue.Set("Hello world!")

    // testValue should now be set
    // the expected result here is that `value is "Hello world!" and `set` is true
    value, set = testValue.Get()

    // this will unset the testValue variable
    // essentially setting the value to 'nil'
    // do not confuse this with setting a Value to actual `nil`
    testValue.Reset()

    // testValue should be once again be 'nil', as it's been unset by the Reset function
    // the expected result here is that `value` is "" and `set` is false
    value, set := testValue.Get()
}

Documentation

Index

• type Value
  • func Coalesce[T any](options ...Value[T]) Value[T]
  • func CoalesceZero[T any](options ...Value[T]) Value[T]
  • func NewValue[T any](value T) Value[T]
  • func (o Value[T]) Get() (T, bool)
  • func (o Value[T]) IsSet() bool
  • func (o Value[T]) IsZero() bool
  • func (o Value[T]) MarshalJSON() ([]byte, error)
  • func (o Value[T]) MarshalYAML() (T, error)
  • func (o *Value[T]) Reset()
  • func (o *Value[T]) Set(value T)
  • func (o *Value[T]) UnmarshalJSON(data []byte) error
  • func (o *Value[T]) UnmarshalYAML(unmarshal func(any) error) error

Types

type Value

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

Value is an optional value

func Coalesce

func Coalesce[T any](options ...Value[T]) Value[T]

Coalesce will return the first optional value that is set (or returns an unset optional value if none is found).

func CoalesceZero

func CoalesceZero[T any](options ...Value[T]) Value[T]

Coalesce will return the first optional value that is set and not "zero" (or returns an unset optional value if none is found).

func NewValue

func NewValue[T any](value T) Value[T]

NewValue constructs a Value structure with a value already set into it

func (Value[T]) Get

func (o Value[T]) Get() (T, bool)

Get returns the value and its set flag

func (Value[T]) IsSet

func (o Value[T]) IsSet() bool

func (Value[T]) IsZero

func (o Value[T]) IsZero() bool

IsZero is used by the yaml marshaller to determine "zero"-ness for omitempty we're using it for the `set` bool

func (Value[T]) MarshalJSON

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

MarshalJSON outputs the value of the Value, if `set` is set. otherwise, it returns nil

func (Value[T]) MarshalYAML

func (o Value[T]) MarshalYAML() (T, error)

MarshalYAML outputs the value of the Value, if `set` is set. otherwise, it returns nil

func (*Value[T]) Reset

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

Reset clears the memory on the value

func (*Value[T]) Set

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

Set updates the value and sets the set flag

func (*Value[T]) UnmarshalJSON

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

UnmarshalJSON unmarshals a value out of json and safely into our struct

func (*Value[T]) UnmarshalYAML

func (o *Value[T]) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML unmarshals a value out of yaml and safely into our struct