opt

README

go-opt

Package opt implements an optional-type, for the Go programming language.

In other programming languages, an optional-type might be know as: a option-type, or a maybe-type.

Documention

Online documentation, which includes examples, can be found at: http://godoc.org/sourcecode.social/reiver/go-opt

Examples

Here is an example optional-type that can hold a string:

import "sourcecode.social/reiver/go-opt"

//

var op opt.Optional[string] // the default value is nothing.

// ...

if opt.Nothing[string]() == op {
	fmt.Println("nothing")
}

// ...

op = opt.Something("Hello world! 👾")

// ...

switch op {
case op.Nothing[string]():
	//@TODO
case op.Something("apple"):
	//@TODO
case op.Something("banana"):
	//@TODO
case op.Something("cherry"):
	//@TODO
default:
	//@TODO
}

// ...

value, found := op.Get()
if found {
	fmt.Println("VALUE:", value)
} else {
	fmt.Println("nothing")
}

Import

To import package opt use import code like the follownig:

import "sourcecode.social/reiver/go-opt"

Installation

To install package opt do the following:

GOPROXY=direct go get https://sourcecode.social/reiver/go-opt

Author

Package opt was written by Charles Iliya Krempeaux

Documentation

Index

• type Optional
  • func Map[T1 any, T2 any](op Optional[T1], fn func(T1) T2) Optional[T2]
  • func Nothing[T any]() Optional[T]
  • func Something[T any](value T) Optional[T]
  • func Then[T1 any, T2 any](op Optional[T1], fn func(T1) Optional[T2]) Optional[T2]
  • func (receiver Optional[T]) Filter(fn func(T) bool) Optional[T]
  • func (receiver Optional[T]) Get() (T, bool)
  • func (receiver Optional[T]) GetElse(alternative T) T
  • func (receiver Optional[T]) GoString() string
  • func (receiver Optional[T]) IsNothing() bool
  • func (receiver Optional[T]) IsSomething() bool
  • func (receiver Optional[T]) MarshalJSON() ([]byte, error)
  • func (receiver *Optional[T]) UnmarshalJSON(data []byte) error
  • func (receiver Optional[T]) WhenNothing(fn func())
  • func (receiver Optional[T]) WhenSomething(fn func(T))

Types

type Optional

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

Optional represents an optional value.

In other programming languages this is know as: an option type, or a maybe type.

For example:

var op opt.Optional[string] = opt.Something("once twice thrice fource")

// ...

value, found := op.Get()
if found {
	fmt.Println("value:", value)
} else{
	fmt.Println("nothing")
}

Also, for example:

var op opt.Optional[uint8] = opt.Something[uint8](101)

// ...

value, found := op.Get()
if found {
	fmt.Println("value:", value)
} else{
	fmt.Println("nothing")
}

func Map

func Map[T1 any, T2 any](op Optional[T1], fn func(T1) T2) Optional[T2]

Map applies the function ‘fn’ to the value inside of the optional-type ‘op’, if the optional-type ‘op’ is holding something, and returns it as a new optional-type. If the optional-type ‘op’ is holding nothing, then Map also returns nothing.

For example:

var op opt.Optional[string] = opt.Something("Hello world!")

var result opt.Optional[string] = opt.Map(op, strings.ToUpper)

// result == opt.Something[string]("HELLO WORLD!")

// ...

var op2 opt.Optional[string] = opt.Nothing[string]()

var result2 opt.Optional[string] = opt.Map(op, strings.ToUpper)

// result2 == opt.Nothing[string]()

Or also, for example:

fn := func(s string) int {
	return len(s)
}

var op opt.Optional[string] = opt.Something("Hello world!")

var result opt.Optional[int] = opt.Map(op, fn)

// result == opt.Something[int](12)

// ...

var op2 opt.Optional[string] = opt.Nothing[string]()

var result2 opt.Optional[int] = opt.Map(op, fn)

// result2 == opt.Nothing[int]()

func Nothing

func Nothing[T any]() Optional[T]

Nothing returns an optional-type with nothing in it.

For example, here is an optional-type that can hold a string with nothing in it:

var op opt.Optional[string] = opt.Nothing[string]()

Note that the default value for any optional-type is nothing. So the following code it equivalent to it:

var op opt.Optional[string]

Also, for example, here is an optional-type that can hold a uint8 with nothing in it:

var op opt.Optional[uint8] = opt.Nothing[uint8]()

Again, note that the default value for any optional-type is nothing. So the following code it equivalent to it:

var op opt.Optional[uint8]

func Something

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

Something returns a optional-type with something in it.

