README
¶
nulls
This package uses the principle of NULL-types from the sql-package. However, it also adds JSON (un)marshalling
functionality while supporting NULL-values.
It's based on the idea of gobuffalo/nulls, but uses native (un)marshalling
functionality of the json-package.
Installation
In order to use this package, run:
go get github.com/lefinal/nulls
Predefined Datatypes
bool(nulls.Bool)[]byte(nulls.ByteSlice)float32(nulls.Float32)float64(nulls.Float64)int(nulls.Int)int16(nulls.Int16)int32(nulls.Int32)int64(nulls.Int64)json.RawMessage(nulls.JSONRawMessage)string(nulls.String)time.Time(nulls.Time)
Support for Generics
Any datatype implementing the required interface can be used as Nullable offering the same functionality as predefined
ones.
If no SQL-support is required, you can also use JSONNullable.
Usage
All datatype feature a value and Valid-field. The latter one is false when a NULL-value is represented. Otherwise,
the actual value is found in the value-field. Constructors for creating non-NULL-values are available in the form of for
example NewString(str). As the zero-value for the Valid-field is false, you do not need to create NULL-values
explicitly.
Documentation
¶
Overview ¶
Package nulls provides nullable types like the ones from sql package. However, (un)marshalling support is available as well. Keep in mind, that NULL-values and "undefined"-values (JS-style) are treated the same.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Bool ¶
type Bool struct {
// Bool is the actual boolean value when Valid.
Bool bool `exhaustruct:"optional"`
// Valid when no NULL-value is represented.
Valid bool
}
Bool holds a nullable boolean value.
func (Bool) MarshalJSON ¶
MarshalJSON marshals the Bool. If not valid, a NULL-value is returned.
func (*Bool) UnmarshalJSON ¶
UnmarshalJSON as boolean or sets Valid to false if null.
type ByteSlice ¶
type ByteSlice struct {
// ByteSlice is the actual byte slice when Valid.
ByteSlice []byte `exhaustruct:"optional"`
// Valid when no NULL-value is represented.
Valid bool
}
ByteSlice holds a nullable byte slice.
func NewByteSlice ¶
NewByteSlice returns a valid ByteSlice with the given value.
func (ByteSlice) MarshalJSON ¶
MarshalJSON marshals the ByteSlice. If not valid, a NULL-value is returned.
func (*ByteSlice) UnmarshalJSON ¶
UnmarshalJSON as byte slice or sets Valid to false if null.
type Float32 ¶
type Float32 struct {
// Float32 is the actual value when Valid.
Float32 float32 `exhaustruct:"optional"`
// Valid when no NULL-value is represented.
Valid bool
}
Float32 holds a nullable float32.
func NewFloat32 ¶
NewFloat32 returns a valid Float32 with the given value.
func (Float32) MarshalJSON ¶
MarshalJSON marshals the float32. If not valid, a NULL-value is returned.
func (*Float32) UnmarshalJSON ¶
UnmarshalJSON as float32 or sets Valid to false if null.
type Float64 ¶
type Float64 struct {
// Float64 is the actual value when Valid.
Float64 float64 `exhaustruct:"optional"`
// Valid when no NULL-value is represented.
Valid bool
}
Float64 holds a nullable float64.
func NewFloat64 ¶
NewFloat64 returns a valid Float64 with the given value.
func (Float64) MarshalJSON ¶
MarshalJSON marshals the float64. If not valid, a NULL-value is returned.
func (*Float64) UnmarshalJSON ¶
UnmarshalJSON as float64 or sets Valid to false if null.
type Int ¶
type Int struct {
// Int is the actual value when Valid.
Int int `exhaustruct:"optional"`
// Valid when no NULL-value is represented.
Valid bool
}
Int holds a nullable int.
func (Int) MarshalJSON ¶
MarshalJSON marshals the int. If not valid, a NULL-value is returned.
func (*Int) UnmarshalJSON ¶
UnmarshalJSON as int or sets Valid to false if null.
type Int16 ¶
type Int16 struct {
// Int16 is the actual value when Valid.
Int16 int16 `exhaustruct:"optional"`
// Valid when no NULL-value is represented.
Valid bool
}
Int16 holds a nullable int16.
func (Int16) MarshalJSON ¶
MarshalJSON marshals the int. If not valid, a NULL-value is returned.
func (*Int16) UnmarshalJSON ¶
UnmarshalJSON as int or sets Valid to false if null.
type Int32 ¶
type Int32 struct {
// Int32 is the actual value when Valid.
Int32 int32 `exhaustruct:"optional"`
// Valid when no NULL-value is represented.
Valid bool
}
Int32 holds a nullable int32.
func (Int32) MarshalJSON ¶
MarshalJSON marshals the int. If not valid, a NULL-value is returned.
func (*Int32) UnmarshalJSON ¶
UnmarshalJSON as int or sets Valid to false if null.
type Int64 ¶
type Int64 struct {
// Int64 is the actual value when Valid.
Int64 int64 `exhaustruct:"optional"`
// Valid when no NULL-value is represented.
Valid bool
}
Int64 holds a nullable int64.
func (Int64) MarshalJSON ¶
MarshalJSON marshals the int. If not valid, a NULL-value is returned.
func (*Int64) UnmarshalJSON ¶
UnmarshalJSON as int or sets Valid to false if null.
type JSONNullable ¶ added in v1.6.0
type JSONNullable[T any] struct { // V is the actual value when Valid. V T `exhaustruct:"optional"` // Valid describes whether the JSONNullable does not hold a NULL value. Valid bool }
JSONNullable holds a nullable value. Keep in mind, that T must be (un)marshallable. However, it cannot be used as sql.Scanner or driver.Valuer.
func NewJSONNullable ¶ added in v1.6.0
func NewJSONNullable[T any](v T) JSONNullable[T]
NewJSONNullable creates a new valid JSONNullable with the given value.
func (JSONNullable[T]) MarshalJSON ¶ added in v1.6.0
func (n JSONNullable[T]) MarshalJSON() ([]byte, error)
MarshalJSON as value. If not vot valid, a NULL-value is returned.
func (*JSONNullable[T]) Scan ¶ added in v1.6.0
func (n *JSONNullable[T]) Scan(src any) error
Scan to value or not valid if nil.
func (*JSONNullable[T]) UnmarshalJSON ¶ added in v1.6.0
func (n *JSONNullable[T]) UnmarshalJSON(data []byte) error
UnmarshalJSON as value ro sets Valid o false if null.
type JSONRawMessage ¶
type JSONRawMessage struct {
// RawMessage is the actual json.RawMessage when Valid.
RawMessage json.RawMessage `exhaustruct:"optional"`
// Valid when no NULL-value is represented.
Valid bool
}
JSONRawMessage holds a json.RawMessage. Keep in mind, that the JSON NULL value will be represented with Valid being false.
func NewJSONRawMessage ¶
func NewJSONRawMessage(raw json.RawMessage) JSONRawMessage
NewJSONRawMessage returns a valid JSONRawMessage with the given value.
func (JSONRawMessage) MarshalJSON ¶
func (rm JSONRawMessage) MarshalJSON() ([]byte, error)
MarshalJSON marshals the RawMessage. If not valid, a NULL-value is returned.
func (*JSONRawMessage) Scan ¶
func (rm *JSONRawMessage) Scan(src any) error
Scan to json.RawMessage value or not valid if nil.
func (*JSONRawMessage) UnmarshalJSON ¶
func (rm *JSONRawMessage) UnmarshalJSON(data []byte) error
UnmarshalJSON as json.RawMessage or sets Valid to false if empty.
type Nullable ¶
type Nullable[T NullableValue] struct { // V is the actual value when Valid. V T `exhaustruct:"optional"` // Valid describes whether the Nullable does not hold a NULL value. Valid bool }
Nullable holds a nullable value.
func NewNullable ¶
func NewNullable[T NullableValue](v T) Nullable[T]
NewNullable creates a new valid Nullable with the given value.
func (Nullable[T]) MarshalJSON ¶
MarshalJSON as value. If not vot valid, a NULL-value is returned.
func (*Nullable[T]) UnmarshalJSON ¶
UnmarshalJSON as value ro sets Valid o false if null.
type NullableInto ¶ added in v1.7.0
type NullableInto[T NullableIntoValue[T]] struct { // V is the actual value when Valid. V T `exhaustruct:"optional"` // Valid describes whether the Nullable does not hold a NULL value. Valid bool }
NullableInto holds a nullable value that satisfies NullableIntoValue. This can be used instead of Nullable if the value should not be treated as pointer. It then provides the NullableIntoValue.ScanInto method that scans into a passed reference.
func NewNullableInto ¶ added in v1.7.0
func NewNullableInto[T NullableIntoValue[T]](v T) NullableInto[T]
NewNullableInto creates a new valid NullableInto with the given value.
func (NullableInto[T]) MarshalJSON ¶ added in v1.7.0
func (n NullableInto[T]) MarshalJSON() ([]byte, error)
MarshalJSON as value. If not vot valid, a NULL-value is returned.
func (*NullableInto[T]) Scan ¶ added in v1.7.0
func (n *NullableInto[T]) Scan(src any) error
Scan to value or not valid if nil.
func (*NullableInto[T]) UnmarshalJSON ¶ added in v1.7.0
func (n *NullableInto[T]) UnmarshalJSON(data []byte) error
UnmarshalJSON as value ro sets Valid o false if null.
type NullableIntoValue ¶ added in v1.7.0
NullableIntoValue are the requirements for values used in NullableInto as they need to implement at least driver.Valuer, and a ScanInto method.
type NullableValue ¶
NullableValue are the requirements for values used in Nullable as they need to implement at least sql.Scanner and driver.Valuer.
type Optional ¶ added in v1.9.0
type Optional[T any] struct { // V is the actual value when Valid. V T `exhaustruct:"optional"` // Valid describes whether the Nullable does not hold a NULL value. Valid bool }
Optional holds a nullable value. This can be used instead of Nullable or NullableInto if database support is not required.
func NewOptional ¶ added in v1.9.0
NewOptional creates a new valid Optional with the given value.
func (Optional[T]) MarshalJSON ¶ added in v1.9.0
MarshalJSON as value. If not vot valid, a NULL-value is returned.
func (*Optional[T]) Scan ¶ added in v1.9.0
Scan returns an error as this is currently not supported on Optional. Use Nullable or NullableInto instead.
func (*Optional[T]) UnmarshalJSON ¶ added in v1.9.0
UnmarshalJSON as value or sets Valid or false if null.
type String ¶
type String struct {
// String is the actual value when Valid.
String string `exhaustruct:"optional"`
// Valid when no NULL-value is represented.
Valid bool
}
String holds a nullable string.
func (String) MarshalJSON ¶
MarshalJSON marshals the string. If not valid, a NULL-value is returned.
func (*String) UnmarshalJSON ¶
UnmarshalJSON as string or sets Valid to false if null.
type Time ¶
type Time struct {
// Time is the actual value when Valid.
Time time.Time `exhaustruct:"optional"`
// Valid when no NULL-value is represented.
Valid bool
}
Time holds a nullable time.Time.
func (Time) MarshalJSON ¶
MarshalJSON marshals the time.Time. If not valid, a NULL-value is returned.
func (*Time) UnmarshalJSON ¶
UnmarshalJSON as time.Time or sets Valid to false if null.
Source Files