lancet/docs/en/api/packages/datastructure/optional.md

Optional

Optional is a type that may or may not contain a non-nil value.

Source

• https://github.com/duke-git/lancet/blob/main/datastructure/optional/optional.go

Usage

import (
    optional "github.com/duke-git/lancet/v2/datastructure/optional"
)

Index

• Of
• OfNullable
• Empty
• IsPresent
• IsEmpty
• IfPresent
• IfPresentOrElse
• Get
• OrElse
• OrElseGet
• OrElseThrow

Documentation

Of

Returns an Optional with a non-nil value.

Signature:

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

Example:

package main

import (
    "fmt"
    optional "github.com/duke-git/lancet/v2/datastructure/optional"
)

func main() {
    value := 42
    opt := optional.Of(value)

    fmt.Println(opt.Get())

    // Output:
    // 42
}

OfNullable

Returns an Optional for a given value, which may be nil.

Signature:

func OfNullable[T any](value *T) Optional[T]

Example:

package main

import (
    "fmt"
    optional "github.com/duke-git/lancet/v2/datastructure/optional"
)

func main() {
    var value *int = nil
    opt := optional.OfNullable(value)

    fmt.Println(opt.IsPresent())

    value = new(int)
    *value = 42
    opt = optional.OfNullable(value)

    fmt.Println(opt.IsPresent())


    // Output:
    // false
    // true
}

Empty

Returns an empty Optional instance.

Signature:

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

Example:

package main

import (
    "fmt"
    optional "github.com/duke-git/lancet/v2/datastructure/optional"
)

func main() {
    optEmpty := OfNullable.Empty[int]()
    fmt.Println(optEmpty.IsEmpty())

    // Output:
    // true
}

IsEmpty

Checks if the Optional is empty.

Signature:

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

Example:

package main

import (
    "fmt"
    optional "github.com/duke-git/lancet/v2/datastructure/optional"
)

func main() {
    optEmpty := OfNullable.Empty[int]()
    fmt.Println(optEmpty.IsEmpty())

    // Output:
    // true
}

IsPresent

Checks if there is a value present.

Signature:

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

Example:

package main

import (
    "fmt"
    optional "github.com/duke-git/lancet/v2/datastructure/optional"
)

func main() {
    var value *int = nil
    opt := optional.OfNullable(value)

    fmt.Println(opt.IsPresent())

    value = new(int)
    *value = 42
    opt = optional.OfNullable(value)

    fmt.Println(opt.IsPresent())


    // Output:
    // false
    // true
}

IfPresent

Performs the given action with the value if a value is present.

Signature:

func (o Optional[T]) IfPresent(action func(value T))

Example:

package main

import (
    "fmt"
    optional "github.com/duke-git/lancet/v2/datastructure/optional"
)

func main() {
    called := false
    action := func(value int) { called = true }

    optEmpty := optional.Empty[int]()
    optEmpty.IfPresent(action)

    fmt.Println(called)

    called = false // Reset for next test
    optWithValue := optional.Of(42)
    optWithValue.IfPresent(action)

    fmt.Println(optWithValue.IsPresent())

    // Output:
    // false
    // true
}

IfPresentOrElse

Performs the action with the value if present, otherwise performs the empty-based action.

Signature:

func (o Optional[T]) IfPresentOrElse(action func(value T), emptyAction func())

Example:

package main

import (
    "fmt"
    optional "github.com/duke-git/lancet/v2/datastructure/optional"
)

func main() {
    calledWithValue := false
    valueAction := func(value int) { calledWithValue = true }
    emptyAction := func() { t.Errorf("Empty action should not be called when value is present") }

    optWithValue := optional.Of(42)
    optWithValue.IfPresentOrElse(valueAction, emptyAction)

    fmt.Println(calledWithValue)

    calledWithEmpty := false
    valueAction = func(value int) { t.Errorf("Value action should not be called when value is not present") }
    emptyAction = func() { calledWithEmpty = true }

    optEmpty := optional.Empty[int]()
    optEmpty.IfPresentOrElse(valueAction, emptyAction)

    fmt.Println(calledWithEmpty)

    // Output:
    // true
    // true
}

Get

Returns the value if present, otherwise panics.

Signature:

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

Example:

package main

import (
    "fmt"
    optional "github.com/duke-git/lancet/v2/datastructure/optional"
)

func main() {
    value := 42
    opt := optional.Of(value)

    fmt.Println(opt.Get())

    // Output:
    // 42
}

OrElse

Returns the value if present, otherwise returns other.

Signature:

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

Example:

package main

import (
    "fmt"
    optional "github.com/duke-git/lancet/v2/datastructure/optional"
)

func main() {
    optEmpty := optional.Empty[int]()
    val := optEmpty.OrElse(100)
    fmt.Println(val)

    optWithValue := optional.Of(42)
    val = optWithValue.OrElse(100)
    fmt.Println(val)

    // Output:
    // 100
    // 42
}

OrElseGet

Returns the value if present, otherwise invokes supplier and returns the result.

Signature:

func (o Optional[T]) OrElseGet(supplier func() T) T

Example:

package main

import (
    "fmt"
    optional "github.com/duke-git/lancet/v2/datastructure/optional"
)

func main() {
    optEmpty := optional.Empty[int]()
    supplier := func() int { return 100 }

    val := optEmpty.OrElseGet(supplier)
    fmt.Println(val)

    // Output:
    // 100
}

OrElseThrow

Returns the value if present, otherwise returns an error.

Signature:

func (o Optional[T]) OrElseThrow(errorSupplier func() error) (T, error)

Example:

package main

import (
    "fmt"
    optional "github.com/duke-git/lancet/v2/datastructure/optional"
)

func main() {
    optEmpty := optional.Empty[int]()
    _, err := optEmpty.OrElseThrow(func() error { return errors.New("no value") })
    
    fmt.Println(err.Error())

    optWithValue := optional.Of(42)
    val, err := optWithValue.OrElseThrow(func() error { return errors.New("no value") })

    fmt.Println(val)
    fmt.Println(err)

    // Output:
    // no value
    // 42
    // nil
}