集合类型-方法介绍

以下常用方法列表，文档更新可能滞后于代码新特性，更多的方法及示例请参考代码文档：https://pkg.go.dev/github.com/gogf/gf/v2/container/gset

这里以StrSet类型介绍方法使用，其他集合类型的方法与此类似，不再赘述。

NewStrSet

• 说明：NewStrSet创建并返回一个空的集合，其中包含没有重复字符串的数据。参数safe用于指定是否在并发安全中使用，默认情况下是false。
• 格式：

func NewStrSet(safe ...bool) *StrSet

• 示例：

func ExampleNewStrSet() {
    strSet := gset.NewStrSet(true)
    strSet.Add([]string{"str1", "str2", "str3"}...)
    fmt.Println(strSet.Slice())

    // May Output:
    // [str3 str1 str2]
}

NewStrSetFrom

• 说明：NewStrSetFrom通过给定的数组创建集合集合。参数safe用于指定是否在并发安全中使用，默认情况下是false。
• 格式：

func NewStrSetFrom(items []string, safe ...bool) *StrSet

• 示例：

func ExampleNewStrSetFrom() {
    strSet := gset.NewStrSetFrom([]string{"str1", "str2", "str3"}, true)
    fmt.Println(strSet.Slice())

    // May Output:
    // [str1 str2 str3]
}

Add

• 说明：Add添加一个或多个元素项到集合中。
• 格式：

func (set *StrSet) Add(item ...string)

• 示例：

func ExampleStrSet_Add() {
    strSet := gset.NewStrSetFrom([]string{"str1", "str2", "str3"}, true)
    strSet.Add("str")
    fmt.Println(strSet.Slice())
    fmt.Println(strSet.AddIfNotExist("str"))

    // Mya Output:
    // [str str1 str2 str3]
    // false
}

AddIfNotExist

• 说明：Addifnotexist检查集合中是否存在指定元素项item，如果不存在则将item添加到集合中并返回true，否则什么也不做并返回false。
• 格式：

func (set *StrSet) AddIfNotExist(item string) bool

• 示例：

func ExampleStrSet_AddIfNotExist() {
    strSet := gset.NewStrSetFrom([]string{"str1", "str2", "str3"}, true)
    strSet.Add("str")
    fmt.Println(strSet.Slice())
    fmt.Println(strSet.AddIfNotExist("str"))

    // Mya Output:
    // [str str1 str2 str3]
    // false
}

AddIfNotExistFunc

• 说明： AddIfNotExistFunc检查集合中存在指定元素项item，如果不存在并且方法f返回true时，则将item设置到集合中并返回true，否则什么也不做并返回false。
• 格式：

func (set *StrSet) AddIfNotExistFunc(item string, f func() bool) bool

• 示例：

func ExampleStrSet_AddIfNotExistFunc() {
    strSet := gset.NewStrSetFrom([]string{"str1", "str2", "str3"}, true)
    strSet.Add("str")
    fmt.Println(strSet.Slice())
    fmt.Println(strSet.AddIfNotExistFunc("str5", func() bool {
        return true
    }))

    // May Output:
    // [str1 str2 str3 str]
    // true
}

AddIfNotExistFuncLock

• 说明： AddifnotExistFuncLock与AddIfNotExistFunc类似，不过当多个goroutine同时调用AddifnotExistFuncLock方法时，内部使用并发安全锁机制保证同时只能一个goroutine执行。该方法只有在创建集合时的safe参数设置true时有效，否则表现和方法一致AddIfNotExistFunc。
• 格式：

func (set *StrSet) AddIfNotExistFuncLock(item string, f func() bool) bool

• 示例：

func ExampleStrSet_AddIfNotExistFuncLock() {
    strSet := gset.NewStrSetFrom([]string{"str1", "str2", "str3"}, true)
    strSet.Add("str")
    fmt.Println(strSet.Slice())
    fmt.Println(strSet.AddIfNotExistFuncLock("str4", func() bool {
        return true
    }))

    // May Output:
    // [str1 str2 str3 str]
    // true
}

Clear

• 说明：Clear 删除集合的所有元素项。
• 格式：

func (set *StrSet) Clear()

• 示例：

