gooptional

README

// SPDX-License-Identifier: Apache-2.0
:doctype: article

= gooptional

Implementation of optional similar to Java.

== Main differences from Java

- Single constructor for both initial cases of empty and with a value
- Comparisons made by Filter, where gofuncs provides conjunction, disjunction, negation, and equality.
- Implements goiter.Iterable, provides an iterator of zero or one elements
- Since goiter.Iter has specialization methods such as IntValue and NextIntValue, there is no need for specialized classes like Java OptionalInt
- Implements database/sql/driver Scanner and Valuer interfaces for compatibility with values read from/written to a column
- Implements Stringer to return "Optional" or fmt.Sprintf("Optional (%v)", value)

== Constructors

Of(...interface{}) returns an empty Optional if no args are passed or nil is passed, or a present Optional with the first arg passed.

== Getters

* Get() method returns (val, bool) where val is valid only if bool is true
* MustGet() method returns val, and panics if empty
* OrElse(defaultVal) returns val if present, else the given default value
* OrElseGet(supplier func() any) returns val if present, else the result of the given supplier
* OrElsePanic(msg func() string) returns val if present, else panics with the result of the given func
* IsEmpty() returns true if empty
* IsPresent() returns true is present
* IfEmpty(func()) executes the given func if empty
* IfPresent(consumer func(val)) executes the given consumer with the value if present
* IfPresentOrElse(consumer func(val), empty func()) executes the given consumer with the value present, else executes the empty func

== Transforms

* Iter() return a *goIter.Iter of one element if present, else an empty Iter
* Filter(func(any) bool) returns this Optional if present and the predicate returns true for the value, else an empty Optional
* Map(func(any) any, zeroValIsPresent = ZeroValueIsPresent) calls the map func if present and returns an Optional of the new value, else returns an empty Optional.
  If the mapping func returns a zero value then if zeroValIsPresent == ZeroValueIsPresent, an Optional of the zero value is returned, else an empty Optional is returned.
* FlatMap(func(any) Optional), calls the map func if present and returns the resulting Optional, else returns an empty Optional.

== Database

* Scan(any) is the database/sql Scanner interface and overwrites the value in the Optional.
  This is the only method that modifies an Optional.
* Value() (driver.Value, error) is the database/sql/driver/Valuer interface that writes a value into a column.
  returns (value, nil) if present, else (nil, nil)

== Other

* String() string is the fmt.Stringer interface, returning "Optional" if empty, else fmt.Sprintf("Optional (%v)", value).

Documentation

Overview

Package gooptional is similar to Java Optional types SPDX-License-Identifier: Apache-2.0

Index

• type Optional
  • func FlatMap[T any, U any](o Optional[T], f func(T) Optional[U]) Optional[U]
  • func Map[T any, U any](o Optional[T], f func(T) U) Optional[U]
  • func Of[T any](value T) Optional[T]
  • func (o Optional[T]) Filter(predicate func(T) bool) Optional[T]
  • func (o Optional[T]) Get() (T, bool)
  • func (o Optional[T]) IfEmpty(f func())
  • func (o Optional[T]) IfPresent(consumer func(T))
  • func (o Optional[T]) IfPresentOrElse(consumer func(T), f func())
  • func (o Optional[T]) IsEmpty() bool
  • func (o Optional[T]) IsPresent() bool
  • func (o Optional[T]) MustGet() T
  • func (o Optional[T]) OrElse(elseValue T) T
  • func (o Optional[T]) OrElseGet(supplier func() T) interface{}
  • func (o *Optional[T]) Scan(src any) error
  • func (o Optional[T]) String() string
  • func (o Optional[T]) Value() (driver.Value, error)

Types

type Optional

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

Optional is a mostly immutable generic wrapper for any kind of value with a present flag. The only mutable operation is the implementation of the sql.Scanner interface. The zero value is ready to use.

func FlatMap

func FlatMap[T any, U any](o Optional[T], f func(T) Optional[U]) Optional[U]

FlatMap operates like Map, except that the mapping function already returns an Optional, which is returned as is.

func Map

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

Map the wrapped value with the given mapping function, which may return a different type. An empty Optional is returned if this optional is not present. Otherwise, an Optional wrapping the mapped value is returned.

func Of

func Of[T any](value T) Optional[T]

Of returns a present Optional. If no value or a nil value is provided, a new empty Optional is returned. Otherwise a new Optional that wraps the value is returned.

func (Optional[T]) Filter

func (o Optional[T]) Filter(predicate func(T) bool) Optional[T]

Filter applies the predicate to the value of this Optional. Returns this Optional only if this Optional is present and the filter returns true for the value. Otherwise an empty Optional is returned.

func (Optional[T]) Get

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

Get returns the wrapped value and whether or not it is present. The wrapped value is only valid if the boolean is true.

func (Optional[T]) IfEmpty

func (o Optional[T]) IfEmpty(f func())

IfEmpty executes the function only if the value is not present.

func (Optional[T]) IfPresent

func (o Optional[T]) IfPresent(consumer func(T))

IfPresent executes the consumer function with the wrapped value only if the value is present.

func (Optional[T]) IfPresentOrElse

func (o Optional[T]) IfPresentOrElse(consumer func(T), f func())

IfPresentOrElse executes the consumer function with the wrapped value if the value is present, otherwise executes the function of no args.

func (Optional[T]) IsEmpty

func (o Optional[T]) IsEmpty() bool

IsEmpty returns true if this Optional is not present

func (Optional[T]) IsPresent

func (o Optional[T]) IsPresent() bool

IsPresent returns true if this Optional is present

func (Optional[T]) MustGet

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

MustGet returns the unwrapped value and panics if it is not present.

func (Optional[T]) OrElse

func (o Optional[T]) OrElse(elseValue T) T

OrElse returns the wrapped value if it is present, else it returns the given value.

func (Optional[T]) OrElseGet

func (o Optional[T]) OrElseGet(supplier func() T) interface{}

OrElseGet returns the wrapped value if it is present, else it returns the result of the given function.

func (*Optional[T]) Scan

func (o *Optional[T]) Scan(src any) error

Scan is database/sql/Scanner interface, allowing users to read null query columns into an Optional. This is the only method that modifies an Optional. If src is null, the Optional will be empty even if T is not a nillable type. If src is not null: - Panics if src is not convertible to T - If T is a reference type, the referenced value must be copied before the next call to Scan

func (Optional[T]) String

func (o Optional[T]) String() string

String returns fmt.Sprintf("Optional (%v)", wrapped value) if present, else "Optional" if it is empty.

func (Optional[T]) Value

func (o Optional[T]) Value() (driver.Value, error)

Value is the database/sql/driver/Valuer interface, allowing users to write an Optional into a column. If a present optional does not contain an allowed type, the operation will fail. It is up to the caller to ensure the correct type is being written.