For example, here is an optional-type with the string "once twice thrice fource" in it:

var op opt.Optional[string] = opt.Something("once twice thrice fource")

And, for example, here is an optional-type with the uint8 101 in it:

var op opt.Optional[uint8] = opt.Something(uint8(101))

func Then

func Then[T1 any, T2 any](op Optional[T1], fn func(T1) Optional[T2]) Optional[T2]

Then applies the function ‘fn’ to the value inside of the optional-type ‘op’, if the optional-type ‘op’ is holding something, and returns the resulting optional-type. If the optional-type ‘op’ is holding nothing, then Then also returns nothing.

For example:

fn := func(s string) opt.Optional[byte] {

	if len(s) < 2 {
		return opt.Nothing[byte]()
	}

	return opt.Something[byte](s[1])
}

var op opt.Optional[string] = opt.Something("Hello world!"")

var result opt.Optional[byte] = opt.Then(op, fn)

// result == opt.Something[byte]('e')

// ...

var op2 opt.Optional[string] = opt.Something[string]("X")

var result2 opt.Optional[byte] = opt.Then(op, fn)

// result2 == opt.Nothing[byte]()

// ...

var op2 opt.Optional[string] = opt.Nothing[string]()

var result2 opt.Optional[byte] = opt.Then(op, fn)

// result2 == opt.Nothing[byte]()

func (Optional[T]) Filter

func (receiver Optional[T]) Filter(fn func(T) bool) Optional[T]

Filter returns itself if it is holding something and ‘fn’ applied to its value returns true. Else it return nothing.

For example:

fn := func(value int) bool {
	return 0 == (value % 2)
}

// ...

var op1 opt.Optional[int] = opt.Something[int](10)

op1 = op1.Filter(fn)

// ...

var op2 opt.Optional[int] = opt.Something[int](11)

op2 = op2.Filter(fn)

// ...

var op3 opt.Optional[int] = opt.Nothing[int]()

op3 = op3.Filter(fn)

func (Optional[T]) Get

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

Get returns the value inside of the optional-type if it is holding something.

Example usage:

var op opt.Optional[string]

// ...

value, found := op.Get()

if found {
	fmt.Println("VALUE:", value)
} else {
	fmt.Println("nothing")
}

func (Optional[T]) GetElse

func (receiver Optional[T]) GetElse(alternative T) T

GetElse returns the value inside of the optional-type if it is holding something. Else it returns the alternstive value passed as a parameter. Example usage:

var op opt.Optional[string]

// ...

value := op.GetElse(alternative)

if found {
	fmt.Println("VALUE:", value)
} else {
	fmt.Println("nothing")
}

func (Optional[T]) GoString

func (receiver Optional[T]) GoString() string

GoString makes it that when the fmt.Fprintf(), fmt.Printf(), and fmt.Sprintf() family of functions renders this type with the %#v verb, that it will be easier to understand.

For example:

var op opt.Optional[string] = opt.Something("once twice thrice fource")

// ...

fmt.Printf("op = %#v", op)

// Output:
// op = opt.Something[string]("once twice thrice fource")

Also, for example:

var op opt.Optional[uint8] = opt.Nothing[uint8]()

// ...

fmt.Printf("op = %#v", op)

// Output:
// op = opt.Nothing[uint8]()

func (Optional[T]) IsNothing

func (receiver Optional[T]) IsNothing() bool

func (Optional[T]) IsSomething

func (receiver Optional[T]) IsSomething() bool

func (Optional[T]) MarshalJSON

func (receiver Optional[T]) MarshalJSON() ([]byte, error)

MarshalJSON makes it so json.Marshaler is implemented.

func (*Optional[T]) UnmarshalJSON

func (receiver *Optional[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON makes it so json.Unmarshaler is implemented.

func (Optional[T]) WhenNothing

func (receiver Optional[T]) WhenNothing(fn func())

WhenNothing will call ‘fn’ when ‘receiver’ is holding nothing.

It will not call ‘fn’ when ‘receier’ is hold something.

For example:

var op opt.Optional = opt.Nothing[string]

// ...

op.WhenNothing(func(){
	//@TODO
})

func (Optional[T]) WhenSomething

func (receiver Optional[T]) WhenSomething(fn func(T))

WhenSomething will ‘fn’ when ‘receiver’ is holding something. The value that ‘receiver’ is holding will be passed as a parameter to the function ‘fn’.

It will not call ‘fn’ when ‘receiver’ is hold nothing.

For example:

var op opt.Optional = opt.Something("once twice thrice fource")

// ...

op.WhenSomething(func(value string){
	//@TODO
})