From 1718fd1cf1a4191a7bdc8c39b3451ae5ec12ff4c Mon Sep 17 00:00:00 2001 From: dudaodong Date: Tue, 5 Apr 2022 14:16:58 +0800 Subject: [PATCH] docs: add doc for maputil package --- docs/maputil.md | 304 ++++++++++++++++++++++++++++++++++++++++++ docs/maputil_zh-CN.md | 304 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 608 insertions(+) create mode 100644 docs/maputil.md create mode 100644 docs/maputil_zh-CN.md diff --git a/docs/maputil.md b/docs/maputil.md new file mode 100644 index 0000000..ce4b334 --- /dev/null +++ b/docs/maputil.md @@ -0,0 +1,304 @@ +# Maputil +Package maputil includes some functions to manipulate map. + +
+ +## Source: + +- [https://github.com/duke-git/lancet/blob/main/maputil/maputil.go](https://github.com/duke-git/lancet/blob/main/maputil/maputil.go) + + +
+ +## Example: +```go +import ( + "github.com/duke-git/lancet/v2/maputil" +) +``` + +
+ +## Index +- [ForEach](#ForEach) +- [Filter](#Filter) +- [Intersect](#Intersect) +- [Keys](#Keys) +- [Merge](#Merge) +- [Minus](#Minus) +- [Values](#Values) + +
+ +## Documentation + + + +### ForEach +

Executes iteratee funcation for every key and value pair in map.

+ +Signature: + +```go +func ForEach[K comparable, V any](m map[K]V, iteratee func(key K, value V)) +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/maputil" +) + +func main() { + m := map[string]int{ + "a": 1, + "b": 2, + "c": 3, + "d": 4, + } + + var sum int + + maputil.ForEach(m, func(_ string, value int) { + sum += value + }) + fmt.Println(sum) // 10 +} +``` + + + + +### Filter +

Iterates over map, return a new map contains all key and value pairs pass the predicate function.

+ +Signature: + +```go +func Filter[K comparable, V any](m map[K]V, predicate func(key K, value V) bool) map[K]V +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/maputil" +) + +func main() { + m := map[string]int{ + "a": 1, + "b": 2, + "c": 3, + "d": 4, + "e": 5, + } + isEven := func(_ string, value int) bool { + return value%2 == 0 + } + + maputil.Filter(m, func(_ string, value int) { + sum += value + }) + res := maputil.Filter(m, isEven) + fmt.Println(res) // map[string]int{"b": 2, "d": 4,} +} +``` + + + + +### Intersect +

Iterates over maps, return a new map of key and value pairs in all given maps.

+ +Signature: + +```go +func Intersect[K comparable, V any](maps ...map[K]V) map[K]V +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/maputil" +) + +func main() { + m1 := map[string]int{ + "a": 1, + "b": 2, + "c": 3, + } + + m2 := map[string]int{ + "a": 1, + "b": 2, + "c": 6, + "d": 7, + } + + m3 := map[string]int{ + "a": 1, + "b": 9, + "e": 9, + } + + fmt.Println(maputil.Intersect(m1)) // map[string]int{"a": 1, "b": 2, "c": 3} + + fmt.Println(maputil.Intersect(m1, m2)) // map[string]int{"a": 1, "b": 2} + + fmt.Println(maputil.Intersect(m1, m2, m3)) // map[string]int{"a": 1} +} +``` + + + + +### Keys +

Returns a slice of the map's keys.

+ +Signature: + +```go +func Keys[K comparable, V any](m map[K]V) []K +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/maputil" +) + +func main() { + m := map[int]string{ + 1: "a", + 2: "a", + 3: "b", + 4: "c", + 5: "d", + } + + keys := maputil.Keys(m) + sort.Ints(keys) + fmt.Println(keys) // []int{1, 2, 3, 4, 5} +} +``` + + + + +### Merge +

Merge maps, next key will overwrite previous key.

+ +Signature: + +```go +func Merge[K comparable, V any](maps ...map[K]V) map[K]V +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/maputil" +) + +func main() { + m1 := map[int]string{ + 1: "a", + 2: "b", + } + m2 := map[int]string{ + 1: "1", + 3: "2", + } + fmt.Println(maputil.Merge(m1, m2)) // map[int]string{1:"1", 2:"b", 3:"2",} +} +``` + + + + +### Minus +

Creates an map of whose key in mapA but not in mapB.

+ +Signature: + +```go +func Minus[K comparable, V any](mapA, mapB map[K]V) map[K]V +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/maputil" +) + +func main() { + m1 := map[string]int{ + "a": 1, + "b": 2, + "c": 3, + } + + m2 := map[string]int{ + "a": 11, + "b": 22, + "d": 33, + } + + fmt.Println(maputil.Minus(m1, m2)) //map[string]int{"c": 3} +} +``` + + + +### Values +

Returns a slice of the map's values.

