README
¶
null 
This module provides (yet another) alternative to dealing with null values in databases or JSON. Other approaches like the Null types in the standard library use structs to ensure you can differentiate between zero values an null values. If that isn't a meaningful distinction in your app, then this module might be a simpler approach for you because it uses primitive values and treats zero values as null values.
If you don't need to define your own types, you can use one of the following predefined types. If you scan a SQL NULL
or unmarshal a JSON null, you will get the zero value. If you write the zero value to SQL you will get NULL and if
you marshal the zero value to JSON, you will get null.
| Zero Value | |
|---|---|
null.Int |
int(0) |
null.Int64 |
int64(0) |
null.String |
"" |
null.Map[V] |
map[string]V{} |
null.JSON |
[]byte("null") |
If you want to define a custom integer type, you need to define the following methods:
import "github.com/nyaruka/null/v2"
type CustomID int64 // or int etc
const NullCustomID = CustomID(0)
func (i *CustomID) Scan(value any) error { return null.ScanInt(value, i) }
func (i CustomID) Value() (driver.Value, error) { return null.IntValue(i) }
func (i *CustomID) UnmarshalJSON(b []byte) error { return null.UnmarshalInt(b, i) }
func (i CustomID) MarshalJSON() ([]byte, error) { return null.MarshalInt(i) }
And likewise for a custom string type:
import "github.com/nyaruka/null/v2"
type CustomString string
const NullCustomString = CustomString("")
func (s *CustomString) Scan(value any) error { return null.ScanString(value, s) }
func (s CustomString) Value() (driver.Value, error) { return null.StringValue(s) }
func (s CustomString) MarshalJSON() ([]byte, error) { return null.MarshalString(s) }
func (s *CustomString) UnmarshalJSON(b []byte) error { return null.UnmarshalString(b, s) }
If you want to create a type which can scan from NULL, but always writes as the zero value, just don't define the Value
method. This can be useful when changing a database column to be non-NULL.
Documentation
¶
Index ¶
- Constants
- Variables
- func IntValue[T constraints.Signed](i T) (driver.Value, error)
- func JSONValue(j JSON) (driver.Value, error)
- func MapValue[V any](m Map[V]) (driver.Value, error)
- func MarshalInt[T constraints.Signed](i T) ([]byte, error)
- func MarshalJSON(j JSON) ([]byte, error)
- func MarshalMap[V any](m Map[V]) ([]byte, error)
- func MarshalString[T ~string](s T) ([]byte, error)
- func ScanInt[T constraints.Signed](value any, i *T) error
- func ScanJSON(value any, j *JSON) error
- func ScanMap[V any](value any, m *Map[V]) error
- func ScanString[T ~string](value any, s *T) error
- func StringValue[T ~string](s T) (driver.Value, error)
- func UnmarshalInt[T constraints.Signed](b []byte, i *T) error
- func UnmarshalJSON(data []byte, j *JSON) error
- func UnmarshalMap[V any](data []byte, m *Map[V]) error
- func UnmarshalString[T ~string](b []byte, s *T) error
- type Int
- type Int64
- type JSON
- type Map
- type String
Constants ¶
const NullInt = Int(0)
NullInt is our constant for an Int value that will be written as null
const NullInt64 = Int64(0)
NullInt64 is our constant for an Int64 value that will be written as null
const NullString = String("")
NullString is our constant for an String value that will be written as null
Variables ¶
var NullJSON = JSON(`null`)
Functions ¶
func IntValue ¶
func IntValue[T constraints.Signed](i T) (driver.Value, error)
IntValue converts an int type value to NULL if it is zero.
func MarshalInt ¶
func MarshalInt[T constraints.Signed](i T) ([]byte, error)
MarshalJSON marshals an int type to JSON, using null for zero.
func MarshalJSON ¶
func MarshalMap ¶
MarshalMap marshals a map, returning null for an empty map.
func MarshalString ¶
MarshalJSON marshals a string type to JSON, using null for empty strings.
func ScanInt ¶
func ScanInt[T constraints.Signed](value any, i *T) error
ScanInt scans a nullable INT into an int type, using zero for NULL.
func ScanString ¶
ScanString scans a nullable CHAR/TEXT into a string type, using empty string for NULL.
func StringValue ¶
StringValue converts a string type value to NULL if it is empty
func UnmarshalInt ¶
func UnmarshalInt[T constraints.Signed](b []byte, i *T) error
UnmarshalInt unmarshals an int type from JSON, using zero for null.
func UnmarshalJSON ¶
func UnmarshalString ¶
UnmarshalString unmarshals a string type from JSON, using empty string for null.
Types ¶
type Int ¶
type Int int
Int is an int that will write as null when it is zero both to databases and JSON null values when unmarshalled or scanned from a DB will result in a zero value.
func (Int) MarshalJSON ¶
MarshalJSON implements the Marshaller interface
func (*Int) UnmarshalJSON ¶
UnmarshalJSON implements the Unmarshaller interface
type Int64 ¶
type Int64 int64
Int64 is an int64 that will write as null when it is zero both to databases and JSON null values when unmarshalled or scanned from a DB will result in a zero value.
func (Int64) MarshalJSON ¶
MarshalJSON implements the Marshaller interface
func (*Int64) UnmarshalJSON ¶
UnmarshalJSON implements the Unmarshaller interface
type JSON ¶
type JSON json.RawMessage
JSON is a json.RawMessage that will marshall as null when empty or nil.
func (JSON) MarshalJSON ¶
MarshalJSON implements the Marshaller interface
func (*JSON) UnmarshalJSON ¶
UnmarshalJSON implements the Unmarshaller interface
type Map ¶
Map is a generic map which is written to the database as JSON.
func (Map[V]) MarshalJSON ¶
MarshalJSON implements the Marshaller interface
func (*Map[V]) UnmarshalJSON ¶
UnmarshalJSON implements the Unmarshaller interface
type String ¶
type String string
String is string that will write as null when it is empty, both to databases and JSON null values when unmarshalled or scanned from a DB will result in an empty string value.
func (String) MarshalJSON ¶
MarshalJSON implements the Marshaller interface
func (*String) UnmarshalJSON ¶
UnmarshalJSON implements the Unmarshaller interface
Source Files