set

package
v1.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 19, 2016 License: GPL-3.0, MIT Imports: 3 Imported by: 0

README

Set GoDoc Build Status

Set is a basic and simple, hash-based, Set data structure implementation in Go (Golang).

Set provides both threadsafe and non-threadsafe implementations of a generic set data structure. The thread safety encompasses all operations on one set. Operations on multiple sets are consistent in that the elements of each set used was valid at exactly one point in time between the start and the end of the operation. Because it's thread safe, you can use it concurrently with your goroutines.

For usage see examples below or click on the godoc badge.

Install and Usage

Install the package with:

go get gopkg.in/fatih/set.v0

Import it with:

import "gopkg.in/fatih/set.v0"

and use set as the package name inside the code.

Examples

Initialization of a new Set

// create a set with zero items
s := set.New()
s := set.NewNonTS() // non thread-safe version

// ... or with some initial values
s := set.New("istanbul", "frankfurt", 30.123, "san francisco", 1234)
s := set.NewNonTS("kenya", "ethiopia", "sumatra")

Basic Operations
// add items
s.Add("istanbul")
s.Add("istanbul") // nothing happens if you add duplicate item

// add multiple items
s.Add("ankara", "san francisco", 3.14)

// remove item
s.Remove("frankfurt")
s.Remove("frankfurt") // nothing happes if you remove a nonexisting item

// remove multiple items
s.Remove("barcelona", 3.14, "ankara")

// removes an arbitary item and return it
item := s.Pop()

// create a new copy
other := s.Copy()

// remove all items
s.Clear()

// number of items in the set
len := s.Size()

// return a list of items
items := s.List()

// string representation of set
fmt.Printf("set is %s", s.String())

Check Operations
// check for set emptiness, returns true if set is empty
s.IsEmpty()

// check for a single item exist
s.Has("istanbul")

// ... or for multiple items. This will return true if all of the items exist.
s.Has("istanbul", "san francisco", 3.14)

// create two sets for the following checks...
s := s.New("1", "2", "3", "4", "5")
t := s.New("1", "2", "3")


// check if they are the same
if !s.IsEqual(t) {
    fmt.Println("s is not equal to t")
}

// if s contains all elements of t
if s.IsSubset(t) {
	fmt.Println("t is a subset of s")
}

// ... or if s is a superset of t
if t.IsSuperset(s) {
	fmt.Println("s is a superset of t")
}


Set Operations
// let us initialize two sets with some values
a := set.New("ankara", "berlin", "san francisco")
b := set.New("frankfurt", "berlin")

// creates a new set with the items in a and b combined.
// [frankfurt, berlin, ankara, san francisco]
c := set.Union(a, b)

// contains items which is in both a and b
// [berlin]
c := set.Intersection(a, b)

// contains items which are in a but not in b
// [ankara, san francisco]
c := set.Difference(a, b)

// contains items which are in one of either, but not in both.
// [frankfurt, ankara, san francisco]
c := set.SymmetricDifference(a, b)

// like Union but saves the result back into a.
a.Merge(b)

// removes the set items which are in b from a and saves the result back into a.
a.Separate(b)

Multiple Set Operations
a := set.New("1", "3", "4", "5")
b := set.New("2", "3", "4", "5")
c := set.New("4", "5", "6", "7")

// creates a new set with items in a, b and c
// [1 2 3 4 5 6 7]
u := set.Union(a, b, c)

// creates a new set with items in a but not in b and c
// [1]
u := set.Difference(a, b, c)

// creates a new set with items that are common to a, b and c
// [5]
u := set.Intersection(a, b, c)
Helper methods

The Slice functions below are a convenient way to extract or convert your Set data into basic data types.

// create a set of mixed types
s := set.New("ankara", "5", "8", "san francisco", 13, 21)


// convert s into a slice of strings (type is []string)
// [ankara 5 8 san francisco]
t := set.StringSlice(s)


// u contains a slice of ints (type is []int)
// [13, 21]
u := set.IntSlice(s)

Concurrent safe usage

Below is an example of a concurrent way that uses set. We call ten functions concurrently and wait until they are finished. It basically creates a new string for each goroutine and adds it to our set.

package main

import (
	"fmt"
	"github.com/fatih/set"
	"strconv"
	"sync"
)

