hashset

README

hashset

A generic set for Go, built on a Go map, with a method surface that mirrors .NET's HashSet<T>. It has no dependencies outside the Go standard library. The type and constructor names, HashSet and NewHashSet, follow .NET's HashSet<T> on purpose.

type HashSet[T comparable] map[T]struct{}

A HashSet is a map, so len(hs) and for v := range hs work directly. Element order is not defined. The zero value is a nil map: reads work, but adding to it panics, so create sets with NewHashSet.

Install

go get github.com/ritchiecarroll/hashset

Requires Go 1.21 or later.

Usage

package main

import (
	"fmt"

	"github.com/ritchiecarroll/hashset"
)

func main() {
	langs := hashset.NewHashSet([]string{"go", "cs", "go"})

	langs.Add("ts")
	langs.Remove("cs")

	fmt.Println(len(langs), langs.Contains("go")) // 2 true

	other := hashset.NewHashSet([]string{"go", "rs"})
	langs.IntersectWithSet(other)

	fmt.Println(langs.Keys()) // [go]
}

Methods

Most operations come in two forms: one takes a slice, and one with a Set suffix takes another HashSet. A slice argument stands for the set of its distinct values, so repeating a value in it does not change the result.

Method	Purpose
NewHashSet(items)	New set holding the distinct items of a slice
Add, Remove, RemoveWhere	Add or remove elements; report what changed
Contains, IsEmpty, Keys, Clear	Query, copy out, or empty the set
UnionWith, UnionWithSet	Add every element of the other collection
IntersectWith, IntersectWithSet	Keep only elements also in the other collection
ExceptWith, ExceptWithSet	Remove every element of the other collection
SymmetricExceptWith, SymmetricExceptWithSet	Keep elements in exactly one of the two
SetEquals, SetEqualsSet	Same elements?
Overlaps, OverlapsSet	Any element in common?
IsSubsetOf, IsSubsetOfSet, IsProperSubsetOf, IsProperSubsetOfSet	Subset tests
IsSupersetOf, IsSupersetOfSet, IsProperSupersetOf, IsProperSupersetOfSet	Superset tests

Thread safety

A HashSet is not safe for concurrent use. To use a set from more than one goroutine, hold a lock around every use of it, len and range included.

Origin

HashSet was extracted from go2cs, a Go to C# transpiler.

License

MIT

Documentation

Overview

Package hashset provides HashSet, a generic set of comparable values built on a Go map, with a method surface that mirrors .NET's HashSet<T>.

Index

• type HashSet
  • func NewHashSet[T comparable](items []T) HashSet[T]
  • func (hs HashSet[T]) Add(item T) bool
  • func (hs HashSet[T]) Clear()
  • func (hs HashSet[T]) Contains(item T) bool
  • func (hs HashSet[T]) ExceptWith(other []T)
  • func (hs HashSet[T]) ExceptWithSet(other HashSet[T])
  • func (hs HashSet[T]) IntersectWith(other []T)
  • func (hs HashSet[T]) IntersectWithSet(other HashSet[T])
  • func (hs HashSet[T]) IsEmpty() bool
  • func (hs HashSet[T]) IsProperSubsetOf(other []T) bool
  • func (hs HashSet[T]) IsProperSubsetOfSet(other HashSet[T]) bool
  • func (hs HashSet[T]) IsProperSupersetOf(other []T) bool
  • func (hs HashSet[T]) IsProperSupersetOfSet(other HashSet[T]) bool
  • func (hs HashSet[T]) IsSubsetOf(other []T) bool
  • func (hs HashSet[T]) IsSubsetOfSet(other HashSet[T]) bool
  • func (hs HashSet[T]) IsSupersetOf(other []T) bool
  • func (hs HashSet[T]) IsSupersetOfSet(other HashSet[T]) bool
  • func (hs HashSet[T]) Keys() []T
  • func (hs HashSet[T]) Overlaps(other []T) bool
  • func (hs HashSet[T]) OverlapsSet(other HashSet[T]) bool
  • func (hs HashSet[T]) Remove(item T) bool
  • func (hs HashSet[T]) RemoveWhere(predicate func(T) bool) int
  • func (hs HashSet[T]) SetEquals(other []T) bool
  • func (hs HashSet[T]) SetEqualsSet(other HashSet[T]) bool
  • func (hs HashSet[T]) SymmetricExceptWith(other []T)
  • func (hs HashSet[T]) SymmetricExceptWithSet(other HashSet[T])
  • func (hs HashSet[T]) UnionWith(other []T)
  • func (hs HashSet[T]) UnionWithSet(other HashSet[T])