+ +Signature: + +```go +func Values[K comparable, V any](m map[K]V) []V +``` +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/maputil" +) + +func main() { + m := map[int]string{ + 1: "a", + 2: "a", + 3: "b", + 4: "c", + 5: "d", + } + + values := maputil.Values(m) + sort.Strings(values) + + fmt.Println(values) // []string{"a", "a", "b", "c", "d"} +} +``` \ No newline at end of file diff --git a/docs/maputil_zh-CN.md b/docs/maputil_zh-CN.md new file mode 100644 index 0000000..5fed2f4 --- /dev/null +++ b/docs/maputil_zh-CN.md @@ -0,0 +1,304 @@ +# Maputil +maputil包包括一些操作map的函数。 + +
+ +## 源码: + +- [https://github.com/duke-git/lancet/blob/main/maputil/maputil.go](https://github.com/duke-git/lancet/blob/main/maputil/maputil.go) + + +
+ +## 用法: +```go +import ( + "github.com/duke-git/lancet/v2/maputil" +) +``` + +
+ +## 目录: +- [ForEach](#ForEach) +- [Filter](#Filter) +- [Intersect](#Intersect) +- [Keys](#Keys) +- [Merge](#Merge) +- [Minus](#Minus) +- [Values](#Values) + +
+ +## API文档: + + + +### ForEach +

对map中的每对key和value执行iteratee函数

+ +函数签名: + +```go +func ForEach[K comparable, V any](m map[K]V, iteratee func(key K, value V)) +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/maputil" +) + +func main() { + m := map[string]int{ + "a": 1, + "b": 2, + "c": 3, + "d": 4, + } + + var sum int + + maputil.ForEach(m, func(_ string, value int) { + sum += value + }) + fmt.Println(sum) // 10 +} +``` + + + + +### Filter +

迭代map中的每对key和value, 返回符合predicate函数的key, value

+ +函数签名: + +```go +func Filter[K comparable, V any](m map[K]V, predicate func(key K, value V) bool) map[K]V +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/maputil" +) + +func main() { + m := map[string]int{ + "a": 1, + "b": 2, + "c": 3, + "d": 4, + "e": 5, + } + isEven := func(_ string, value int) bool { + return value%2 == 0 + } + + maputil.Filter(m, func(_ string, value int) { + sum += value + }) + res := maputil.Filter(m, isEven) + fmt.Println(res) // map[string]int{"b": 2, "d": 4,} +} +``` + + + + +### Intersect +

多个map的交集操作

+ +函数签名: + +```go +func Intersect[K comparable, V any](maps ...map[K]V) map[K]V +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/maputil" +) + +func main() { + m1 := map[string]int{ + "a": 1, + "b": 2, + "c": 3, + } + + m2 := map[string]int{ + "a": 1, + "b": 2, + "c": 6, + "d": 7, + } + + m3 := map[string]int{ + "a": 1, + "b": 9, + "e": 9, + } + + fmt.Println(maputil.Intersect(m1)) // map[string]int{"a": 1, "b": 2, "c": 3} + + fmt.Println(maputil.Intersect(m1, m2)) // map[string]int{"a": 1, "b": 2} + + fmt.Println(maputil.Intersect(m1, m2, m3)) // map[string]int{"a": 1} +} +``` + + + + +### Keys +

返回map中所有key的切片

+ +函数签名: + +```go +func Keys[K comparable, V any](m map[K]V) []K +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/maputil" +) + +func main() { + m := map[int]string{ + 1: "a", + 2: "a", + 3: "b", + 4: "c", + 5: "d", + } + + keys := maputil.Keys(m) + sort.Ints(keys) + fmt.Println(keys) // []int{1, 2, 3, 4, 5} +} +``` + + + + +### Merge +

合并多个maps, 相同的key会被后来的key覆盖

+ +函数签名: + +```go +func Merge[K comparable, V any](maps ...map[K]V) map[K]V +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/maputil" +) + +func main() { + m1 := map[int]string{ + 1: "a", + 2: "b", + } + m2 := map[int]string{ + 1: "1", + 3: "2", + } + fmt.Println(maputil.Merge(m1, m2)) // map[int]string{1:"1", 2:"b", 3:"2",} +} +``` + + + + +### Minus +

返回一个map，其中的key存在于mapA，不存在于mapB.

+ +函数签名: + +```go +func Minus[K comparable, V any](mapA, mapB map[K]V) map[K]V +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/maputil" +) + +func main() { + m1 := map[string]int{ + "a": 1, + "b": 2, + "c": 3, + } + + m2 := map[string]int{ + "a": 11, + "b": 22, + "d": 33, + } + + fmt.Println(maputil.Minus(m1, m2)) //map[string]int{"c": 3} +} +``` + + + +### Values +

返回map中所有value的切片

+ +函数签名: + +```go +func Values[K comparable, V any](m map[K]V) []V +``` +例子: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/maputil" +) + +func main() { + m := map[int]string{ + 1: "a", + 2: "a", + 3: "b", + 4: "c", + 5: "d", + } + + values := maputil.Values(m) + sort.Strings(values) + + fmt.Println(values) // []string{"a", "a", "b", "c", "d"} +} +``` \ No newline at end of file