null

package module
v3.0.0 Latest Latest
Warning

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

Go to latest
Published: Sep 6, 2023 License: MIT Imports: 6 Imported by: 0

README

null Build Status codecov Go Report Card

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

View Source
const NullInt = Int(0)

NullInt is our constant for an Int value that will be written as null

View Source
const NullInt64 = Int64(0)

NullInt64 is our constant for an Int64 value that will be written as null

View Source
const NullString = String("")

NullString is our constant for an String value that will be written as null

Variables

View Source
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 JSONValue

func JSONValue(j JSON) (driver.Value, error)

func MapValue

func MapValue[V any](m Map[V]) (driver.Value, error)

MapValue converts a map to NULL if it is empty.

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 MarshalJSON(j JSON) ([]byte, error)

func MarshalMap

func MarshalMap[V any](m Map[V]) ([]byte, error)

MarshalMap marshals a map, returning null for an empty map.

func MarshalString

func MarshalString[T ~string](s T) ([]byte, error)

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 ScanJSON

func ScanJSON(value any, j *JSON) error

func ScanMap

func ScanMap[V any](value any, m *Map[V]) error

ScanMap scans a nullable text or JSON into a map, using an empty map for NULL.

func ScanString

func ScanString[T ~string](value any, s *T) error

ScanString scans a nullable CHAR/TEXT into a string type, using empty string for NULL.

func StringValue

func StringValue[T ~string](s T) (driver.Value, error)

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 UnmarshalJSON(data []byte, j *JSON) error

func UnmarshalMap

func UnmarshalMap[V any](data []byte, m *Map[V]) error

func UnmarshalString

func UnmarshalString[T ~string](b []byte, s *T) error

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

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

MarshalJSON implements the Marshaller interface

func (*Int) Scan

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

Scan implements the Scanner interface

func (*Int) UnmarshalJSON

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

UnmarshalJSON implements the Unmarshaller interface

func (Int) Value

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

Value implements the Valuer 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

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

MarshalJSON implements the Marshaller interface

func (*Int64) Scan

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

Scan implements the Scanner interface

func (*Int64) UnmarshalJSON

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

UnmarshalJSON implements the Unmarshaller interface

func (Int64) Value

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

Value implements the Valuer interface

type JSON

type JSON json.RawMessage

JSON is a json.RawMessage that will marshall as null when empty or nil.

func (JSON) IsNull

func (j JSON) IsNull() bool

IsNull returns whether this JSON value is empty or contains null.

func (JSON) MarshalJSON

func (j JSON) MarshalJSON() ([]byte, error)

MarshalJSON implements the Marshaller interface

func (*JSON) Scan

func (j *JSON) Scan(value any) error

Scan implements the Scanner interface

func (*JSON) UnmarshalJSON

func (j *JSON) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the Unmarshaller interface

func (JSON) Value

func (j JSON) Value() (driver.Value, error)

Value implements the Valuer interface

type Map

type Map[V any] map[string]V

Map is a generic map which is written to the database as JSON.

func (Map[V]) MarshalJSON

func (m Map[V]) MarshalJSON() ([]byte, error)

MarshalJSON implements the Marshaller interface

func (*Map[V]) Scan

func (m *Map[V]) Scan(value any) error

Scan implements the Scanner interface

func (*Map[V]) UnmarshalJSON

func (m *Map[V]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the Unmarshaller interface

func (Map[V]) Value

func (m Map[V]) Value() (driver.Value, error)

Value implements the Valuer 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

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

MarshalJSON implements the Marshaller interface

func (*String) Scan

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

Scan implements the Scanner interface

func (*String) UnmarshalJSON

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

UnmarshalJSON implements the Unmarshaller interface

func (String) Value

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

Value implements the Valuer interface

Jump to

Keyboard shortcuts

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