From da24bae6b4038ae59c9a628dfe09efd597e23d92 Mon Sep 17 00:00:00 2001 From: dudaodong Date: Tue, 20 Feb 2024 11:22:39 +0800 Subject: [PATCH] doc: add doc for Optional type --- docs/api/packages/datastructure/optional.md | 422 ++++++++++++++++++ .../en/api/packages/datastructure/optional.md | 416 +++++++++++++++++ 2 files changed, 838 insertions(+) create mode 100644 docs/api/packages/datastructure/optional.md create mode 100644 docs/en/api/packages/datastructure/optional.md diff --git a/docs/api/packages/datastructure/optional.md b/docs/api/packages/datastructure/optional.md new file mode 100644 index 00000000..18074049 --- /dev/null +++ b/docs/api/packages/datastructure/optional.md @@ -0,0 +1,422 @@ +# Optional +Optional类型代表一个可选的值，它要么包含一个实际值，要么为空。 + +
+ +## 源码 + +- [https://github.com/duke-git/lancet/blob/main/datastructure/optional/optional.go](https://github.com/duke-git/lancet/blob/main/datastructure/optional/optional.go) + + +
+ +## 用法 +```go +import ( + optional "github.com/duke-git/lancet/v2/datastructure/optional" +) +``` + +
+ +## 目录 + +- [Of](#Of) +- [OfNullable](#OfNullable) +- [Empty](#Empty) +- [IsPresent](#IsPresent) +- [IsEmpty](#IsEmpty) +- [IfPresent](#IfPresent) +- [IfPresentOrElse](#IfPresentOrElse) +- [Get](#Get) +- [OrElse](#OrElse) +- [OrElseGet](#OrElseGet) +- [OrElseThrow](#OrElseThrow) + + + +
+ +## 文档 + +### Of +

返回一个包含非空值的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