Documentation
¶
Overview ¶
Package omitnull exposes a Val(ue) type that wraps a regular value with the ability to be 'omitted/unset' or '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]) GetNull() (null.Val[T], bool)
- func (v Val[T]) GetOmit() (omit.Val[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]) 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]) MustGetNull() null.Val[T]
- func (v Val[T]) MustGetOmit() omit.Val[T]
- func (v Val[T]) MustPtr() *T
- func (v *Val[T]) Null()
- 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]) 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]) Unset()
- func (v Val[T]) Value() (driver.Value, error)
Constants ¶
const ( StateUnset state = 0 StateNull state = 1 StateSet state = 2 )
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", "null", or "set". Its zero value is usfel and initially "unset".
func FromNull ¶
FromNull constructs a value from a nullable value. This is a lossless conversion and cannot fail.
func FromOmit ¶
FromOmit constructs a value from a omittable value. This is a lossless conversion and cannot fail.
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 or null.
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.
Omitnull will add a prepend a single byte to the value's binary encoding track the state (0 for null, 1 for set) when it is not omitted.
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.
func (Val[T]) MarshalText ¶
MarshalText implements encoding.TextMarshaler. If the value is omitted it will return nil (empty string), if the value is null it will return '0' as a representation, and if the value is set it will prepend '1' to the value's text representation.
That's also to say that there is no compatibility with the outside world. A value that is Unmarshal'd by this package must have been produced by this package to encode the text properly.
func (Val[T]) MustGet ¶
func (v Val[T]) MustGet() T
MustGet retrieves the value or panics if it's null or omitted
func (Val[T]) MustGetNull ¶
MustGetNull retrieves the value as a nullable value or panics if it's omitted
func (Val[T]) MustGetOmit ¶
MustGetOmit retrieves the value as an omittable value or panics if it's null
func (Val[T]) MustPtr ¶
func (v Val[T]) MustPtr() *T
MustPtr returns a pointer to the value, or nil if null, panics if it is not one of (null, set).
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 | _ | v unset | set | other unset | null | 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]) 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.
Source Files