Documentation
¶
Overview ¶
Package null exposes a Val(ue) type that wraps a regular value with the ability to be 'null'.
Index ¶
- Constants
- func Equal[T comparable](a, b Val[T]) bool
- type Val
- 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]) IsNull() bool
- func (v Val[T]) IsSet() bool
- func (v Val[T]) Map(fn func(T) T) Val[T]
- func (v Val[T]) MarshalBinary() ([]byte, error)
- func (v Val[T]) MarshalJSON() ([]byte, error)
- func (v Val[T]) MarshalText() ([]byte, error)
- func (v Val[T]) MustGet() T
- func (v *Val[T]) Null()
- func (v Val[T]) Or(other Val[T]) Val[T]
- func (v Val[T]) Ptr() *T
- func (v *Val[T]) Scan(value any) error
- func (v *Val[T]) Set(val T)
- func (v *Val[T]) SetPtr(val *T)
- func (v Val[T]) State() state
- func (v *Val[T]) UnmarshalBinary(b []byte) error
- func (v *Val[T]) UnmarshalJSON(data []byte) error
- func (v *Val[T]) UnmarshalText(text []byte) error
- func (v Val[T]) Value() (driver.Value, error)
Constants ¶
const ( StateNull state = 0 StateSet state = 1 )
Variables ¶
This section is empty.
Functions ¶
func Equal ¶
func Equal[T comparable](a, b Val[T]) bool
Equal compares two nullable values and returns true if they are equal.
Types ¶
type Val ¶
type Val[T any] struct { // contains filtered or unexported fields }
Val allows representing a value with a state of "null" or "set". Its zero value is usfel and initially "null".
func FromCond ¶
FromCond conditionally creates a 'set' value if the bool is true, else it will return a null value.
func FromPtr ¶
FromPtr creates a value from a pointer, if the pointer is null it will be 'null', if it has a value the deferenced value is stored.
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]) Map ¶
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]) MarshalBinary ¶
MarshalBinary tries to encode the value in binary. If it finds type that implements encoding.BinaryMarshaler it will use that, it will fallback to encoding.TextMarshaler if that is implemented, and failing that it will attempt to do some reflect to convert between the types to hit common cases like Go primitives.
func (Val[T]) MarshalJSON ¶
MarshalJSON implements json.Marshaler.
func (Val[T]) MarshalText ¶
MarshalText implements encoding.TextMarshaler.
This package emits an empty string for null values as its way of compactly storing the state. This probably isn't canonically useful but it's hard to agree on a better way because various implementations of serialization may use a different representation of null (such as nil).
Further to that it would prevent us from just encoding the string "null" since null.From("null") would be both valid and useful.
It may in the future be more useful to rely on a []byte("null") as a sentinel value, but for now this package will assume that any value being consumed by null.UnmarshalText() has been created with null.MarshalText() and it therefore strives to make no gesture of compatibility with non-null.Val serialized types.
func (Val[T]) MustGet ¶
func (v Val[T]) MustGet() T
MustGet retrieves the value or panics if it's null
func (Val[T]) Or ¶
Or returns v or other depending on their states. In general set > null > unset and therefore the one with the state highest in that area will win out.
v | other | result ------------- | ------- set | _ | v null | set | other null | null | v
func (*Val[T]) Scan ¶
Scan implements the sql.Scanner interface. If the wrapped type implements sql.Scanner then it will call that.
func (*Val[T]) SetPtr ¶
func (v *Val[T]) SetPtr(val *T)
SetPtr sets the value to (value, set) if val is non-nil or (??, null) if not. The value is dereferenced before stored.
func (Val[T]) State ¶
func (v Val[T]) State() state
State retrieves the internal state, mostly useful for testing.
func (*Val[T]) UnmarshalBinary ¶
UnmarshalBinary tries to reverse the value MarshalBinary operation. See documentation there for details about supported types.
func (*Val[T]) UnmarshalJSON ¶
UnmarshalJSON implements json.Unmarshaler
func (*Val[T]) UnmarshalText ¶
UnmarshalText implements encoding.TextUnmarshaler.
It specifically does not understand the word "null" to mean anything special, as that would preclude us from encoding the string "null" as a non-null string value.
Source Files