nullable

package module
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2023 License: MIT Imports: 3 Imported by: 0

README

Go Nullable

Nullable is specifically designed for json marshalling and unmarshalling but not limited to, where zero values have business logic meaning.

Examples

package main

import (
	"fmt"

	"github.com/steelshot/go-nullable"
)

func main() {
	var greet nullable.Any[string]

	if greet.Null() {
		fmt.Println("greet is null after var declaration")
	}

	greet = nullable.Of("")

	if greet.Null() {
		fmt.Println("greet is null after zero value assignment")
	}

	greet = nullable.Of("Hello, World!")

	if greet.Null() {
		fmt.Println("greet is null after value assignment")
	}

	fmt.Printf(`greet value is "%s"`, greet)

	// Output:
	// greet is null after var declaration
	// greet value is "Hello, World!"
}

Roadmap

  • Aliases for builtin types
  • Text & Binary Marshalling
  • Support YAML, TOML and others without 3rd party dependencies
  • API freeze & release 1.0.0

FAQ

Which GoLang version do I need?

As of the current release, the minimum required Go version is 1.18 which introduced Go generics

What is planned for 1.0.0?

As of the current release Go generics are in their infancy age. As Go generics grow and become more streamlined, features will be added, modified or removed if there is benefit to the module. Breaking changes before v1.0.0 are expected.

License

MIT

Documentation

Overview

Package nullable is specifically designed for json marshalling and unmarshalling but not limited to, where zero values have business logic meaning.

Example (NullableNestedStruct)
var card nullable.Any[Card]

if card.Null() {
	fmt.Println("card is null after var declaration")
}

if card.Value().Person.Null() {
	fmt.Println("card.Person is null after card var declaration")
}

card = nullable.Of(Card{})

if card.Null() {
	fmt.Println("card is null after zero value declaration")
}

if card.Value().Person.Null() {
	fmt.Println("card.Person is null after card zero value declaration")
}

card = nullable.Of(Card{
	ID: "card-id",
	Person: nullable.Of(Person{
		Name: "John Doe",
		Age:  18,
	}),
})

if card.Null() {
	fmt.Println("card is null after value declaration")
}

if card.Value().Person.Null() {
	fmt.Println("card.Person is null after card value declaration")
}

fmt.Printf(`card value is "%s"`, card)
Output:

card is null after var declaration
card.Person is null after card var declaration
card.Person is null after card zero value declaration
card value is "{card-id {John Doe 18}}"
Example (NullableString)
var greet nullable.Any[string]

if greet.Null() {
	fmt.Println("greet is null after var declaration")
}

greet = nullable.Of("")

if greet.Null() {
	fmt.Println("greet is null after zero value assignment")
}

greet = nullable.Of("Hello, World!")

if greet.Null() {
	fmt.Println("greet is null after value assignment")
}

fmt.Printf(`greet value is "%s"`, greet)
Output:

greet is null after var declaration
greet value is "Hello, World!"
Example (NullableStruct)
var person nullable.Any[Person]

if person.Null() {
	fmt.Println("person is null after var declaration")
}

person = nullable.Of(Person{})

if person.Null() {
	fmt.Println("person is null after zero value assignment")
}

person = nullable.Of(Person{
	Name: "John Doe",
	Age:  18,
})

if person.Null() {
	fmt.Println("person is null after value assignment")
}

fmt.Printf(`person value is "%s"`, person)
Output:

person is null after var declaration
person value is "{John Doe 18}"

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Any added in v0.2.0

type Any[T any] struct {
	// contains filtered or unexported fields
}

Any holds a single value of type T BUG(golang) Golang currently (if ever?) has no type constraint that indicates that a type is json (un)marshalling compatible. If you use a json incompatible type like complex64, the marshal and unmarshal functions will always fail. BUG(steelshot) Currently the Any type does not implement text/binary (un)marshalling. YAML, TOML and other's (un)marshalling will not work, for the time being, You should implement your own types that embed Any with custom (un)marshalling.

func Of

func Of[T any](value T) Any[T]

Of returns a new non-null Any[typeof value]

func (Any[T]) Format added in v0.2.0

func (r Any[T]) Format(f fmt.State, verb rune)

Format implements fmt.Formatter

func (Any[T]) GoString added in v0.2.0

func (r Any[T]) GoString() string

GoString implements fmt.GoStringer

func (Any[T]) MarshalJSON added in v0.2.0

func (r Any[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler

func (Any[T]) Null added in v0.2.0

func (r Any[T]) Null() bool

Null will indicate whether Any is null (without value).

func (Any[T]) String added in v0.2.0

func (r Any[T]) String() string

String implements fmt.Stringer

func (*Any[T]) UnmarshalJSON added in v0.2.0

func (r *Any[T]) UnmarshalJSON(bytes []byte) (err error)

UnmarshalJSON implements json.Unmarshaler

func (Any[T]) Value added in v0.2.0

func (r Any[T]) Value() (value T)

Value returns the value of Any; unless it is null, then the zero value of T will be returned

type Bool added in v0.2.0

type Bool = Any[bool]

Arbitrary type alias

type Byte added in v0.2.0

type Byte = Uint8

Builtin alias' alias

type Float32 added in v0.2.0

type Float32 = Any[float32]

Real number alias

type Float64 added in v0.2.0

type Float64 = Any[float64]

Real number alias

type Int added in v0.2.0

type Int = Any[int]

Real number alias

type Int16 added in v0.2.0

type Int16 = Any[int16]

Real number alias

type Int32 added in v0.2.0

type Int32 = Any[int32]

Real number alias

type Int64 added in v0.2.0

type Int64 = Any[int64]

Real number alias

type Int8 added in v0.2.0

type Int8 = Any[int8]

Real number alias

type Rune added in v0.2.0

type Rune = Int32

Builtin alias' alias

type String added in v0.2.0

type String = Any[string]

Arbitrary type alias

type Uint added in v0.2.0

type Uint = Any[uint]

Real number alias

type Uint16 added in v0.2.0

type Uint16 = Any[uint16]

Real number alias

type Uint32 added in v0.2.0

type Uint32 = Any[uint32]

Real number alias

type Uint64 added in v0.2.0

type Uint64 = Any[uint64]

Real number alias

type Uint8 added in v0.2.0

type Uint8 = Any[uint8]

Real number alias

Notes

Bugs

  • Golang currently (if ever?) has no type constraint that indicates that a type is json (un)marshalling compatible. If you use a json incompatible type like complex64, the marshal and unmarshal functions will always fail.

  • Currently the Any type does not implement text/binary (un)marshalling. YAML, TOML and other's (un)marshalling will not work, for the time being, You should implement your own types that embed Any with custom (un)marshalling.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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