optional

README

Optional Package

The optional package in Go provides a generic type that can represent values which may or may not be set, including the concept of null. This allows handling scenarios where a value might be missing or explicitly set to null in JSON. The package is designed to be flexible and efficient, with support for custom marshalling and unmarshalling functions.

Features

• Generic Type: Supports any type T.
• Null Handling: Distinguishes between unset values, null values, and non-null values.
• Custom Marshalling/Unmarshalling: Allows changing the JSON marshalling/unmarshalling implementation, such as using a faster library like json-iterator.

Installation

To install the optional package, use the following command:

go get github.com/micronull/optional

Usage

Basic Usage

Here's a simple example demonstrating how to use the Type struct and its methods:

package main

import (
	"encoding/json"
	"fmt"

	"github.com/micronull/optional"
)

func main() {
	// Create a new optional value that is not null
	optVal := optional.New[string]("hello", false)
	fmt.Println(optVal.IsSet())    // Output: true
	fmt.Println(optVal.IsSetNull()) // Output: false

	// Marshal the optional value to JSON
	jsonBytes, _ := json.Marshal(optVal)
	fmt.Println(string(jsonBytes)) // Output: "hello"

	// Create a new optional value that is explicitly null
	optNull := optional.New[string]("", true)
	fmt.Println(optNull.IsSet())    // Output: false
	fmt.Println(optNull.IsSetNull()) // Output: true

	// Marshal the null optional value to JSON
	jsonBytes, _ = json.Marshal(optNull)
	fmt.Println(string(jsonBytes)) // Output: null

	// Unmarshal JSON into an optional value
	var opt optional.Type[string]
	
	fmt.Println(opt.IsSet()) // Output: false
	fmt.Println(opt.IsSetNull()) // Output: false
	
	json.Unmarshal([]byte(`"world"`), &opt)
	fmt.Println(opt.V) // Output: world
	fmt.Println(opt.IsSet()) // Output: true
	fmt.Println(opt.IsSetNull()) // Output: false

	json.Unmarshal([]byte(`null`), &opt)
	fmt.Println(opt.IsSet()) // Output: true
	fmt.Println(opt.IsSetNull()) // Output: true
}

Custom Marshalling/Unmarshalling

You can replace the default JSON marshalling and unmarshalling functions with your own implementations, such as using json-iterator:

package main

import (
	"fmt"

	jsoniter "github.com/json-iterator/go"

	"github.com/micronull/optional"
)

func init() {
	// Replace the default marshaller with json-iterator's marshaller
	optional.ChangeMarshal(jsoniter.Marshal)
	// Replace the default unmarshaller with json-iterator's unmarshaller
	optional.ChangeUnmarshal(jsoniter.Unmarshal)
}

func main() {
	optVal := optional.New[string]("hello", false)

	jsonBytes, _ := jsoniter.Marshal(optVal)
	fmt.Println(string(jsonBytes)) // Output: "hello"
}

Contributing

Contributions are welcome! If you have any suggestions or find a bug, please open an issue on the GitHub repository.

License

This package is licensed under the MIT License. See the LICENSE file for more information.

Documentation

Overview

Package optional provides a generic type that can represent values which may or may not be set, including the concept of null. This allows handling scenarios where a value might be missing or explicitly set to null in JSON.

Index

• func ChangeMarshal(m func(v any) ([]byte, error))
• func ChangeUnmarshal(u func(data []byte, v any) error)
• type Type
  • func New[T any](value T, null bool) Type[T]
  • func (t Type[T]) IsSet() bool
  • func (t Type[T]) IsSetNull() bool
  • func (t Type[T]) MarshalJSON() ([]byte, error)
  • func (t *Type[T]) UnmarshalJSON(bytes []byte) error

Functions

func ChangeMarshal

func ChangeMarshal(m func(v any) ([]byte, error))

ChangeMarshal allows you to change the function used for marshalling. By default, it uses json.Marshal. You can provide an alternative implementation, such as from a library like https://pkg.go.dev/github.com/json-iterator/go.

func ChangeUnmarshal

func ChangeUnmarshal(u func(data []byte, v any) error)

ChangeUnmarshal allows you to change the function used for unmarshalling. By default, it uses json.Unmarshal. You can provide an alternative implementation, such as from a library like https://pkg.go.dev/github.com/json-iterator/go.

Types

type Type

type Type[T any] struct {
	V T // V holds the actual value of type T.
	// contains filtered or unexported fields
}

Type represents a generic value that may or may not be set and could also be null.

func New

func New[T any](value T, null bool) Type[T]

New creates a new instance of Type with the specified value and null status.

func (Type[T]) IsSet

func (t Type[T]) IsSet() bool

IsSet checks if the value has been set, either to a non-null value or explicitly to null.

func (Type[T]) IsSetNull

func (t Type[T]) IsSetNull() bool

IsSetNull checks if the value is explicitly set to null.

func (Type[T]) MarshalJSON

func (t Type[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface for Type. It handles marshalling a Type instance to JSON, correctly representing unset values as empty, null values as `null`, and non-null values using the specified marshaller.

func (*Type[T]) UnmarshalJSON

func (t *Type[T]) UnmarshalJSON(bytes []byte) error

UnmarshalJSON implements the json.Unmarshaler interface for Type. It handles unmarshalling JSON data into a Type instance, distinguishing between unset values, null values, and actual non-null values.