set

Documentation

Index

• type Iterator
  • func (it *Iterator[T]) Next() bool
  • func (it *Iterator[T]) Value() T
• type OrderedRules
• type Rules
• type Set
  • func NewSet[T any](rules Rules[T]) Set[T]
  • func NewSetFromSlice[T any](rules Rules[T], vals []T) Set[T]
  • func (s Set[T]) Add(val T)
  • func (s Set[T]) Copy() Set[T]
  • func (s Set[T]) EachValue(cb func(T))
  • func (s Set[T]) Has(val T) bool
  • func (s Set[T]) HasRules(rules Rules[T]) bool
  • func (s1 Set[T]) Intersection(s2 Set[T]) Set[T]
  • func (s Set[T]) Iterator() *Iterator[T]
  • func (s Set[T]) Length() int
  • func (s Set[T]) Remove(val T)
  • func (s Set[T]) Rules() Rules[T]
  • func (s1 Set[T]) Subtract(s2 Set[T]) Set[T]
  • func (s1 Set[T]) SymmetricDifference(s2 Set[T]) Set[T]
  • func (s1 Set[T]) Union(s2 Set[T]) Set[T]
  • func (s Set[T]) Values() []T

Types

type Iterator

type Iterator[T any] struct {
	// contains filtered or unexported fields
}

func (*Iterator[T]) Next

func (it *Iterator[T]) Next() bool

func (*Iterator[T]) Value

func (it *Iterator[T]) Value() T

type OrderedRules

type OrderedRules[T any] interface {
	Rules[T]

	// Less returns true if and only if the first argument should sort before
	// the second argument. If the second argument should sort before the first
	// or if there is no defined order for the values, return false.
	Less(interface{}, interface{}) bool
}

OrderedRules is an extension of Rules that can apply a partial order to element values. When a set's Rules implements OrderedRules an iterator over the set will return items in the order described by the rules.

If the given order is not a total order (that is, some pairs of non-equivalent elements do not have a defined order) then the resulting iteration order is undefined but consistent for a particular version of cty. The exact order in that case is not part of the contract and is subject to change between versions.

type Rules

type Rules[T any] interface {
	// Hash returns an int that somewhat-uniquely identifies the given value.
	//
	// A good hash function will minimize collisions for values that will be
	// added to the set, though collisions *are* permitted. Collisions will
	// simply reduce the efficiency of operations on the set.
	Hash(T) int

	// Equivalent returns true if and only if the two values are considered
	// equivalent for the sake of set membership. Two values that are
	// equivalent cannot exist in the set at the same time, and if two
	// equivalent values are added it is undefined which one will be
	// returned when enumerating all of the set members.
	//
	// Two values that are equivalent *must* result in the same hash value,
	// though it is *not* required that two values with the same hash value
	// be equivalent.
	Equivalent(T, T) bool

	// SameRules returns true if the instance is equivalent to another Rules
	// instance over the same element type.
	SameRules(Rules[T]) bool
}

Rules represents the operations that define membership for a Set.

Each Set has a Rules instance, whose methods must satisfy the interface contracts given below for any value that will be added to the set.

type Set

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

Set is an implementation of the concept of a set: a collection where all values are conceptually either in or out of the set, but the members are not ordered.

This type primarily exists to be the internal type of sets in cty, but it is considered to be at the same level of abstraction as Go's built in slice and map collection types, and so should make no cty-specific assumptions.

Set operations are not thread safe. It is the caller's responsibility to provide mutex guarantees where necessary.

Set operations are not optimized to minimize memory pressure. Mutating a set will generally create garbage and so should perhaps be avoided in tight loops where memory pressure is a concern.

func NewSet

func NewSet[T any](rules Rules[T]) Set[T]

NewSet returns an empty set with the membership rules given.

func NewSetFromSlice

func NewSetFromSlice[T any](rules Rules[T], vals []T) Set[T]

func (Set[T]) Add

func (s Set[T]) Add(val T)

Add inserts the given value into the receiving Set.

This mutates the set in-place. This operation is not thread-safe.

func (Set[T]) Copy

func (s Set[T]) Copy() Set[T]

Copy performs a shallow copy of the receiving set, returning a new set with the same rules and elements.

func (Set[T]) EachValue

func (s Set[T]) EachValue(cb func(T))

EachValue calls the given callback once for each value in the set, in an undefined order that callers should not depend on.

func (Set[T]) Has

func (s Set[T]) Has(val T) bool

Has returns true if the given value is in the receiving set, or false if it is not.

func (Set[T]) HasRules

func (s Set[T]) HasRules(rules Rules[T]) bool

HasRules returns true if and only if the receiving set has the given rules instance as its rules.

func (Set[T]) Intersection

func (s1 Set[T]) Intersection(s2 Set[T]) Set[T]

Intersection returns a new set that contains the values that both the receiver and given sets have in common. Both sets must have the same rules, or else this function will panic.

func (Set[T]) Iterator

func (s Set[T]) Iterator() *Iterator[T]

Iterator returns an iterator over values in the set. If the set's rules implement OrderedRules then the result is ordered per those rules. If no order is provided, or if it is not a total order, then the iteration order is undefined but consistent for a particular version of cty. Do not rely on specific ordering between cty releases unless the rules order is a total order.

The pattern for using the returned iterator is:

it := set.Iterator()
for it.Next() {
    val := it.Value()
    // ...
}

Once an iterator has been created for a set, the set *must not* be mutated until the iterator is no longer in use.

func (Set[T]) Length

func (s Set[T]) Length() int

Length returns the number of values in the set.

func (Set[T]) Remove

func (s Set[T]) Remove(val T)

Remove deletes the given value from the receiving set, if indeed it was there in the first place. If the value is not present, this is a no-op.

func (Set[T]) Rules

func (s Set[T]) Rules() Rules[T]

Rules returns the receiving set's rules instance.

func (Set[T]) Subtract

func (s1 Set[T]) Subtract(s2 Set[T]) Set[T]

Subtract returns a new set that contains all of the values from the receiver that are not also in the given set. Both sets must have the same rules, or else this function will panic.

func (Set[T]) SymmetricDifference

func (s1 Set[T]) SymmetricDifference(s2 Set[T]) Set[T]

SymmetricDifference returns a new set that contains all of the values from both the receiver and given sets, except those that both sets have in common. Both sets must have the same rules, or else this function will panic.

func (Set[T]) Union

func (s1 Set[T]) Union(s2 Set[T]) Set[T]

Union returns a new set that contains all of the members of both the receiving set and the given set. Both sets must have the same rules, or else this function will panic.

func (Set[T]) Values

func (s Set[T]) Values() []T

Values returns a slice of all the values in the set. If the set rules have an order then the result is in that order. If no order is provided or if it is not a total order then the result order is undefined, but consistent for a particular set value within a specific release of cty.