func ExampleStrSet_Clear() {
    strSet := gset.NewStrSetFrom([]string{"str1", "str2", "str3"}, true)
    fmt.Println(strSet.Size())
    strSet.Clear()
    fmt.Println(strSet.Size())

    // Output:
    // 3
    // 0
}

Intersect

• 说明：Intrersect 执行集合set与others的交集，并返回一个新的集合newSet，在newSet中的元素项同时存在于集合set与others中。
• 格式：

func (set *StrSet) Intersect(others ...*StrSet) (newSet *StrSet)

• 示例：

func ExampleStrSet_Intersect() {
    s1 := gset.NewStrSet(true)
    s1.Add([]string{"a", "b", "c"}...)
    var s2 gset.StrSet
    s2.Add([]string{"a", "b", "c", "d"}...)
    fmt.Println(s2.Intersect(s1).Slice())

    // May Output:
    // [c a b]
}

Diff

• 说明：Diff 执行集合set与others差集操作，并返回一个新的集合newSet。在newSet中的元素项存在于set但不存在于集合others。注意，参数others可以指定多个集合参数。
• 格式：

func (set *StrSet) Diff(others ...*StrSet) (newSet *StrSet)

• 示例：

func ExampleStrSet_Diff() {
    s1 := gset.NewStrSetFrom([]string{"a", "b", "c"}, true)
    s2 := gset.NewStrSetFrom([]string{"a", "b", "c", "d"}, true)
    fmt.Println(s2.Diff(s1).Slice())

    // Output:
    // [d]
}

Union

• 说明：union执行集合set与others的并集操作，并返回一个新的集合newSet。
• 格式：

func (set *StrSet) Union(others ...*StrSet) (newSet *StrSet)

• 示例：

func ExampleStrSet_Union() {
    s1 := gset.NewStrSet(true)
    s1.Add([]string{"a", "b", "c", "d"}...)
    s2 := gset.NewStrSet(true)
    s2.Add([]string{"a", "b", "d"}...)
    fmt.Println(s1.Union(s2).Slice())

    // May Output:
    // [a b c d]
}

Complement

• 说明：Complement 执行set与full的补集操作，并返回一个新集合newSet。
• 格式：

func (set *StrSet) Complement(full *StrSet) (newSet *StrSet)

• 示例：

func ExampleStrSet_Complement() {
    strSet := gset.NewStrSetFrom([]string{"str1", "str2", "str3", "str4", "str5"}, true)
    s := gset.NewStrSetFrom([]string{"str1", "str2", "str3"}, true)
    fmt.Println(s.Complement(strSet).Slice())

    // May Output:
    // [str4 str5]
}

Contains

• 说明：Contains 包含检查集是否包含item。
• 格式：

func (set *StrSet) Contains(item string) bool

• 示例：

func ExampleStrSet_Contains() {
    var set gset.StrSet
    set.Add("a")
    fmt.Println(set.Contains("a"))
    fmt.Println(set.Contains("A"))

    // Output:
    // true
    // false
}

ContainsI

• 说明： ContainsI方法类似于Contains，只是它不区分大小写比较大小。
• 格式：

func (set *StrSet) ContainsI(item string) bool

• 示例：

func ExampleStrSet_ContainsI() {
    var set gset.StrSet
    set.Add("a")
    fmt.Println(set.ContainsI("a"))
    fmt.Println(set.ContainsI("A"))

    // Output:
    // true
    // true
}

Equal

• 说明： Equal检查两个集合是否完全相等（包括大小以及元素项）。
• 格式：

func (set *StrSet) Equal(other *StrSet) bool

• 示例：

func ExampleStrSet_Equal() {
    s1 := gset.NewStrSetFrom([]string{"a", "b", "c"}, true)
    s2 := gset.NewStrSetFrom([]string{"a", "b", "c", "d"}, true)
    fmt.Println(s2.Equal(s1))

    s3 := gset.NewStrSetFrom([]string{"a", "b", "c"}, true)
    s4 := gset.NewStrSetFrom([]string{"a", "b", "c"}, true)
    fmt.Println(s3.Equal(s4))

    // Output:
    // false
    // true
}

IsSubSetOf

• 说明：IsSumSetOf检查当前集合set是否是指定集合other的子集。
• 格式：

func (set *StrSet) IsSubsetOf(other *StrSet) bool

