nulls

package module
v1.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 2, 2024 License: MIT Imports: 8 Imported by: 26

README

nulls

made-with-Go Go GitHub go.mod Go version GoReportCard example codecov GitHub issues GitHub code size in bytes

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

func NewUUID added in v1.5.0

func NewUUID(id uuid.UUID) uuid.NullUUID

NewUUID creates a new valid uuid.NullUUID.

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 NewBool

func NewBool(b bool) Bool

NewBool returns a valid Bool with the given value.

func (Bool) MarshalJSON

func (b Bool) MarshalJSON() ([]byte, error)

MarshalJSON marshals the Bool. If not valid, a NULL-value is returned.

func (*Bool) Scan

func (b *Bool) Scan(src any) error

Scan to boolean value or not valid if nil.

func (*Bool) UnmarshalJSON

func (b *Bool) UnmarshalJSON(data []byte) error

UnmarshalJSON as boolean or sets Valid to false if null.

func (Bool) Value

func (b Bool) Value() (driver.Value, error)

Value returns the value for satisfying the driver.Valuer interface.

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

func NewByteSlice(b []byte) ByteSlice

NewByteSlice returns a valid ByteSlice with the given value.

func (ByteSlice) MarshalJSON

func (b ByteSlice) MarshalJSON() ([]byte, error)

MarshalJSON marshals the ByteSlice. If not valid, a NULL-value is returned.

func (*ByteSlice) Scan

func (b *ByteSlice) Scan(src any) error

Scan to byte slice value or not valid if nil.

func (*ByteSlice) UnmarshalJSON

func (b *ByteSlice) UnmarshalJSON(data []byte) error

UnmarshalJSON as byte slice or sets Valid to false if null.

func (ByteSlice) Value

func (b ByteSlice) Value() (driver.Value, error)

Value returns the value for satisfying the driver.Valuer interface.

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

func NewFloat32(f float32) Float32

NewFloat32 returns a valid Float32 with the given value.

func (Float32) MarshalJSON

func (f Float32) MarshalJSON() ([]byte, error)

MarshalJSON marshals the float32. If not valid, a NULL-value is returned.

func (*Float32) Scan

func (f *Float32) Scan(src any) error

Scan to float32 value or not valid if nil.

func (*Float32) UnmarshalJSON

func (f *Float32) UnmarshalJSON(data []byte) error

UnmarshalJSON as float32 or sets Valid to false if null.

func (Float32) Value

func (f Float32) Value() (driver.Value, error)

Value returns the value for satisfying the driver.Valuer interface.

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

func NewFloat64(f float64) Float64

NewFloat64 returns a valid Float64 with the given value.

func (Float64) MarshalJSON

func (f Float64) MarshalJSON() ([]byte, error)

MarshalJSON marshals the float64. If not valid, a NULL-value is returned.

func (*Float64) Scan

func (f *Float64) Scan(src any) error

Scan to float64 value or not valid if nil.

func (*Float64) UnmarshalJSON

func (f *Float64) UnmarshalJSON(data []byte) error

UnmarshalJSON as float64 or sets Valid to false if null.

func (Float64) Value

func (f Float64) Value() (driver.Value, error)

Value returns the value for satisfying the driver.Valuer interface.

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 NewInt

func NewInt(i int) Int

NewInt returns a valid Int with the given value.

func (Int) MarshalJSON

func (i Int) MarshalJSON() ([]byte, error)

MarshalJSON marshals the int. If not valid, a NULL-value is returned.

func (*Int) Scan

func (i *Int) Scan(src any) error

Scan to int value or not valid if nil.

func (*Int) UnmarshalJSON

func (i *Int) UnmarshalJSON(data []byte) error

UnmarshalJSON as int or sets Valid to false if null.

func (Int) Value

func (i Int) Value() (driver.Value, error)

Value returns the value for satisfying the driver.Valuer interface.

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 NewInt16

func NewInt16(i int16) Int16

NewInt16 returns a valid Int16 with the given value.

func (Int16) MarshalJSON

func (i Int16) MarshalJSON() ([]byte, error)

MarshalJSON marshals the int. If not valid, a NULL-value is returned.

func (*Int16) Scan

func (i *Int16) Scan(src any) error

Scan to int value or not valid if nil.

func (*Int16) UnmarshalJSON

func (i *Int16) UnmarshalJSON(data []byte) error

UnmarshalJSON as int or sets Valid to false if null.

func (Int16) Value

func (i Int16) Value() (driver.Value, error)

Value returns the value for satisfying the driver.Valuer interface.

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 NewInt32

func NewInt32(i int32) Int32

NewInt32 returns a valid Int32 with the given value.

func (Int32) MarshalJSON

