option

README

Optional values for Go

Installation

go get github.com/sagikazarmark/go-option

License

The project is licensed under the MIT License.

Documentation

Overview

Package option provides tools for working with optional values.

It is heavily inspired by the option module in Rust implementing the same functionality: https://doc.rust-lang.org/std/option/index.html

Index

• func Equals[T comparable](o1 Option[T], o2 Option[T]) bool
• func IsNone[T any](o Option[T]) bool
• func IsSome[T any](o Option[T]) bool
• func MapOr[T any, U any](o Option[T], d U, f func(v T) U) U
• func MapOrElse[T any, U any](o Option[T], d func() U, f func(v T) U) U
• func TryMapOr[T any, U any](o Option[T], d U, f func(v T) (U, error)) (U, error)
• func TryMapOrElse[T any, U any](o Option[T], d func() U, f func(v T) (U, error)) (U, error)
• func Unwrap[T any](o Option[T]) T
• func UnwrapOr[T any](o Option[T], d T) T
• func UnwrapOrDefault[T any](o Option[T]) T
• func UnwrapOrElse[T any](o Option[T], d func() T) T
• type Option
  • func And[T any](o Option[T], o2 Option[T]) Option[T]
  • func AndThen[T any](o Option[T], f func(v T) Option[T]) Option[T]
  • func Filter[T any](o Option[T], f func(T) bool) Option[T]
  • func Map[T any, U any](o Option[T], f func(v T) U) Option[U]
  • func None[T any]() Option[T]
  • func Or[T any](o Option[T], o2 Option[T]) Option[T]
  • func OrElse[T any](o Option[T], f func() Option[T]) Option[T]
  • func Some[T any](value T) Option[T]
  • func TryMap[T any, U any](o Option[T], f func(v T) (U, error)) (Option[U], error)
  • func Xor[T any](o Option[T], o2 Option[T]) Option[T]

Examples

• IsNone
• IsSome
• None
• Some
• Unwrap
• UnwrapOr
• UnwrapOrDefault
• UnwrapOrElse

Functions

func Equals

func Equals[T comparable](o1 Option[T], o2 Option[T]) bool

Equals checks if two values are equal to each other according to the following: - Two Nones are always equal - Two Somes are equal if their values are equal

func IsNone

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

IsNone returns true if o does not contain a value.

Example

s := Some("hello")
n := None[string]()

fmt.Println(IsNone(s))
fmt.Println(IsNone(n))

Output:

false
true

func IsSome

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

IsSome returns true if o contains a value.

Example

s := Some("hello")
n := None[string]()

fmt.Println(IsSome(s))
fmt.Println(IsSome(n))

Output:

true
false

func MapOr

func MapOr[T any, U any](o Option[T], d U, f func(v T) U) U

MapOr applies the provided function to the contained value (if any) or returns the provided default value.

func MapOrElse

func MapOrElse[T any, U any](o Option[T], d func() U, f func(v T) U) U

MapOrElse applies the provided function to the contained value (if any) or computes it from the provided default function.

func TryMapOr

func TryMapOr[T any, U any](o Option[T], d U, f func(v T) (U, error)) (U, error)

TryMapOr applies the provided function to the contained value (if any) or returns the provided default value. If the function returns an error, it propagates back.

func TryMapOrElse

func TryMapOrElse[T any, U any](o Option[T], d func() U, f func(v T) (U, error)) (U, error)

TryMapOrElse applies the provided function to the contained value (if any) or computes it from the provided default function.

func Unwrap

func Unwrap[T any](o Option[T]) T

Unwrap returns the contained value or panics.

Example

s := Some("hello")

fmt.Println(Unwrap(s))
// fmt.Println(Unwrap(None[string]())) // This would panic

Output:

hello

func UnwrapOr

func UnwrapOr[T any](o Option[T], d T) T

UnwrapOr returns the contained value (if any) or returns the provided default value.

Example

s := Some("hello")
n := None[string]()

fmt.Println(UnwrapOr(s, "world"))
fmt.Println(UnwrapOr(n, "world"))

Output:

hello
world

func UnwrapOrDefault

func UnwrapOrDefault[T any](o Option[T]) T

UnwrapOrDefault returns the contained value (if any) or returns the default value of the type.

Example

s := Some("hello")
n := None[string]()

fmt.Println(UnwrapOrDefault(s))
fmt.Println(UnwrapOrDefault(n))

Output:

hello

func UnwrapOrElse

func UnwrapOrElse[T any](o Option[T], d func() T) T

UnwrapOrElse returns the contained value (if any) or computes it from the provided default function.

Example

s := Some("hello")
n := None[string]()

fmt.Println(UnwrapOrElse(s, func() string { return "world" }))
fmt.Println(UnwrapOrElse(n, func() string { return "world" }))

Output:

hello
world

Types

type Option

type Option[T any] interface {
	// HasValue returns true if the Option contains a value.
	HasValue() bool

	// Value returns the value (or its default) stored in the Option.
	Value() T
}

Option represents an optional value. It either contains a value or it does not.

An Option that contains a value is often called Some, while an Option without a value is called None. The terminology comes from Rust's option module: https://doc.rust-lang.org/std/option/index.html

Option describes a low-level interface used by the high-level API implemented by this package. The methods defined in Option are not supposed to be called directly.

func And

func And[T any](o Option[T], o2 Option[T]) Option[T]

And returns o2 if o contains a value.

func AndThen

func AndThen[T any](o Option[T], f func(v T) Option[T]) Option[T]

AndThen applies the provided function to the contained value (if any) and returns the new value or returns a None.

func Filter

func Filter[T any](o Option[T], f func(T) bool) Option[T]

Filter returns o if it contains a value and the provided predicate applied to the contained value returns true.

func Map

func Map[T any, U any](o Option[T], f func(v T) U) Option[U]

Map applies the provided function to the contained value (if any) or returns a None.

func None

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

None returns a new Option that does not contain a value.

Example

o := None[string]()

// Note: you are not supposed to call these methods directly.
// Please take a look at the rest of the functions in the package.
fmt.Println(o.HasValue())
fmt.Println(o.Value())

Output:

false

func Or

func Or[T any](o Option[T], o2 Option[T]) Option[T]

Or returns o if it contains a value, returns o2 otherwise.

func OrElse

func OrElse[T any](o Option[T], f func() Option[T]) Option[T]

OrElse returns o if it contains a value or returns the result of calling the provided function.

func Some

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

Some returns a new Option that contains a value.

Example

o := Some("hello")

// Note: you are not supposed to call these methods directly.
// Please take a look at the rest of the functions in the package.
fmt.Println(o.HasValue())
fmt.Println(o.Value())

Output:

true
hello

func TryMap

func TryMap[T any, U any](o Option[T], f func(v T) (U, error)) (Option[U], error)

TryMap applies the provided function to the contained value (if any) or returns a None. If the function returns an error, it propagates back (with a None).

func Xor

func Xor[T any](o Option[T], o2 Option[T]) Option[T]

Xor returns o or o2 if exactly one of them contains a value, otherwise returns a None.