set

Documentation

Index

• type Iterator
  • func (it *Iterator) Next() bool
  • func (it *Iterator) Value() interface{}
• type OrderedRules
• type Rules
• type Set
  • func NewSet(rules Rules) Set
  • func NewSetFromSlice(rules Rules, vals []interface{}) Set
  • func (s Set) Add(val interface{})
  • func (s Set) Copy() Set
  • func (s Set) EachValue(cb func(interface{}))
  • func (s *Set) GobDecode(buf []byte) error
  • func (s Set) GobEncode() ([]byte, error)
  • func (s Set) Has(val interface{}) bool
  • func (s Set) HasRules(rules Rules) bool
  • func (s1 Set) Intersection(s2 Set) Set
  • func (s Set) Iterator() *Iterator
  • func (s Set) Length() int
  • func (s Set) Remove(val interface{})
  • func (s Set) Rules() Rules
  • func (s1 Set) Subtract(s2 Set) Set
  • func (s1 Set) SymmetricDifference(s2 Set) Set
  • func (s1 Set) Union(s2 Set) Set
  • func (s Set) Values() []interface{}

Types

type Iterator

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

func (*Iterator) Next

func (it *Iterator) Next() bool

func (*Iterator) Value

func (it *Iterator) Value() interface{}

type OrderedRules

type OrderedRules interface {
	Rules

	// 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 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(interface{}) 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(interface{}, interface{}) bool

	// SameRules returns true if the instance is equivalent to another Rules
	// instance.
	SameRules(Rules) 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 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(rules Rules) Set

NewSet returns an empty set with the membership rules given.

func NewSetFromSlice

func NewSetFromSlice(rules Rules, vals []interface{}) Set

func (Set) Add

func (s Set) Add(val interface{})

Add inserts the given value into the receiving Set.

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

func (Set) Copy

func (s Set) Copy() Set

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

func (Set) EachValue

func (s Set) EachValue(cb func(interface{}))

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

func (*Set) GobDecode

func (s *Set) GobDecode(buf []byte) error

GobDecode is the opposite of GobEncode. See GobEncode for information on the requirements for and caveats of including set values in gobs.

func (Set) GobEncode

func (s Set) GobEncode() ([]byte, error)

GobEncode is an implementation of the interface gob.GobEncoder, allowing sets to be included in structures encoded via gob.

The set rules are included in the serialized value, so the caller must register its concrete rules type with gob.Register before using a set in a gob, and possibly also implement GobEncode/GobDecode to customize how any parameters are persisted.

The set elements are also included, so if they are of non-primitive types they too must be registered with gob.

If the produced gob values will persist for a long time, the caller must ensure compatibility of the rules implementation. In particular, if the definition of element equivalence changes between encoding and decoding then two distinct stored elements may be considered equivalent on decoding, causing the recovered set to have fewer elements than when it was stored.

func (Set) Has

func (s Set) Has(val interface{}) bool

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

func (Set) HasRules

func (s Set) HasRules(rules Rules) bool

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

func (Set) Intersection

func (s1 Set) Intersection(s2 Set) Set

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) Iterator

func (s Set) Iterator() *Iterator

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) Length

func (s Set) Length() int

Length returns the number of values in the set.

func (Set) Remove

func (s Set) Remove(val interface{})

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) Rules

func (s Set) Rules() Rules

Rules returns the receiving set's rules instance.

func (Set) Subtract

func (s1 Set) Subtract(s2 Set) Set

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) SymmetricDifference

func (s1 Set) SymmetricDifference(s2 Set) Set

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) Union

func (s1 Set) Union(s2 Set) Set

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) Values

func (s Set) Values() []interface{}

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.