tip

The following is a list of common methods. The documentation may lag behind new features in the code. For more methods and examples, please refer to the code documentation: https://pkg.go.dev/github.com/gogf/gf/v2/container/gset

tip

The usage of methods is introduced using the StrSet type; methods for other set types are similar and will not be repeated.

NewStrSet

• Description: NewStrSet creates and returns an empty set that contains unique string data. The safe parameter specifies whether to use in concurrent safety, with a default value of false.
• Signature:

func NewStrSet(safe ...bool) *StrSet

• Example:

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

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

NewStrSetFrom

• Description: NewStrSetFrom creates a set from a given array. The safe parameter specifies whether to use in concurrent safety, with a default value of false.
• Signature:

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

• Example:

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

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

Add

• Description: Add adds one or more elements to the set.
• Signature:

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

• Example:

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

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

AddIfNotExist

• Description: AddIfNotExist checks if the specified element item exists in the set. If it does not exist, it adds item to the set and returns true; otherwise, it does nothing and returns false.
• Signature:

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

• Example:

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

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

AddIfNotExistFunc

• Description: AddIfNotExistFunc checks if the specified element item exists in the set. If it does not exist and the function f returns true, it sets item into the set and returns true; otherwise, it does nothing and returns false.
• Signature:

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

• Example:

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

• Description: AddIfNotExistFuncLock is similar to AddIfNotExistFunc, but when multiple goroutines simultaneously call AddIfNotExistFuncLock, it uses a concurrent safety lock mechanism to ensure that only one goroutine executes at a time. This method is effective only if the safe parameter is set to true when creating the set; otherwise, it behaves like the AddIfNotExistFunc method.
• Signature:

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

• Example:

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

• Description: Clear removes all elements from the set.
• Signature:

func (set *StrSet) Clear()

• Example:

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

• Description: Intersect performs an intersection operation between the set set and others, returning a new set newSet where the elements exist in both set and others.
• Signature:

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

• Example:

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

• Description: Diff performs a difference operation between the set set and others, returning a new set newSet. The elements in newSet exist in set but not in others. Note that others can specify multiple set parameters.
• Signature:

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

• Example:

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

• Description: Union performs a union operation between the set set and others, returning a new set newSet.
• Signature:

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

• Example:

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

• Description: Complement performs a complement operation between set and full, returning a new set newSet.
• Signature:

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

• Example:

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

• Description: Contains checks if the set contains item.
• Signature:

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

• Example:

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

      // Output:
      // true
      // false
}

ContainsI

• Description: ContainsI is similar to Contains, but it performs a case-insensitive comparison.
• Signature:

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

• Example:

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

      // Output:
      // true
      // true
}

Equal

• Description: Equal checks whether two sets are completely equal (including size and elements).
• Signature:

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

• Example:

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

• Description: IsSubsetOf checks whether the current set set is a subset of the specified set other.
• Signature:

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

• Example:

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

• Description: Iterator iterates over the current set set using the given callback function f. If the function f returns true, it continues iteration; otherwise, it stops.
• Signature:

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

• Example:

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

• Description: Join concatenates the elements of the set into a new string using glue.
• Signature:

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

• Example:

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

• Description: LockFunc is useful only in concurrent safety scenarios. It locks the set set with a write lock and executes the callback function f.
• Signature:

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

• Example:

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

• Description: RLockFunc is useful only in concurrent safety scenarios. It locks the set set with a read lock and executes the callback function f.
• Signature:

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

• Example:

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

• Description: Merge merges all elements from the others sets into set.
• Signature:

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

• Example:

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

• Description: Pop randomly retrieves an element from the set.
• Signature:

func (set *StrSet) Pop() string

• Example:

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

      fmt.Println(s1.Pop())

      // May Output:
      // a
}

Pops

• Description: Pops randomly pops size number of elements from the set. If size == -1, it returns all elements.
• Signature:

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

• Example:

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

• Description: Remove removes the specified element item from the set.
• Signature:

func (set *StrSet) Remove(item string)

• Example:

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

• Description: Size returns the size of the set.
• Signature:

func (set *StrSet) Size() int

• Example:

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

      // Output:
      // 4
}

Silce

• Description: Slice returns the elements of the set as a slice.
• Signature:

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

• Example:

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

• Description: String returns the set as a string.
• Signature:

func (set *StrSet) String() string

• Example:

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

• Description: Sum sums up the elements of the set. Note: It is valid only when the elements are numbers; otherwise, you will get an unexpected result.
• Signature:

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

• Example:

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

      // Output:
      // 10
}

Walk

• Description: Walk traverses the current set with the user-provided callback function f, and resets the current set with the return results of f. Note, in a concurrent safety scenario, this method uses a write lock internally to ensure safety.
• Signature:

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

• Example:

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

• Description: MarshalJSON implements the MarshalJSON interface of json.Marshal.
• Signature:

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

• Example:

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

• Description: UnmarshalJSON implements the UnmarshalJSON interface of json.Unmarshal.
• Signature:

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

• Example:

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

• Description: UnmarshalValue implements the internal unified setting interface of the goframe framework. It initializes the current object with an interface{} type parameter, the usage logic of which is determined by the implementation method of this interface.
• Signature:

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

• Example:

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"}
}