func main() {
	var wg sync.WaitGroup // this is just for waiting until all goroutines finish

	// Initialize our thread safe Set
	s := set.New()

	// Add items concurrently (item1, item2, and so on)
	for i := 0; i < 10; i++ {
		wg.Add(1)
		go func(i int) {
			item := "item" + strconv.Itoa(i)
			fmt.Println("adding", item)
			s.Add(item)
			wg.Done()
		}(i)
	}

	// Wait until all concurrent calls finished and print our set
	wg.Wait()
	fmt.Println(s)
}

Credits

License

The MIT License (MIT) - see LICENSE.md for more details

Documentation

Overview

Package set provides both threadsafe and non-threadsafe implementations of a generic set data structure. In the threadsafe set, safety encompasses all operations on one set. Operations on multiple sets are consistent in that the elements of each set used was valid at exactly one point in time between the start and the end of the operation.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IntSlice

func IntSlice(s Interface) []int

IntSlice is a helper function that returns a slice of ints of s. If the set contains mixed types of items only items of type int are returned.

func StringSlice

func StringSlice(s Interface) []string

StringSlice is a helper function that returns a slice of strings of s. If the set contains mixed types of items only items of type string are returned.

Types

type Interface

type Interface interface {
	New(items ...interface{}) Interface
	Add(items ...interface{})
	Remove(items ...interface{})
	Pop() interface{}
	Has(items ...interface{}) bool
	Size() int
	Clear()
	IsEmpty() bool
	IsEqual(s Interface) bool
	IsSubset(s Interface) bool
	IsSuperset(s Interface) bool
	Each(func(interface{}) bool)
	String() string
	List() []interface{}
	Copy() Interface
	Merge(s Interface)
	Separate(s Interface)
}

Interface is describing a Set. Sets are an unordered, unique list of values.

func Difference

func Difference(set1, set2 Interface, sets ...Interface) Interface

Difference returns a new set which contains items which are in in the first set but not in the others. Unlike the Difference() method you can use this function separately with multiple sets.

func Intersection

func Intersection(set1, set2 Interface, sets ...Interface) Interface

Intersection returns a new set which contains items that only exist in all given sets.

func SymmetricDifference

func SymmetricDifference(s Interface, t Interface) Interface

SymmetricDifference returns a new set which s is the difference of items which are in one of either, but not in both.

func Union

func Union(set1, set2 Interface, sets ...Interface) Interface

Union is the merger of multiple sets. It returns a new set with all the elements present in all the sets that are passed.

The dynamic type of the returned set is determined by the first passed set's implementation of the New() method.

type Set

type Set struct {
	// contains filtered or unexported fields
}

Set defines a thread safe set data structure.

func New

func New(items ...interface{}) *Set

New creates and initialize a new Set. It's accept a variable number of arguments to populate the initial set. If nothing passed a Set with zero size is created.

func (*Set) Add

func (s *Set) Add(items ...interface{})

Add includes the specified items (one or more) to the set. The underlying Set s is modified. If passed nothing it silently returns.

func (*Set) Clear

func (s *Set) Clear()

Clear removes all items from the set.

func (*Set) Copy

func (s *Set) Copy() Interface

Copy returns a new Set with a copy of s.

func (*Set) Each

func (s *Set) Each(f func(item interface{}) bool)

Each traverses the items in the Set, calling the provided function for each set member. Traversal will continue until all items in the Set have been visited, or if the closure returns false.

func (*Set) Has

func (s *Set) Has(items ...interface{}) bool

Has looks for the existence of items passed. It returns false if nothing is passed. For multiple items it returns true only if all of the items exist.

func (*Set) IsEmpty

func (s *Set) IsEmpty() bool

IsEmpty reports whether the Set is empty.

func (*Set) IsEqual

func (s *Set) IsEqual(t Interface) bool

IsEqual test whether s and t are the same in size and have the same items.

func (*Set) IsSubset

func (s *Set) IsSubset(t Interface) (subset bool)

IsSubset tests whether t is a subset of s.

func (*Set) IsSuperset

func (s *Set) IsSuperset(t Interface) bool

IsSuperset tests whether t is a superset of s.

func (*Set) List

func (s *Set) List() []interface{}

