Documentation
¶
Overview ¶
Package null exposes a Val(ue) type that wraps a regular value with the ability to be 'omitted' or 'unset'.
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]) IsSet() bool
- func (v Val[T]) IsUnset() 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]) 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]) UnmarshalBinary(b []byte) error
- 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 )
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 "unset" or "set". Its zero value is usfel and initially "unset".
func FromCond ¶
FromCond conditionally creates a 'set' value if the bool is true, else it will return an omitted value.
func FromPtr ¶
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 (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.
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 ¶
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 ¶
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 ¶
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 ¶
Scan implements the sql.Scanner interface. If the wrapped type implements sql.Scanner then it will call that.
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. Notably will fail to unmarshal if given a null.
func (*Val[T]) UnmarshalText ¶
UnmarshalText implements encoding.TextUnmarshaler.
func (Val[T]) Value ¶
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
Source Files