opt

Documentation

Overview

Package opt implements "optional" values. An Opt can either hold an error or a value. The special error ErrEmpty signifies that the option is empty. Options are not "futures" or "promises" but hold a pre-computed value.

Index

• Variables
• func Caller[T any](f FuncSourceErr[T]) func() Opt[T]
• func Mapper[S, T any](f func(S) (T, error)) func(S) Opt[T]
• func Ok[T any](opt Opt[T]) bool
• func RecoveringMapper[S any, T any](f func(S) (T, error)) func(S) Opt[T]
• type ErrPanic
  • func (p ErrPanic) Error() string
  • func (p ErrPanic) Unwrap() error
• type FuncSourceErr
• type Future
  • func Promise[T any](exec func(resolve func(Opt[T]))) *Future[T]
  • func PromiseThen[S, T any](first *Future[S], exec func(firstResult Opt[S], resolve func(Opt[T]))) *Future[T]
  • func (fut *Future[T]) Await() Opt[T]
  • func (fut *Future[T]) Then(exec func(firstResult Opt[T], resolve func(Opt[T]))) *Future[T]
• type Opt
  • func Empty[T any]() Opt[T]
  • func ErrorOf[T any](err error) Opt[T]
  • func Map[S, T any](opt Opt[S], f func(S) T) Opt[T]
  • func Of[T any](t T) Opt[T]
  • func Recovering[T any](f FuncSourceErr[T]) (op Opt[T])
  • func Returning[T any](t T, err error) Opt[T]
  • func Zero[T any]() Opt[T]
  • func (o Opt[T]) Empty() bool
  • func (o Opt[T]) Error() error
  • func (o Opt[T]) Map(f func(T) T) Opt[T]
  • func (o Opt[T]) Must() T
  • func (o Opt[T]) Ok() bool
  • func (o Opt[T]) OnErr(errFn func(err error) T) T
  • func (o Opt[T]) Or(altValue T) T
  • func (o Opt[T]) Return() (T, error)

Variables

var ErrEmpty = errors.New("empty")

ErrEmpty is a constant error value used to signify when an Opt is empty.

Functions

func Caller

func Caller[T any](f FuncSourceErr[T]) func() Opt[T]

Caller wraps an error-returning function in a function returning an opt. Caller is intended for use with seq.SourceOf and similar situation where you repeatedly call a source function that can error. See also Mapper.

Example

 i := 0
	ints, tail := seq.SourceOf(opt.Caller(func() (int, error) {
		i++
		if i > 3 {
			return 0, numTooBigError
		}
		return i, nil
	})).TakeWhile(opt.Ok[int])

 // ints = [opt.Of(1), opt.Of(2), opt.Of(3)]
 // tail wraps numTooBigError

func Mapper

func Mapper[S, T any](f func(S) (T, error)) func(S) Opt[T]

Mapper wraps an error-returning function in a function returning an opt. Mapper is intended for use with slice.Mapping and seq.MappingOf and similar transformations. See also Caller.

Example

	strInts := seq.SliceOfArgs("1", "two", "3")
	ints := seq.MappingOf(strInts, opt.Mapper(strconv.Atoi)).
		Where(opt.Ok[int]).
		ToSlice()

 // ints is [opt.Of(1), opt.Of(3)]

func Ok

func Ok[T any](opt Opt[T]) bool

Ok is just a different way of calling Opt.Ok. It can sometimes make seq expression read a bit easier.

func RecoveringMapper

func RecoveringMapper[S any, T any](f func(S) (T, error)) func(S) Opt[T]

RecoveringMapper is like Mapper but recovers panics produced by f.

Types

type ErrPanic

type ErrPanic struct {
	V any
}

ErrPanic wraps a panic value when Recovering or RecoveringMapper recovers from a panic.

func (ErrPanic) Error

func (p ErrPanic) Error() string

func (ErrPanic) Unwrap

func (p ErrPanic) Unwrap() error

type FuncSourceErr

type FuncSourceErr[T any] func() (T, error)

type Future

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

Future represents a result that will appear at some point in the future.

func Promise

func Promise[T any](exec func(resolve func(Opt[T]))) *Future[T]

Promise executes a function in a goroutine and returns a Future that can be used to wait for the result. The exec function *must* ensure that the resolve function is called exactly once. The promise does not have to be resolved by the exec function itself. It is allowed to pass the resolve function to other functions and goroutines.

Calling resolve multiple times will cause a panic. Failing to call resolve will cause Future.Await to hang forever.

If the exec function panics it will be recovered and Future.Await will return an option with an ErrPanic.

func PromiseThen

func PromiseThen[S, T any](first *Future[S], exec func(firstResult Opt[S], resolve func(Opt[T]))) *Future[T]

PromiseThen starts another promise when the result of a future is ready. The chained promise is started whether the first result is an error or not.

func (*Future[T]) Await

func (fut *Future[T]) Await() Opt[T]

Await blocks until the result is ready and returns it. If the result is already available the function returns immediately. It is valid to call from any goroutine and as many times as you like.

func (*Future[T]) Then

func (fut *Future[T]) Then(exec func(firstResult Opt[T], resolve func(Opt[T]))) *Future[T]

Then starts another promise result of this future is ready. The chained promise is started whether the first result is an error or not. If you need to change the type of the result you must use PromiseThen.

type Opt

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

Opt is a light wrapper around a value or an error. Opts should always be passed by value. If you see a pointer to an Opt anywhere something is wrong.

The zero Opt structure holds the default value for T and no error, and is *not* considered empty.

func Empty

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

Empty creates a new empty opt. An empty opt stores the special error ErrEmpty and will respond true to Opt.Empty() and false to Opt.Ok. An empty opt is not the same as a zero value. Empty opts should be thought of as a general nil, or missing value.

func ErrorOf

func ErrorOf[T any](err error) Opt[T]

ErrorOf creates a new opt wrapping an error.

func Map

func Map[S, T any](opt Opt[S], f func(S) T) Opt[T]

Map converts an option into some other type. If you want to keep the same type it may be easier to use Opt.Map. If the opt is empty or an error the mapping function will not be called.

func Of

func Of[T any](t T) Opt[T]

Of creates a new opt wrapping a value.

func Recovering

func Recovering[T any](f FuncSourceErr[T]) (op Opt[T])

Recovering a function returning an opt with the result. If the function panics it is recovered and returned as ErrPanic.

func Returning

func Returning[T any](t T, err error) Opt[T]

Returning creates an option from a value and an error.

Example:

fileOpt := opt.Returning(os.Open("/tmp/README.txt"))

func Zero

func Zero[T any]() Opt[T]

Zero creates an opt with the zero value for the type. This is *not* the same as an empty opt! A zero opt response true to Opt.Ok and does not have any error associated with it.

func (Opt[T]) Empty

func (o Opt[T]) Empty() bool

Empty returns true if the option holds ErrEmpty or any other error.

func (Opt[T]) Error

func (o Opt[T]) Error() error

Error returns the error, if any, held by this opt.

func (Opt[T]) Map

func (o Opt[T]) Map(f func(T) T) Opt[T]

Map applies a function to the value of the Opt, unless the Opt is empty. If you need to change the type inside the Opt you will have to use Map.

func (Opt[T]) Must

func (o Opt[T]) Must() T

Must returns the value wrapped by this opt or panics if there isn't one. It should be considered a last resort to use this function. It is almost always better to use Or, OnErr, or Return instead.

func (Opt[T]) Ok

func (o Opt[T]) Ok() bool

Ok returns true if there is no error associated with this opt. It is guaranteed to be valid to call Opt.Must() if Opt.Ok() returns true.

func (Opt[T]) OnErr

func (o Opt[T]) OnErr(errFn func(err error) T) T

OnErr calls a function if the opt is an error or returns the value directly. The function returns a default value that will be returned from OnErr.

func (Opt[T]) Or

func (o Opt[T]) Or(altValue T) T

Or returns the value held by this opt or an alternate value if it is empty or an error.

func (Opt[T]) Return

func (o Opt[T]) Return() (T, error)

Return unpacks the opt into a standard (value, error) pair.