List returns a slice of all items. There is also StringSlice() and IntSlice() methods for returning slices of type string or int.

func (*Set) Merge

func (s *Set) Merge(t Interface)

Merge is like Union, however it modifies the current set it's applied on with the given t set.

func (*Set) New

func (s *Set) New(items ...interface{}) Interface

New creates and initalizes a new Set interface. It accepts a variable number of arguments to populate the initial set. If nothing is passed a zero size Set based on the struct is created.

func (*Set) Pop

func (s *Set) Pop() interface{}

Pop deletes and return an item from the set. The underlying Set s is modified. If set is empty, nil is returned.

func (*Set) Remove

func (s *Set) Remove(items ...interface{})

Remove deletes the specified items from the set. The underlying Set s is modified. If passed nothing it silently returns.

func (*Set) Separate

func (s *Set) Separate(t Interface)

it's not the opposite of Merge. Separate removes the set items containing in t from set s. Please aware that

func (*Set) Size

func (s *Set) Size() int

Size returns the number of items in a set.

func (*Set) String

func (s *Set) String() string

String returns a string representation of s

type SetNonTS

type SetNonTS struct {
	// contains filtered or unexported fields
}

SetNonTS defines a non-thread safe set data structure.

func NewNonTS

func NewNonTS(items ...interface{}) *SetNonTS

NewNonTS creates and initialize a new non-threadsafe Set. It accepts a variable number of arguments to populate the initial set. If nothing is passed a SetNonTS with zero size is created.

func (*SetNonTS) Add

func (s *SetNonTS) Add(items ...interface{})

Add includes the specified items (one or more) to the set. The underlying Set s is modified. If passed nothing it silently returns.

func (*SetNonTS) Clear

func (s *SetNonTS) Clear()

Clear removes all items from the set.

func (*SetNonTS) Copy

func (s *SetNonTS) Copy() Interface

Copy returns a new Set with a copy of s.

func (*SetNonTS) Each

func (s *SetNonTS) Each(f func(item interface{}) bool)

Each traverses the items in the Set, calling the provided function for each set member. Traversal will continue until all items in the Set have been visited, or if the closure returns false.

func (*SetNonTS) Has

func (s *SetNonTS) Has(items ...interface{}) bool

Has looks for the existence of items passed. It returns false if nothing is passed. For multiple items it returns true only if all of the items exist.

func (*SetNonTS) IsEmpty

func (s *SetNonTS) IsEmpty() bool

IsEmpty reports whether the Set is empty.

func (*SetNonTS) IsEqual

func (s *SetNonTS) IsEqual(t Interface) bool

IsEqual test whether s and t are the same in size and have the same items.

func (*SetNonTS) IsSubset

func (s *SetNonTS) IsSubset(t Interface) (subset bool)

IsSubset tests whether t is a subset of s.

func (*SetNonTS) IsSuperset

func (s *SetNonTS) IsSuperset(t Interface) bool

IsSuperset tests whether t is a superset of s.

func (*SetNonTS) List

func (s *SetNonTS) List() []interface{}

List returns a slice of all items. There is also StringSlice() and IntSlice() methods for returning slices of type string or int.

func (*SetNonTS) Merge

func (s *SetNonTS) Merge(t Interface)

Merge is like Union, however it modifies the current set it's applied on with the given t set.

func (*SetNonTS) New

func (s *SetNonTS) New(items ...interface{}) Interface

New creates and initalizes a new Set interface. It accepts a variable number of arguments to populate the initial set. If nothing is passed a zero size Set based on the struct is created.

func (*SetNonTS) Pop

func (s *SetNonTS) Pop() interface{}

Pop deletes and return an item from the set. The underlying Set s is modified. If set is empty, nil is returned.

func (*SetNonTS) Remove

func (s *SetNonTS) Remove(items ...interface{})

Remove deletes the specified items from the set. The underlying Set s is modified. If passed nothing it silently returns.

func (*SetNonTS) Separate

func (s *SetNonTS) Separate(t Interface)

it's not the opposite of Merge. Separate removes the set items containing in t from set s. Please aware that

func (*SetNonTS) Size

func (s *SetNonTS) Size() int

Size returns the number of items in a set.

func (*SetNonTS) String

func (s *SetNonTS) String() string

String returns a string representation of s

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL