返回一个包含非空值的Optional。
+ +函数签名: + +```go +func Of[T any](value T) Optional[T] +``` +示例: + +```go +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 + +返回一个包含给定值的Optional，该值可能为空 (nil)。
+ +函数签名: + +```go +func OfNullable[T any](value *T) Optional[T] +``` +示例: + +```go +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 + +返回一个空Optional实例。
+ +函数签名: + +```go +func Empty[T any]() Optional[T] +``` +示例: + +```go +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 + +验证Optional是否为空。
+ +函数签名: + +```go +func (o Optional[T]) IsEmpty() bool +``` +示例: + +```go +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 + +检查当前Optional内是否存在值。
+ +函数签名: + +```go +func (o Optional[T]) IsPresent() bool +``` +示例: + +```go +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 + +如果值存在，则使用action方法执行给定的操作。
+ +函数签名: + +```go +func (o Optional[T]) IfPresent(action func(value T)) +``` +示例: + +```go +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 + +根据是否存在值执行相应的操作：有值则执行指定操作，没有值则执行默认操作。
+ +函数签名: + +```go +func (o Optional[T]) IfPresentOrElse(action func(value T), emptyAction func()) +``` +示例: + +```go +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 +如果存在，返回该值，否则引发panic。
+ +函数签名: + +```go +func (o Optional[T]) Get() T +``` +示例: + +```go +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 +检查Optional值是否存在，如果存在，则直接返回该值。如果不存在，返回参数other值。
+ +函数签名: + +```go +func (o Optional[T]) OrElse(other T) T +``` +示例: + +```go +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 +检查Optional值是否存在，如果存在，则直接返回该值。如果不存在，则调用一个提供的函数 (supplier)，并返回该函数的执行结果。
+ +函数签名: + +```go +func (o Optional[T]) OrElseGet(supplier func() T) T +``` +示例: + +```go +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 +检查Optional值是否存在，如果存在，则直接返回该值，否则返回错误。
+ +函数签名: + +```go +func (o Optional[T]) OrElseThrow(errorSupplier func() error) (T, error) +``` +示例: + +```go +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 +} +``` \ No newline at end of file diff --git a/docs/en/api/packages/datastructure/optional.md b/docs/en/api/packages/datastructure/optional.md new file mode 100644 index 00000000..fb34a1d0 --- /dev/null +++ b/docs/en/api/packages/datastructure/optional.md @@ -0,0 +1,416 @@ +# 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](https://github.com/duke-git/lancet/blob/main/datastructure/optional/optional.go) + + + + +## Usage +```go +import ( + optional "github.com/duke-git/lancet/v2/datastructure/optional" +) +``` + + + +## Index + +- [Of](#Of) +- [OfNullable](#OfNullable) +- [Empty](#Empty) +- [IsPresent](#IsPresent) +- [IsEmpty](#IsEmpty) +- [IfPresent](#IfPresent) +- [IfPresentOrElse](#IfPresentOrElse) +- [Get](#Get) +- [OrElse](#OrElse) +- [OrElseGet](#OrElseGet) +- [OrElseThrow](#OrElseThrow) + + + + + +## Documentation + +### Of +Returns an Optional with a non-nil value.
+ +Signature: + +```go +func Of[T any](value T) Optional[T] +``` +Example: + +```go +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: + +```go +func OfNullable[T any](value *T) Optional[T] +``` +Example: + +```go +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: + +```go +func Empty[T any]() Optional[T] +``` +Example: + +```go +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: + +```go +func (o Optional[T]) IsEmpty() bool +``` +Example: + +```go +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: + +```go +func (o Optional[T]) IsPresent() bool +``` +Example: + +```go +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: + +```go +func (o Optional[T]) IfPresent(action func(value T)) +``` +Example: + +```go +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: + +```go +func (o Optional[T]) IfPresentOrElse(action func(value T), emptyAction func()) +``` +Example: + +```go +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: + +```go +func (o Optional[T]) Get() T +``` +Example: + +```go +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: + +```go +func (o Optional[T]) OrElse(other T) T +``` +Example: + +```go +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: + +```go +func (o Optional[T]) OrElseGet(supplier func() T) T +``` +Example: + +```go +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: + +```go +func (o Optional[T]) OrElseThrow(errorSupplier func() error) (T, error) +``` +Example: + +```go +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 +} +``` \ No newline at end of file