Skip to main content
Version: 2.9.x
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.

tip

For generic versions of set containers (such as TSet[T]), the framework provides NilChecker functions to customize "which elements should be considered nil" to solve typed nil determination issues when containing pointers, interfaces, and other types. Lazy loading or conditional write methods (such as AddIfNotExist* series) will call this function before actually writing, and usually won't add the element to the set when determined as nil; when NilChecker is not set, behavior remains consistent with historical versions.

  • Description: The generic version TSet[T] provides constructors with NilChecker and runtime registration methods, including:

    • NewTSetWithChecker(checker NilChecker[T], safe ...bool) *TSet[T]
    • NewTSetWithCheckerFrom(items []T, checker NilChecker[T], safe ...bool) *TSet[T]
    • func (set *TSet[T]) RegisterNilChecker(checker NilChecker[T])

  • Purpose: Through NilChecker, customize "which elements are considered nil". Lazy loading/conditional write methods (such as AddIfNotExist*, AddIfNotExistFunc* series) will call this function before actually writing, and usually won't add the element to the set when determined as nil.

  • Example:

func ExampleTSet_NilChecker() {
    type Student struct {
        Name string
    }

    // Use constructor to specify NilChecker, treat *Student(nil) as "invalid element", won't add to set
    set := gset.NewTSetWithChecker[*Student](func(s *Student) bool {
        return s == nil
    }, true)

    ok1 := set.AddIfNotExist(nil)
    fmt.Println(ok1)
    fmt.Println(set.Size())

    // Can also create first, then register determination logic via RegisterNilChecker
    set2 := gset.NewTSet[*Student](true)
    set2.RegisterNilChecker(func(s *Student) bool {
        return s == nil
    })

    ok2 := set2.AddIfNotExist(nil)
    fmt.Println(ok2)
    fmt.Println(set2.Size())

    // Output:
    // false
    // 0
    // false
    // 0
}

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