• 示例：

func ExampleStrSet_IsSubsetOf() {
    s1 := gset.NewStrSet(true)
    s1.Add([]string{"a", "b", "c", "d"}...)
    var s2 gset.StrSet
    s2.Add([]string{"a", "b", "d"}...)
    fmt.Println(s2.IsSubsetOf(s1))

    // Output:
    // true
}

Iterator

• 说明：Iterator 迭代器通过给定的回调函数f随机遍历当前集合set，如果方法f返回true，则继续遍历，否则停止。
• 格式：

func (set *StrSet) Iterator(f func(v string) bool)

• 示例：

func ExampleStrSet_Iterator() {
    s1 := gset.NewStrSet(true)
    s1.Add([]string{"a", "b", "c", "d"}...)
    s1.Iterator(func(v string) bool {
        fmt.Println("Iterator", v)
        return true
    })

    // May Output:
    // Iterator a
    // Iterator b
    // Iterator c
    // Iterator d
}

Join

• 说明：Join 将集合中的元素项通过字符串glue拼接成新的字符串返回。
• 格式：

func (set *StrSet) Join(glue string) string

• 示例：

func ExampleStrSet_Join() {
    s1 := gset.NewStrSet(true)
    s1.Add([]string{"a", "b", "c", "d"}...)
    fmt.Println(s1.Join(","))

    // May Output:
    // b,c,d,a
}

LockFunc

• 说明：LockFunc 仅在并发安全场景下有用，该方法通过写锁锁定集合set，并执行回调方法f。
• 格式：

func (set *StrSet) LockFunc(f func(m map[string]struct{}))

• 示例：

func ExampleStrSet_LockFunc() {
    s1 := gset.NewStrSet(true)
    s1.Add([]string{"1", "2"}...)
    s1.LockFunc(func(m map[string]struct{}) {
        m["3"] = struct{}{}
    })
    fmt.Println(s1.Slice())

    // May Output
    // [2 3 1]

}

RLockFunc

• 说明：RLockFunc 仅在并发安全场景下有用，该方法通过读锁锁定集合set，并执行回调方法f。
• 格式：

func (set *StrSet) RLockFunc(f func(m map[string]struct{}))

• 示例：

func ExampleStrSet_RLockFunc() {
    s1 := gset.NewStrSet(true)
    s1.Add([]string{"a", "b", "c", "d"}...)
    s1.RLockFunc(func(m map[string]struct{}) {
        fmt.Println(m)
    })

    // Output:
    // map[a:{} b:{} c:{} d:{}]
}

Merge

• 说明：Merge将集合others中的所有元素项合并到set中。
• 格式：

func (set *StrSet) Merge(others ...*StrSet) *StrSet

• 示例：

func ExampleStrSet_Merge() {
    s1 := gset.NewStrSet(true)
    s1.Add([]string{"a", "b", "c", "d"}...)

    s2 := gset.NewStrSet(true)
    fmt.Println(s1.Merge(s2).Slice())

    // May Output:
    // [d a b c]
}

Pop

• 说明：Pop随机从集合中取出一个元素项。
• 格式：

func (set *StrSet) Pop() string

• 示例：

func ExampleStrSet_Pop() {
    s1 := gset.NewStrSet(true)
    s1.Add([]string{"a", "b", "c", "d"}...)

    fmt.Println(s1.Pop())

    // May Output:
    // a
}

Pops

• 说明：Pops 从集合中随机弹出size个元素项。如果size == -1，则返回所有元素项。
• 格式：

func (set *StrSet) Pops(size int) []string

• 示例：

func ExampleStrSet_Pops() {
    s1 := gset.NewStrSet(true)
    s1.Add([]string{"a", "b", "c", "d"}...)
    for _, v := range s1.Pops(2) {
        fmt.Println(v)
    }

    // May Output:
    // a
    // b
}

Remove

• 说明：Remove从集合中删除指定的元素项item。
• 格式：

func (set *StrSet) Remove(item string)

• 示例：

func ExampleStrSet_Remove() {
    s1 := gset.NewStrSet(true)
    s1.Add([]string{"a", "b", "c", "d"}...)
    s1.Remove("a")
    fmt.Println(s1.Slice())

    // May Output:
    // [b c d]
}