func (i Int32) MarshalJSON() ([]byte, error)

MarshalJSON marshals the int. If not valid, a NULL-value is returned.

func (*Int32) Scan

func (i *Int32) Scan(src any) error

Scan to int value or not valid if nil.

func (*Int32) UnmarshalJSON

func (i *Int32) UnmarshalJSON(data []byte) error

UnmarshalJSON as int or sets Valid to false if null.

func (Int32) Value

func (i Int32) Value() (driver.Value, error)

Value returns the value for satisfying the driver.Valuer interface.

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 NewInt64

func NewInt64(i int64) Int64

NewInt64 returns a valid Int64 with the given value.

func (Int64) MarshalJSON

func (i Int64) MarshalJSON() ([]byte, error)

MarshalJSON marshals the int. If not valid, a NULL-value is returned.

func (*Int64) Scan

func (i *Int64) Scan(src any) error

Scan to int value or not valid if nil.

func (*Int64) UnmarshalJSON

func (i *Int64) UnmarshalJSON(data []byte) error

UnmarshalJSON as int or sets Valid to false if null.

func (Int64) Value

func (i Int64) Value() (driver.Value, error)

Value returns the value for satisfying the driver.Valuer interface.

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.

func (JSONNullable[T]) Value added in v1.6.0

func (n JSONNullable[T]) Value() (driver.Value, error)

Value returns the value for satisfying the driver.Valuer interface.

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.

func (JSONRawMessage) Value

func (rm JSONRawMessage) Value() (driver.Value, error)

Value returns the value for satisfying the driver.Valuer interface.

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

func (n Nullable[T]) MarshalJSON() ([]byte, error)

MarshalJSON as value. If not vot valid, a NULL-value is returned.

func (*Nullable[T]) Scan

func (n *Nullable[T]) Scan(src any) error

Scan to value or not valid if nil.

func (*Nullable[T]) UnmarshalJSON

func (n *Nullable[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON as value ro sets Valid o false if null.

func (Nullable[T]) Value

func (n Nullable[T]) Value() (driver.Value, error)

Value returns the value for satisfying the driver.Valuer interface.

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.

func (NullableInto[T]) Value added in v1.7.0

func (n NullableInto[T]) Value() (driver.Value, error)

Value returns the value for satisfying the driver.Valuer interface.

type NullableIntoValue added in v1.7.0

type NullableIntoValue[T any] interface {
	ScanInto(src any, dst *T) error
	driver.Valuer
}

NullableIntoValue are the requirements for values used in NullableInto as they need to implement at least driver.Valuer, and a ScanInto method.

type NullableValue

type NullableValue interface {
	sql.Scanner
	driver.Valuer
}

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

func NewOptional[T any](v T) Optional[T]

NewOptional creates a new valid Optional with the given value.

func (Optional[T]) MarshalJSON added in v1.9.0

func (n Optional[T]) MarshalJSON() ([]byte, error)

MarshalJSON as value. If not vot valid, a NULL-value is returned.

func (*Optional[T]) Scan added in v1.9.0

func (n *Optional[T]) Scan(_ any) error

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

func (n *Optional[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON as value or sets Valid or false if null.

func (Optional[T]) Value added in v1.9.0

func (n Optional[T]) Value() (driver.Value, error)

Value returns an error as this is currently not supported on Optional. Use Nullable or NullableInto instead.

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 NewString

func NewString(s string) String

NewString returns a valid String with the given value.

func (String) MarshalJSON

func (s String) MarshalJSON() ([]byte, error)

MarshalJSON marshals the string. If not valid, a NULL-value is returned.

func (*String) Scan

func (s *String) Scan(src any) error

Scan to string value or not valid if nil.

func (*String) UnmarshalJSON

func (s *String) UnmarshalJSON(data []byte) error

UnmarshalJSON as string or sets Valid to false if null.

func (String) Value

func (s String) Value() (driver.Value, error)

Value returns the value for satisfying the driver.Valuer interface.

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 NewTime

func NewTime(t time.Time) Time

NewTime returns a valid Time with the given value.

func (Time) MarshalJSON

func (t Time) MarshalJSON() ([]byte, error)

MarshalJSON marshals the time.Time. If not valid, a NULL-value is returned.

func (*Time) Scan

func (t *Time) Scan(src any) error

Scan to time.Time value or not valid if nil.

func (Time) UTC added in v1.3.0

func (t Time) UTC() Time

UTC returns the UTC time.

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(data []byte) error

UnmarshalJSON as time.Time or sets Valid to false if null.

func (Time) Value

func (t Time) Value() (driver.Value, error)

Value returns the value for satisfying the driver.Valuer interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL