optional

README

Optional values for Go projects

We often need tools that help us work with optional values. For example, for optional fields in requests/responses from APIs (JSON), optional values in YAML/JSON configs, or nullable columns in some tables. Typically, we use a pointer for certain data types, but this does not work well for some scenarios.

This package offers a simple way to define optional fields and provides some helpers for marshalling and unmarshalling data.

Features

• JSON marshal/unmarshal
• YAML marshal/unmarshal
• SQL driver value/scan
• Useful functions to create and handle optional values

Installation

go get -u github.com/kazhuravlev/optional

Usage

package main

import (
	"fmt"
	"encoding/json"
	"github.com/kazhuravlev/optional"
)

type User struct {
	AvatarURL optional.Val[string] `json:"avatar_url"`
	// some fields...
}

func main() {
	req := []byte(`{"avatar_url": "https://example.com/img.webp"}`)
	var user User
	if err := json.Unmarshal(req, &user); err != nil {
		panic(err)
	}

	// Check the presence of value and use it.
	if avatar, ok := user.AvatarURL.Get(); ok {
		fmt.Println("User have avatar", avatar)
	} else {
		fmt.Println("User have no avatar")
	}

	// Just check that value presented.
	if !user.AvatarURL.HasVal() {
		fmt.Println("User have no avatar")
	}

	// Use default value in case of it did not presented.
	fmt.Println("Avatar of this user is:", user.AvatarURL.ValDefault("https://example.com/default.webp"))

	// Use this api to adapt value to pointer. It will return nil when value not provided.
	avatarPtr := user.AvatarURL.AsPointer()
	fmt.Printf("Pointer to avatar: %#v\n", avatarPtr)
}

Documentation

Index

• type Val
  • func Empty[T any]() Val[T]
  • func New[T any](val T) Val[T]
  • func NewFromPointer[T any](val *T) Val[T]
  • func (v Val[T]) AsPointer() *T
  • func (v Val[T]) Get() (T, bool)
  • func (v Val[T]) HasVal() bool
  • func (v Val[T]) MarshalJSON() ([]byte, error)
  • func (v Val[T]) MarshalYAML() ([]byte, error)
  • func (v *Val[T]) Reset()
  • func (v *Val[T]) Scan(value any) error
  • func (v *Val[T]) Set(val T)
  • func (v *Val[T]) UnmarshalJSON(buf []byte) error
  • func (v *Val[T]) UnmarshalYAML(bb []byte) error
  • func (v Val[T]) Val() T
  • func (v Val[T]) ValDefault(defaultVal T) T
  • func (v Val[T]) Value() (driver.Value, error)

Types

type Val

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

Val contains value and flag that mark this value as empty.

func Empty

func Empty[T any]() Val[T]

Empty create container without value.

func New

func New[T any](val T) Val[T]

func NewFromPointer

func NewFromPointer[T any](val *T) Val[T]

NewFromPointer create Val from pointer to some type. Nil pointer means that value not provided.

func (Val[T]) AsPointer

func (v Val[T]) AsPointer() *T

AsPointer adapt value to pointer. It will return nil when value not provided.

func (Val[T]) Get

func (v Val[T]) Get() (T, bool)

func (Val[T]) HasVal

func (v Val[T]) HasVal() bool

HasVal return value of flag hasVal.

func (Val[T]) MarshalJSON

func (v Val[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (Val[T]) MarshalYAML

func (v Val[T]) MarshalYAML() ([]byte, error)

MarshalYAML implements the interface for marshaling yaml.

func (*Val[T]) Reset

func (v *Val[T]) Reset()

Reset will clear value and mark this as empty.

func (*Val[T]) Scan

func (v *Val[T]) Scan(value any) error

Scan implements the Scanner interface.

func (*Val[T]) Set

func (v *Val[T]) Set(val T)

Set will set the value and mark that value is presented.

func (*Val[T]) UnmarshalJSON

func (v *Val[T]) UnmarshalJSON(buf []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (*Val[T]) UnmarshalYAML

func (v *Val[T]) UnmarshalYAML(bb []byte) error

UnmarshalYAML implements the interface for unmarshalling yaml.

func (Val[T]) Val

func (v Val[T]) Val() T

Val return internal value.

func (Val[T]) ValDefault

func (v Val[T]) ValDefault(defaultVal T) T

ValDefault returns value, if presented or defaultVal in other case.

func (Val[T]) Value

func (v Val[T]) Value() (driver.Value, error)

Value implements the driver Valuer interface.