Examples

• HashSet.Add
• HashSet.IntersectWith
• HashSet.IsSubsetOfSet
• HashSet.UnionWithSet
• NewHashSet

Types

type HashSet

type HashSet[T comparable] map[T]struct{}

HashSet represents a distinct collection of T values, i.e., a set. A HashSet is not sorted and will not contain duplicate elements.

The zero value is a nil HashSet. It reads as an empty set: len, range and every method that only reads the set work on it. Adding an element to it panics, so sets are created with NewHashSet.

A floating-point NaN never equals itself, so each Add of a NaN adds a new element, Contains and Remove never find it, and only emptying the set removes it: Clear, or IntersectWith or IntersectWithSet with an empty slice or set.

A HashSet is not safe for concurrent use. To use one from more than one goroutine, hold a lock around every use of it, len and range included.

func NewHashSet

func NewHashSet[T comparable](items []T) HashSet[T]

NewHashSet creates a new set containing all elements in the specified slice. Returns a new HashSet that contains the specified slice items.

Example

package main

import (
	"fmt"

	"github.com/ritchiecarroll/hashset"
)

func main() {
	hs := hashset.NewHashSet([]string{"go", "cs", "go"})

	fmt.Println(len(hs), hs.Contains("go"), hs.Contains("ts"))
}

Output:
2 true false

func (HashSet[T]) Add

func (hs HashSet[T]) Add(item T) bool

Add adds the specified element to a set. Returns true if item was added to the set; otherwise, false.

Example

package main

import (
	"fmt"

	"github.com/ritchiecarroll/hashset"
)

func main() {
	hs := hashset.NewHashSet[int](nil)

	fmt.Println(hs.Add(1), hs.Add(1))
}

Output:
true false

func (HashSet[T]) Clear

func (hs HashSet[T]) Clear()

Clear removes all elements from a set.

func (HashSet[T]) Contains

func (hs HashSet[T]) Contains(item T) bool

Contains determines whether a set contains the specified element. Returns true if the set contains the specified element; otherwise, false.

func (HashSet[T]) ExceptWith

func (hs HashSet[T]) ExceptWith(other []T)

ExceptWith removes all elements in the specified slice from the current set.

func (HashSet[T]) ExceptWithSet

func (hs HashSet[T]) ExceptWithSet(other HashSet[T])

ExceptWithSet removes all elements in the specified set from the current set.

func (HashSet[T]) IntersectWith

func (hs HashSet[T]) IntersectWith(other []T)

IntersectWith modifies the current set to contain only elements that are present in the set and in the specified slice.

Example

package main

import (
	"fmt"
	"sort"

	"github.com/ritchiecarroll/hashset"
)

func main() {
	hs := hashset.NewHashSet([]int{1, 2, 3, 4})
	hs.IntersectWith([]int{2, 4, 6})

	keys := hs.Keys()
	sort.Ints(keys)
	fmt.Println(keys)
}

Output:
[2 4]

func (HashSet[T]) IntersectWithSet

func (hs HashSet[T]) IntersectWithSet(other HashSet[T])

IntersectWithSet modifies the current set to contain only elements that are present in the set and in the specified set.

func (HashSet[T]) IsEmpty

func (hs HashSet[T]) IsEmpty() bool

IsEmpty determines if a set contains no elements. Returns true if the set is empty, i.e., has a length of zero; otherwise, false.

func (HashSet[T]) IsProperSubsetOf

func (hs HashSet[T]) IsProperSubsetOf(other []T) bool

IsProperSubsetOf determines whether a set is a proper subset of the specified slice. Returns true if the set is a proper subset of other slice items; otherwise, false.

func (HashSet[T]) IsProperSubsetOfSet

func (hs HashSet[T]) IsProperSubsetOfSet(other HashSet[T]) bool

IsProperSubsetOfSet determines whether a set is a proper subset of the specified set. Returns true if the set is a proper subset of other set; otherwise, false.

func (HashSet[T]) IsProperSupersetOf

func (hs HashSet[T]) IsProperSupersetOf(other []T) bool

IsProperSupersetOf determines whether a set is a proper superset of the specified slice. Returns true if the set is a proper superset of other slice items; otherwise, false.

func (HashSet[T]) IsProperSupersetOfSet

