option

Documentation

Overview

Package option implements option types in Go. It takes inspiration from samber/mo but also works with BSON and exposes a (hopefully) more refined interface.

Typical Go code uses pointers to represent such values. That’s problematic for 2 reasons: - If you accidentally dereference a nil pointer, your program panics. - The pointer can increase GC pressure.

This type solves both of those.

A couple special notes:

• nil values inside the Option, like `Some([]int(nil))`, are forbidden. (A runtime panic will happen if you try.) See functions like FromPointer and IfNotZero instead.
• Option’s BSON marshaling/unmarshaling interoperates with the bson package’s handling of nilable pointers. So any code that uses nilable pointers to represent optional values can switch to Option and should continue working with existing persisted data.
• Because encoding/json provides no equivalent to bsoncodec.Zeroer, Option always marshals to JSON null if empty.

Prefer Option to nilable pointers in all new code, and consider changing existing code to use it.

Index

• type Option
  • func FromPointer[T any](valPtr *T) Option[T]
  • func IfNotZero[T any](value T) Option[T]
  • func Map[T, V any](opt Option[T], f func(T) V) Option[V]
  • func None[T any]() Option[T]
  • func Some[T any](value T) Option[T]
  • func (o Option[T]) Get() (T, bool)
  • func (o Option[T]) IsNone() bool
  • func (o Option[T]) IsSome() bool
  • func (o Option[T]) IsZero() bool
  • func (o Option[T]) MarshalBSONValue() (byte, []byte, error)
  • func (o Option[T]) MarshalJSON() ([]byte, error)
  • func (o Option[T]) MustGet() T
  • func (o Option[T]) MustGetf(pattern string, args ...any) T
  • func (o Option[T]) OrElse(fallback T) T
  • func (o Option[T]) OrZero() T
  • func (o Option[T]) ToPointer() *T
  • func (o *Option[T]) UnmarshalBSONValue(bType byte, raw []byte) error
  • func (o *Option[T]) UnmarshalJSON(b []byte) error

Types

type Option

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

Option represents a possibly-empty value. Its zero value is the empty case.

func FromPointer

func FromPointer[T any](valPtr *T) Option[T]

FromPointer will convert a nilable pointer into its equivalent Option.

func IfNotZero

func IfNotZero[T any](value T) Option[T]

IfNotZero returns an Option that’s populated if & only if the given value is a non-zero value. (NB: The zero value for slices & maps is nil, not empty!)

This is useful, e.g., to interface with code that uses nil to indicate a missing slice or map.

func Map

func Map[T, V any](opt Option[T], f func(T) V) Option[V]

Map transforms `opt` by applying the given function to its internal value, if it exists. If `opt` is empty, this returns empty.

func None

func None[T any]() Option[T]

None creates an Option with no value.

Note that `None[T]()` is interchangeable with `Option[T]{}`.

func Some

func Some[T any](value T) Option[T]

Some creates an Option with a value.

func (Option[T]) Get

func (o Option[T]) Get() (T, bool)

Get “unboxes” the Option’s internal value. The boolean indicates whether the value exists.

func (Option[T]) IsNone

func (o Option[T]) IsNone() bool

IsNone returns a boolean indicating whether or not the option is a None value.

func (Option[T]) IsSome

func (o Option[T]) IsSome() bool

IsSome returns a boolean indicating whether or not the option is a Some value.

func (Option[T]) IsZero

func (o Option[T]) IsZero() bool

IsZero implements bson.Zeroer.

func (Option[T]) MarshalBSONValue

func (o Option[T]) MarshalBSONValue() (byte, []byte, error)

MarshalBSONValue implements bson.ValueMarshaler.

func (Option[T]) MarshalJSON

func (o Option[T]) MarshalJSON() ([]byte, error)

MarshalJSON encodes Option into json.

func (Option[T]) MustGet

func (o Option[T]) MustGet() T

MustGet is like Get but panics if the Option is empty.

func (Option[T]) MustGetf

func (o Option[T]) MustGetf(pattern string, args ...any) T

MustGetf is like MustGet, but this lets you customize the panic.

func (Option[T]) OrElse

func (o Option[T]) OrElse(fallback T) T

OrElse returns either the Option’s internal value or the given `fallback`.

func (Option[T]) OrZero

func (o Option[T]) OrZero() T

OrZero returns either the Option’s internal value or the type’s zero value.

func (Option[T]) ToPointer

func (o Option[T]) ToPointer() *T

ToPointer converts the Option to a nilable pointer. The internal value (if it exists) is (shallow-)copied.

func (*Option[T]) UnmarshalBSONValue

func (o *Option[T]) UnmarshalBSONValue(bType byte, raw []byte) error

UnmarshalBSONValue implements bson.ValueUnmarshaler.

func (*Option[T]) UnmarshalJSON

func (o *Option[T]) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes Option from json.