Size

• 说明：Size返回集合的大小。
• 格式：

func (set *StrSet) Size() int

• 示例：

func ExampleStrSet_Size() {
    s1 := gset.NewStrSet(true)
    s1.Add([]string{"a", "b", "c", "d"}...)
    fmt.Println(s1.Size())

    // Output:
    // 4
}

Silce

• 说明：Slice将集合中的元素项以slice的形式返回。
• 格式：

func (set *StrSet) Slice() []string

• 示例：

func ExampleStrSet_Slice() {
    s1 := gset.NewStrSet(true)
    s1.Add([]string{"a", "b", "c", "d"}...)
    fmt.Println(s1.Slice())

    // May Output:
    // [a,b,c,d]
}

String

• 说明：String将集合按照字符串返回。
• 格式：

func (set *StrSet) String() string

• 示例：

func ExampleStrSet_String() {
    s1 := gset.NewStrSet(true)
    s1.Add([]string{"a", "b", "c", "d"}...)
    fmt.Println(s1.String())

    // May Output:
    // "a","b","c","d"
}

Sum

• 说明：Sum将集合中的元素项执行求和，注意：只有元素项为数字时才有效，否则您将得到一个意想不到的结果。
• 格式：

func (set *StrSet) Sum() (sum int)

• 示例：

func ExampleStrSet_Sum() {
    s1 := gset.NewStrSet(true)
    s1.Add([]string{"1", "2", "3", "4"}...)
    fmt.Println(s1.Sum())

    // Output:
    // 10
}

Walk

• 说明：Walk按照用户给定的回调方法f遍历当前集合，并将f的返回结果重新设置当前集合。注意，在并发安全场景中，该方法内部使用写锁来保证并发安全性。
• 格式：

func (set *StrSet) Walk(f func(item string) string) *StrSet

• 示例：

func ExampleStrSet_Walk() {
    var (
        set    gset.StrSet
        names  = g.SliceStr{"user", "user_detail"}
        prefix = "gf_"
    )
    set.Add(names...)
    // Add prefix for given table names.
    set.Walk(func(item string) string {
        return prefix + item
    })
    fmt.Println(set.Slice())

    // May Output:
    // [gf_user gf_user_detail]
}

MarshalJSON

• 说明：MarshalJSON实现了json.Marshal的MarshalJSON接口。
• 格式：

func (set *StrSet) MarshalJSON() ([]byte, error)

• 示例：

func ExampleStrSet_MarshalJSON() {
    type Student struct {
        Id     int
        Name   string
        Scores *gset.StrSet
    }
    s := Student{
        Id:     1,
        Name:   "john",
        Scores: gset.NewStrSetFrom([]string{"100", "99", "98"}, true),
    }
    b, _ := json.Marshal(s)
    fmt.Println(string(b))

    // May Output:
    // {"Id":1,"Name":"john","Scores":["100","99","98"]}
}

UnmarshalJSON

• 说明：UnmarshalJSON实现了json.Unmarshal中的UnmarshalJSON接口。
• 格式：

func (set *StrSet) UnmarshalJSON(b []byte) error

• 示例：

func ExampleStrSet_UnmarshalJSON() {
    b := []byte(`{"Id":1,"Name":"john","Scores":["100","99","98"]}`)
    type Student struct {
        Id     int
        Name   string
        Scores *gset.StrSet
    }
    s := Student{}
    json.Unmarshal(b, &s)
    fmt.Println(s)

    // May Output:
    // {1 john "99","98","100"}
}

UnmarshalValue

• 说明： UnfarshalValue实现goframe框架内部统一的设置接口，它通过一个interface{}类型的参数初始化当前对象，至于interface{}参数的使用逻辑由该接口实现方法决定。
• 格式：

func (set *StrSet) UnmarshalValue(value interface{}) (err error)

• 示例：

func ExampleStrSet_UnmarshalValue() {
    b := []byte(`{"Id":1,"Name":"john","Scores":["100","99","98"]}`)
    type Student struct {
        Id     int
        Name   string
        Scores *gset.StrSet
    }
    s := Student{}
    json.Unmarshal(b, &s)
    fmt.Println(s)

    // May Output:
    // {1 john "99","98","100"}
}