optional

README

go-optional

A container object to describe the specified type value that may or may not contain a non-nil value.

Installation

You can install the package by the following command.

go get -u github.com/ghosind/go-optional

Getting Started

You can create an Optional instance with a pointer, and perform actions with the Optional instance.

s := "Hello world"
vp := &s

val = optional.New(vp)
a.IsPresent() // true
val.OrElse("default string") // Hello world
val.IfPresent(func (s string) {
  fmt.Println(s)
})
// Hello world

// Optional instance with nil value
vp = nil
val := optional.New(vp)
vp.IsPresent() // false
val.OrElse("default string") // default string
val.IfPresent(func (s string) {
  fmt.Println(s)
}) // Not invoked

The Optional type also supports marshaling the value to a JSON string, or unmarshal from a JSON string.

type Example struct {
  Val *optional.Optional[string] `json:"val"`
}

example := Example{
  Val: optional.Of("Hello world"),
}
out, err := json.Marshal(example)
fmt.Println(string(out))
// {"val":"Hello world"}

json.Unmarshal([]byte("Test"), &example)
fmt.Println(example)
// {Hello world}

Documentation

Index

• Variables
• type Optional
  • func Empty[T comparable]() *Optional[T]
  • func New[T comparable](v *T) *Optional[T]
  • func Of[T comparable](v T) *Optional[T]
  • func (opt *Optional[T]) Clone() *Optional[T]
  • func (opt *Optional[T]) Equals(other any) bool
  • func (opt *Optional[T]) Filter(predicate func(v T) bool) *Optional[T]
  • func (opt *Optional[T]) Get() (T, error)
  • func (opt *Optional[T]) GetPanic() T
  • func (opt *Optional[T]) IfPresent(action func(v T))
  • func (opt *Optional[T]) IfPresentOrElse(action func(v T), emptyAction func())
  • func (opt *Optional[T]) IsEmpty() bool
  • func (opt *Optional[T]) IsPresent() bool
  • func (opt *Optional[T]) MarshalJSON() ([]byte, error)
  • func (opt *Optional[T]) Or(supplier func() *Optional[T]) *Optional[T]
  • func (opt *Optional[T]) OrElse(other T) T
  • func (opt *Optional[T]) OrElseGet(supplier func() T) T
  • func (opt *Optional[T]) String() string
  • func (opt *Optional[T]) UnmarshalJSON(b []byte) error

Examples

• Optional
• Optional.MarshalJSON
• Optional.UnmarshalJSON

Variables

var (
	// ErrNilFunction indicates the supplier function is nil.
	ErrNilFunction = errors.New("nil function")
	// ErrNoSuchValue indicates the Optional does not contain any value.
	ErrNoSuchValue = errors.New("no such value")
)

Types

type Optional

type Optional[T comparable] struct {
	// contains filtered or unexported fields
}

Optional is a container that may or may not contains a non-nil value.

Example

s := "Hello world"
sp := &s

opt := optional.New(sp)
fmt.Println(opt.IsPresent())
fmt.Println(opt.OrElse("Default"))

sp = nil
opt = optional.New(sp)
fmt.Println(opt.IsPresent())
fmt.Println(opt.OrElse("Default"))

Output:

true
Hello world
false
Default

func Empty

func Empty[T comparable]() *Optional[T]

Empty returns an empty Optional instance.

func New

func New[T comparable](v *T) *Optional[T]

New returns an Optional with the value if it's not nil, otherwise returns and empty Optional.

func Of

func Of[T comparable](v T) *Optional[T]

Of returns an Optional instance with the specified value.

func (*Optional[T]) Clone

func (opt *Optional[T]) Clone() *Optional[T]

Clone creates and returns a copy of this optional value.

func (*Optional[T]) Equals

func (opt *Optional[T]) Equals(other any) bool

Equals indicates whether some other value is equals to this Optional.

func (*Optional[T]) Filter

func (opt *Optional[T]) Filter(predicate func(v T) bool) *Optional[T]

Filter returns the Optional if the value is present and matches the given predicate, otherwise returns an empty Optional.

func (*Optional[T]) Get

func (opt *Optional[T]) Get() (T, error)

Get returns the value if a value is present in the Optional, otherwise returns an ErrNoSuchValue.

func (*Optional[T]) GetPanic

func (opt *Optional[T]) GetPanic() T

GetPanic returns the value if a value is present in the Optional, otherwise panic ErrNoSuchValue.

func (*Optional[T]) IfPresent

func (opt *Optional[T]) IfPresent(action func(v T))

IfPresent performs the given action with the value if it is present, otherwise does nothing.

func (*Optional[T]) IfPresentOrElse

func (opt *Optional[T]) IfPresentOrElse(action func(v T), emptyAction func())

IfPresentOrElse performs the given action with the value if it is present, otherwise performs the given empty-based action.

func (*Optional[T]) IsEmpty

func (opt *Optional[T]) IsEmpty() bool

IsEmpty return true if there is not a value present, otherwise false.

func (*Optional[T]) IsPresent

func (opt *Optional[T]) IsPresent() bool

IsPresent return true if there is a value present, otherwise false.

func (*Optional[T]) MarshalJSON

func (opt *Optional[T]) MarshalJSON() ([]byte, error)

MarshalJSON marshals the value and returns into valid JSON.

Example

type Example struct {
	Val *optional.Optional[string] `json:"val"`
}

val := &Example{
	Val: optional.Of("Hello world"),
}
out, err := json.Marshal(val)
fmt.Println(string(out))
fmt.Println(err)

val.Val = optional.Empty[string]()
out, err = json.Marshal(val)
fmt.Println(string(out))
fmt.Println(err)

Output:

{"val":"Hello world"}
<nil>
{"val":null}
<nil>

func (*Optional[T]) Or

func (opt *Optional[T]) Or(supplier func() *Optional[T]) *Optional[T]

Or returns the Optional instance if the value is present, otherwise returns an Optional produced by the supplying function.

func (*Optional[T]) OrElse

func (opt *Optional[T]) OrElse(other T) T

OrElse returns the value if present, otherwise returns other.

func (*Optional[T]) OrElseGet

func (opt *Optional[T]) OrElseGet(supplier func() T) T

OrElseGet returns the value if present, otherwise returns the result produces by the supplier function.

func (*Optional[T]) String

func (opt *Optional[T]) String() string

String returns a string for representing the value.

func (*Optional[T]) UnmarshalJSON

func (opt *Optional[T]) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshal a JSON to an Optional value.

Example

type Example struct {
	Val *optional.Optional[string] `json:"val"`
}

val := &Example{}
json.Unmarshal([]byte(`{"val":"Hello world"}`), &val)
fmt.Println(val.Val)

Output:

Hello world