Skip to content

Commit 38ee2ed

Browse files
authored
Merge pull request #3 from fortio/better_doc
improve doc - links to receiver methods don't work though
2 parents 06c3655 + 88e8400 commit 38ee2ed

File tree

1 file changed

+15
-2
lines changed

1 file changed

+15
-2
lines changed

sets.go

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,9 @@
33
// (c) 2023 Fortio Authors
44
// See LICENSE
55

6-
// Sets and Set type and operations in go 1.18+ generics.
7-
// (pending built in support in golang core)
6+
// Sets and Set[T] type and operations of any comparable type (go 1.18+ generics)
7+
// [Intersection], [Union], [Subset], difference aka [Minus], [XOR],
8+
// JSON serialization and deserialization and more.
89
package sets // import "fortio.org/sets"
910

1011
import (
@@ -16,6 +17,7 @@ import (
1617
"golang.org/x/exp/constraints"
1718
)
1819

20+
// Set defines a low memory footprint set of any comparable type. Based on `map[T]struct{}`.
1921
type Set[T comparable] map[T]struct{}
2022

2123
// New returns a new set containing the given elements.
@@ -33,6 +35,7 @@ func FromSlice[T comparable](items []T) Set[T] {
3335
return New(items...)
3436
}
3537

38+
// Clone returns a copy of the set.
3639
func (s Set[T]) Clone() Set[T] {
3740
res := make(Set[T], len(s))
3841
for k := range s {
@@ -41,17 +44,20 @@ func (s Set[T]) Clone() Set[T] {
4144
return res
4245
}
4346

47+
// Add items to the set.
4448
func (s Set[T]) Add(item ...T) {
4549
for _, i := range item {
4650
s[i] = struct{}{}
4751
}
4852
}
4953

54+
// Has returns true if the item is present in the set.
5055
func (s Set[T]) Has(item T) bool {
5156
_, found := s[item]
5257
return found
5358
}
5459

60+
// Remove items from the set.
5561
func (s Set[T]) Remove(item ...T) {
5662
for _, i := range item {
5763
delete(s, i)
@@ -73,6 +79,7 @@ func Union[T comparable](sets ...Set[T]) Set[T] {
7379
return res
7480
}
7581

82+
// Intersection returns a new set that has the elements common to all the input sets.
7683
func Intersection[T comparable](sets ...Set[T]) Set[T] {
7784
if len(sets) == 0 {
7885
return New[T]()
@@ -91,6 +98,7 @@ func Intersection[T comparable](sets ...Set[T]) Set[T] {
9198
return res
9299
}
93100

101+
// Elements returns a slice of the elements in the set.
94102
func (s Set[T]) Elements() []T {
95103
res := make([]T, 0, len(s))
96104
for k := range s {
@@ -127,14 +135,17 @@ func (s Set[T]) Plus(others ...Set[T]) Set[T] {
127135
return s
128136
}
129137

138+
// Equals returns true if the two sets have the same elements.
130139
func (s Set[T]) Equals(other Set[T]) bool {
131140
return len(s) == len(other) && s.Subset(other)
132141
}
133142

143+
// Len returns the number of elements in the set (same as len(s) but as a method).
134144
func (s Set[T]) Len() int {
135145
return len(s)
136146
}
137147

148+
// Clear removes all elements from the set.
138149
func (s Set[T]) Clear() {
139150
for k := range s {
140151
delete(s, k)
@@ -207,6 +218,8 @@ func (s *Set[T]) UnmarshalJSON(data []byte) error {
207218

208219
// -- Additional operations on sets of ordered types
209220

221+
// Sort returns a sorted slice of the elements in the set.
222+
// Only applicable for when the type is sortable.
210223
func Sort[Q constraints.Ordered](s Set[Q]) []Q {
211224
keys := s.Elements()
212225
sort.Slice(keys, func(i, j int) bool { return keys[i] < keys[j] })

0 commit comments

Comments
 (0)