func (hs HashSet[T]) IsProperSupersetOfSet(other HashSet[T]) bool

IsProperSupersetOfSet determines whether a set is a proper superset of the specified set. Returns true if the set is a proper superset of other set; otherwise, false.

func (HashSet[T]) IsSubsetOf

func (hs HashSet[T]) IsSubsetOf(other []T) bool

IsSubsetOf determines whether a set is a subset of the specified slice. Returns true if the set is a subset of other slice items; otherwise, false.

func (HashSet[T]) IsSubsetOfSet

func (hs HashSet[T]) IsSubsetOfSet(other HashSet[T]) bool

IsSubsetOfSet determines whether a set is a subset of the specified set. Returns true if the set is a subset of other set; otherwise, false.

Example

package main

import (
	"fmt"

	"github.com/ritchiecarroll/hashset"
)

func main() {
	small := hashset.NewHashSet([]int{1, 2})
	large := hashset.NewHashSet([]int{1, 2, 3})

	fmt.Println(small.IsSubsetOfSet(large), small.IsProperSubsetOfSet(large), large.IsSubsetOfSet(small))
}

Output:
true true false

func (HashSet[T]) IsSupersetOf

func (hs HashSet[T]) IsSupersetOf(other []T) bool

IsSupersetOf determines whether a set is a superset of the specified slice. Returns true if the set is a superset of other slice items; otherwise, false.

func (HashSet[T]) IsSupersetOfSet

func (hs HashSet[T]) IsSupersetOfSet(other HashSet[T]) bool

IsSupersetOfSet determines whether a set is a superset of the specified set. Returns true if the set is a superset of other set; otherwise, false.

func (HashSet[T]) Keys

func (hs HashSet[T]) Keys() []T

Keys copies the elements of a set to a slice. Returns a slice containing the elements of the set.

func (HashSet[T]) Overlaps

func (hs HashSet[T]) Overlaps(other []T) bool

Overlaps determines whether the current set and a specified slice share common elements. Returns true if the current set and other slice items share at least one common element; otherwise, false.

func (HashSet[T]) OverlapsSet

func (hs HashSet[T]) OverlapsSet(other HashSet[T]) bool

OverlapsSet determines whether the current set and a specified set share common elements. Returns true if the current set and other set share at least one common element; otherwise, false.

func (HashSet[T]) Remove

func (hs HashSet[T]) Remove(item T) bool

Remove removes the specified element from a set. Returns true if item was removed from the set; otherwise, false.

func (HashSet[T]) RemoveWhere

func (hs HashSet[T]) RemoveWhere(predicate func(T) bool) int

RemoveWhere removes all elements that match the conditions defined by the specified predicate from a set. Returns the number of elements that were removed from the set.

func (HashSet[T]) SetEquals

func (hs HashSet[T]) SetEquals(other []T) bool

SetEquals determines whether a set and the specified slice contain the same elements. Returns true if the set is equal to other slice items; otherwise, false.

func (HashSet[T]) SetEqualsSet

func (hs HashSet[T]) SetEqualsSet(other HashSet[T]) bool

SetEqualsSet determines whether a set and the specified set contain the same elements. Returns true if the set is equal to other set; otherwise, false.

func (HashSet[T]) SymmetricExceptWith

func (hs HashSet[T]) SymmetricExceptWith(other []T)

SymmetricExceptWith modifies the current set to contain only elements that are present either in the set or in the specified slice, but not both.

func (HashSet[T]) SymmetricExceptWithSet

func (hs HashSet[T]) SymmetricExceptWithSet(other HashSet[T])

SymmetricExceptWithSet modifies the current set to contain only elements that are present either in the set or in the specified set, but not both.

func (HashSet[T]) UnionWith

func (hs HashSet[T]) UnionWith(other []T)

UnionWith modifies the current set to contain all elements that are present in the set, the specified slice, or both.

func (HashSet[T]) UnionWithSet

func (hs HashSet[T]) UnionWithSet(other HashSet[T])

UnionWithSet modifies the current set to contain all elements that are present in the set, the specified set, or both.

Example

package main

import (
	"fmt"
	"sort"

	"github.com/ritchiecarroll/hashset"
)

func main() {
	hs := hashset.NewHashSet([]int{1, 2})
	hs.UnionWithSet(hashset.NewHashSet([]int{2, 3}))

	keys := hs.Keys()
	sort.Ints(keys)
	fmt.Println(keys)
}

Output:
[1 2 3]