set

Documentation

Overview

Package set implements a simple, generic set data structure.

The set is not safe for concurrent access across goroutines, the caller is responsible for synchronising concurrent access.

Index

• type Set
  • func Collect[T comparable](items iter.Seq[T]) *Set[T]
  • func Difference[S *Set[T], T comparable](a, b *Set[T]) *Set[T]
  • func From[T comparable](items []T) *Set[T]
  • func Intersection[S *Set[T], T comparable](a, b *Set[T]) *Set[T]
  • func New[T comparable]() *Set[T]
  • func Union[S *Set[T], T comparable](a, b *Set[T]) *Set[T]
  • func (s *Set[T]) Contains(item T) bool
  • func (s *Set[T]) Empty() bool
  • func (s *Set[T]) Insert(item T) bool
  • func (s *Set[T]) Items() iter.Seq[T]
  • func (s *Set[T]) Remove(item T) bool
  • func (s *Set[T]) Size() int
  • func (s *Set[T]) String() string

Examples

• Difference
• Intersection
• Union

Types

type Set

type Set[T comparable] struct {
	// contains filtered or unexported fields
}

Set is a simple, generic implementation of a mathematical set.

func Collect

func Collect[T comparable](items iter.Seq[T]) *Set[T]

Collect builds a Set from an iterator of items.

func Difference

func Difference[S *Set[T], T comparable](a, b *Set[T]) *Set[T]

Difference returns a set containing the items present in a but not b.

Example

package main

import (
	"fmt"
	"slices"

	"github.com/FollowTheProcess/collections/set"
)

func main() {
	this := set.New[string]()
	that := set.New[string]()

	this.Insert("hello")
	this.Insert("there")

	that.Insert("general")
	that.Insert("kenobi")
	that.Insert("says")
	that.Insert("hello")

	// Get the items in a slice of strings
	difference := slices.Sorted(set.Difference(this, that).Items())

	fmt.Println(difference)
}

Output:

[there]

func From

func From[T comparable](items []T) *Set[T]

From builds a Set from an existing slice of items.

The set will be preallocated the size of len(items).

func Intersection

func Intersection[S *Set[T], T comparable](a, b *Set[T]) *Set[T]

Intersection returns a set containing all the items present in both a and b.

Example

package main

import (
	"fmt"
	"slices"

	"github.com/FollowTheProcess/collections/set"
)

func main() {
	this := set.New[string]()
	that := set.New[string]()

	this.Insert("hello")
	this.Insert("there")

	that.Insert("general")
	that.Insert("kenobi")
	that.Insert("says")
	that.Insert("hello")

	// Get the items in a slice of strings
	intersection := slices.Sorted(set.Intersection(this, that).Items())

	fmt.Println(intersection)
}

Output:

[hello]

func New

func New[T comparable]() *Set[T]

New builds and returns a new empty Set.

The set will grow as needed as items are inserted, an initial small size is allocated.

If constructing a set from a pre-existing slice of items, use From which will preallocate the set with the appropriate size. Or to collect an iterator into a Set, use Collect.

func Union

func Union[S *Set[T], T comparable](a, b *Set[T]) *Set[T]

Union returns a set that is the combination of a and b, i.e. all the items from both sets combined into one, with no duplicates.

Example

package main

import (
	"fmt"
	"slices"

	"github.com/FollowTheProcess/collections/set"
)

func main() {
	this := set.New[string]()
	that := set.New[string]()

	this.Insert("hello")
	this.Insert("there")

	that.Insert("general")
	that.Insert("kenobi")
	that.Insert("says")
	that.Insert("hello")

	// Get the union in a slice of strings
	union := slices.Sorted(set.Union(this, that).Items()) // A set is unordered

	fmt.Println(union)
}

Output:

[general hello kenobi says there]

func (*Set[T]) Contains

func (s *Set[T]) Contains(item T) bool

Contains reports whether the set contains item.

s := set.New[int]()
s.Contains(1) // false
s.Insert(1)
s.Contains(1) // true

func (*Set[T]) Empty

func (s *Set[T]) Empty() bool

Empty reports whether the set is empty.

func (*Set[T]) Insert

func (s *Set[T]) Insert(item T) bool

Insert inserts an item into the Set.

Returns whether the item was newly inserted. Inserting an item that is already present is effectively a no-op.

s := set.New[string]()
s.Insert("foo") // true -> set was modified by the insertion
s.Insert("foo") // false -> "foo" is already in the set, it was not modified

func (*Set[T]) Items

func (s *Set[T]) Items() iter.Seq[T]

Items returns the an iterator over the sets items.

The order of the items is non-deterministic, the caller should collect and sort the returned items if order is important.

func (*Set[T]) Remove

func (s *Set[T]) Remove(item T) bool

Remove removes an item from the set.

Returns whether the value was present. Removing an item that wasn't in the set is effectively a no-op.

func (*Set[T]) Size

func (s *Set[T]) Size() int

Size returns the current size of the set.

func (*Set[T]) String

func (s *Set[T]) String() string

String implements fmt.Stringer for a Set and allows it to print itself.