omit

Documentation

Overview

Package null exposes a Val(ue) type that wraps a regular value with the ability to be 'omitted' or 'unset'.

Index

• Constants
• type Val
  • func From[T any](val T) Val[T]
  • func FromCond[T any](val T, ok bool) Val[T]
  • func FromPtr[T any](val *T) Val[T]
  • func Map[A any, B any](v Val[A], fn func(A) B) Val[B]
  • func (v Val[T]) Get() (T, bool)
  • func (v Val[T]) GetOr(fallback T) T
  • func (v Val[T]) GetOrZero() T
  • func (v Val[T]) IsSet() bool
  • func (v Val[T]) IsUnset() bool
  • func (v Val[T]) Map(fn func(T) T) Val[T]
  • func (v Val[T]) MarshalJSON() ([]byte, error)
  • func (v Val[T]) MarshalJSONIsZero() bool
  • func (v Val[T]) MarshalText() ([]byte, error)
  • func (v Val[T]) MustGet() T
  • func (v Val[T]) Or(other Val[T]) Val[T]
  • func (v *Val[T]) Scan(value any) error
  • func (v *Val[T]) Set(val T)
  • func (v Val[T]) State() state
  • func (v *Val[T]) UnmarshalJSON(data []byte) error
  • func (v *Val[T]) UnmarshalText(text []byte) error
  • func (v *Val[T]) Unset()
  • func (v Val[T]) Value() (driver.Value, error)

Constants

const (
	StateUnset state = 0
	StateSet   state = 1
)

Types

type Val

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

Val allows representing a value with a state of "unset" or "set". Its zero value is usfel and initially "unset".

func From

func From[T any](val T) Val[T]

From a value which is considered 'set'

func FromCond

func FromCond[T any](val T, ok bool) Val[T]

FromCond conditionally creates a 'set' value if the bool is true, else it will return an omitted value.

func FromPtr

func FromPtr[T any](val *T) Val[T]

FromPtr creates a value from a pointer, if the pointer is null it will be 'unset', if it has a value the deferenced value is stored.

func Map

func Map[A any, B any](v Val[A], fn func(A) B) Val[B]

Map transforms the value inside if it is set, else it returns value of the same state.

func (Val[T]) Get

func (v Val[T]) Get() (T, bool)

Get the underlying value, if one exists.

func (Val[T]) GetOr

func (v Val[T]) GetOr(fallback T) T

GetOr gets the value or returns a fallback if the value does not exist.

func (Val[T]) GetOrZero

func (v Val[T]) GetOrZero() T

GetOrZero returns the zero value for T if the value was omitted.

func (Val[T]) IsSet

func (v Val[T]) IsSet() bool

IsSet returns true if v contains a non-null value

func (Val[T]) IsUnset

func (v Val[T]) IsUnset() bool

IsUnset returns true if v contains no value

func (Val[T]) Map

func (v Val[T]) Map(fn func(T) T) Val[T]

Map transforms the value inside if it is set, else it returns a value of the same state.

Until a later Go version adds type parameters to methods, it is not possible to map to a different type. See the non-method function Map if you need another type.

func (Val[T]) MarshalJSON

func (v Val[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

Note that this type cannot possibly work with the stdlib json package due to there being no way for the json package to omit a value based on its internals.

That's to say even if you have an `omitempty` tag with this type, it will still show up in outputs as {"val": null} because this functionality is not supported.

For a package that works well with this package see github.com/aarondl/json.

func (Val[T]) MarshalJSONIsZero

func (v Val[T]) MarshalJSONIsZero() bool

MarshalJSONIsZero returns true if this value should be omitted by the json marshaler.

There is a special case in which we omit the value even if the value is `set` which is when the value is going to write out `nil` (pointers, maps and slices that are nil) when marshaled.

The reason this is important is if we marshal(From[[]int](nil)) with the special json fork, it will emit `null` without this override. This is bad because this same package even with the json fork cannot consume a null.

In order to achieve symmetry in encoding/decoding we'll quietly omit nil maps, slices, and ptrs as it was likely a mistake to try to .From(nil) for this type of value anyway.

func (Val[T]) MarshalText

func (v Val[T]) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (Val[T]) MustGet

func (v Val[T]) MustGet() T

MustGet retrieves the value or panics if it's null

func (Val[T]) Or

func (v Val[T]) Or(other Val[T]) Val[T]

Or returns v or other depending on their states. In general set > unset and therefore the one with the state highest in that area will win out.

v     | other | result
------------- | -------
set   | _     | v
unset | set   | other
unset | unset | v

func (*Val[T]) Scan

func (v *Val[T]) Scan(value any) error

Scan implements the sql.Scanner interface. If the wrapped type implements sql.Scanner then it will call that.

func (*Val[T]) Set

func (v *Val[T]) Set(val T)

Set the value (and the state to 'set')

func (Val[T]) State

func (v Val[T]) State() state

State retrieves the internal state, mostly useful for testing.

func (*Val[T]) UnmarshalJSON

func (v *Val[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler. Notably will fail to unmarshal if given a null.

func (*Val[T]) UnmarshalText

func (v *Val[T]) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

func (*Val[T]) Unset

func (v *Val[T]) Unset()

Unset the value (state is set to 'unset')

func (Val[T]) Value

func (v Val[T]) Value() (driver.Value, error)

Value implements the driver.Valuer interface. If the underlying type implements the driver.Valuer it will call that (when not unset). Go primitive types will be converted where possible.

Because sql doesn't have an analog to unset it will marshal as null in these cases.

int64
float64
bool
[]byte
string
time.Time