set

Sets provide constant-time operations to insert, remove, or check for the presence of a value. Sets are implemented using a hash table, and therefore, just like keys of a dictionary, elements of a set must be hashable. A value may be used as an element of a set if and only if it may be used as a key of a dictionary.

Sets may be constructed using the set() built-in function, which returns a new set containing the unique elements of its optional argument, which must be an iterable. Calling set() without an argument constructs an empty set. Sets have no literal syntax.

The in and not in operations check whether a value is (or is not) in a set:

s = set(["a", "b", "c"])
"a" in s  # True
"z" in s  # False

A set is iterable, and thus may be used as the operand of a for loop, a list comprehension, and the various built-in functions that operate on iterables. Its length can be retrieved using the len() built-in function, and the order of iteration is the order in which elements were first added to the set:

s = set(["z", "y", "z", "y"])
len(s)       # prints 2
s.add("x")
len(s)       # prints 3
for e in s:
    print e  # prints "z", "y", "x"

A set used in Boolean context is true if and only if it is non-empty.

s = set()
"non-empty" if s else "empty"  # "empty"
t = set(["x", "y"])
"non-empty" if t else "empty"  # "non-empty"

Sets may be compared for equality or inequality using == and !=. A set s is equal to t if and only if t is a set containing the same elements; iteration order is not significant. In particular, a set is not equal to the list of its elements. Sets are not ordered with respect to other sets, and an attempt to compare two sets using <, <=, >, >=, or to sort a sequence of sets, will fail.

set() == set()              # True
set() != []                 # True
set([1, 2]) == set([2, 1])  # True
set([1, 2]) != [1, 2]       # True

The | operation on two sets returns the union of the two sets: a set containing the elements found in either one or both of the original sets.

set([1, 2]) | set([3, 2])  # set([1, 2, 3])

The & operation on two sets returns the intersection of the two sets: a set containing only the elements found in both of the original sets.

set([1, 2]) & set([2, 3])  # set([2])
set([1, 2]) & set([3, 4])  # set()

The - operation on two sets returns the difference of the two sets: a set containing the elements found in the left-hand side set but not the right-hand side set.

set([1, 2]) - set([2, 3])  # set([1])
set([1, 2]) - set([3, 4])  # set([1, 2])

The ^ operation on two sets returns the symmetric difference of the two sets: a set containing the elements found in exactly one of the two original sets, but not in both.

set([1, 2]) ^ set([2, 3])  # set([1, 3])
set([1, 2]) ^ set([3, 4])  # set([1, 2, 3, 4])

In each of the above operations, the elements of the resulting set retain their order from the two operand sets, with all elements that were drawn from the left-hand side ordered before any element that was only present in the right-hand side.

The corresponding augmented assignments, |=, &=, -=, and ^=, modify the left-hand set in place.

s = set([1, 2])
s |= set([2, 3, 4])     # s now equals set([1, 2, 3, 4])
s &= set([0, 1, 2, 3])  # s now equals set([1, 2, 3])
s -= set([0, 1])        # s now equals set([2, 3])
s ^= set([3, 4])        # s now equals set([2, 4])

Like all mutable values in Starlark, a set can be frozen, and once frozen, all subsequent operations that attempt to update it will fail.

Members

• add
• clear
• difference
• difference_update
• discard
• intersection
• intersection_update
• isdisjoint
• issubset
• issuperset
• pop
• remove
• symmetric_difference
• symmetric_difference_update
• union
• update

add

None set.add(element)

It is permissible to add a value already present in the set; this leaves the set unchanged.

If you need to add multiple elements to a set, see update or the |= augmented assignment operation.

Parameters

clear

None set.clear()

difference

set set.difference(*others)

If s and t are sets, s.difference(t) is equivalent to s - t; however, note that the - operation requires both sides to be sets, while the difference method also accepts sequences and dicts.

It is permissible to call difference without any arguments; this returns a copy of the set.

For example,

set([1, 2, 3]).difference([2])             # set([1, 3])
set([1, 2, 3]).difference([0, 1], [3, 4])  # set([2])

Parameters

difference_update

None set.difference_update(*others)

If s and t are sets, s.difference_update(t) is equivalent to s -= t; however, note that the -= augmented assignment requires both sides to be sets, while the difference_update method also accepts sequences and dicts.

It is permissible to call difference_update without any arguments; this leaves the set unchanged.

For example,

s = set([1, 2, 3, 4])
s.difference_update([2])             # None; s is set([1, 3, 4])
s.difference_update([0, 1], [4, 5])  # None; s is set([3])

Parameters

discard

None set.discard(element)

It is permissible to discard a value not present in the set; this leaves the set unchanged. If you want to fail on an attempt to remove a non-present element, use remove instead. If you need to remove multiple elements from a set, see difference_update or the -= augmented assignment operation.

For example,

s = set(["x", "y"])
s.discard("y")  # None; s == set(["x"])
s.discard("y")  # None; s == set(["x"])

Parameters

intersection

set set.intersection(*others)

If s and t are sets, s.intersection(t) is equivalent to s & t; however, note that the & operation requires both sides to be sets, while the intersection method also accepts sequences and dicts.

It is permissible to call intersection without any arguments; this returns a copy of the set.

For example,

set([1, 2]).intersection([2, 3])             # set([2])
set([1, 2, 3]).intersection([0, 1], [1, 2])  # set([1])

Parameters

intersection_update

None set.intersection_update(*others)

If s and t are sets, s.intersection_update(t) is equivalent to s &= t; however, note that the &= augmented assignment requires both sides to be sets, while the intersection_update method also accepts sequences and dicts.

It is permissible to call intersection_update without any arguments; this leaves the set unchanged.

For example,

s = set([1, 2, 3, 4])
s.intersection_update([0, 1, 2])       # None; s is set([1, 2])
s.intersection_update([0, 1], [1, 2])  # None; s is set([1])

Parameters

isdisjoint

bool set.isdisjoint(other)

For example,

set([1, 2]).isdisjoint([3, 4])  # True
set().isdisjoint(set())         # True
set([1, 2]).isdisjoint([2, 3])  # False

Parameters

issubset

bool set.issubset(other)

Note that a set is always considered to be a subset of itself.

For example,

set([1, 2]).issubset([1, 2, 3])  # True
set([1, 2]).issubset([1, 2])     # True
set([1, 2]).issubset([2, 3])     # False

Parameters

issuperset

bool set.issuperset(other)

Note that a set is always considered to be a superset of itself.

For example,

set([1, 2, 3]).issuperset([1, 2])     # True
set([1, 2, 3]).issuperset([1, 2, 3])  # True
set([1, 2, 3]).issuperset([2, 3, 4])  # False

Parameters

pop

unknown set.pop()

Fails if the set is empty.

For example,

s = set([3, 1, 2])
s.pop()  # 3; s == set([1, 2])
s.pop()  # 1; s == set([2])
s.pop()  # 2; s == set()
s.pop()  # error: empty set

remove

None set.remove(element)

remove fails if the element was not present in the set. If you don't want to fail on an attempt to remove a non-present element, use discard instead. If you need to remove multiple elements from a set, see difference_update or the -= augmented assignment operation.

Parameters

symmetric_difference

set set.symmetric_difference(other)

If s and t are sets, s.symmetric_difference(t) is equivalent to s ^ t; however, note that the ^ operation requires both sides to be sets, while the symmetric_difference method also accepts a sequence or a dict.

For example,

set([1, 2]).symmetric_difference([2, 3])  # set([1, 3])

Parameters

symmetric_difference_update

None set.symmetric_difference_update(other)

If s and t are sets, s.symmetric_difference_update(t) is equivalent to `s ^= t; however, note that the ^=` augmented assignment requires both sides to be sets, while the symmetric_difference_update method also accepts a sequence or a dict.

For example,

s = set([1, 2])
s.symmetric_difference_update([2, 3])  # None; s == set([1, 3])

Parameters

union

set set.union(*others)

If s and t are sets, s.union(t) is equivalent to s | t; however, note that the | operation requires both sides to be sets, while the union method also accepts sequences and dicts.

It is permissible to call union without any arguments; this returns a copy of the set.

For example,

set([1, 2]).union([2, 3])                    # set([1, 2, 3])
set([1, 2]).union([2, 3], {3: "a", 4: "b"})  # set([1, 2, 3, 4])

Parameters

update

None set.update(*others)

For example,

s = set()
s.update([1, 2])          # None; s is set([1, 2])
s.update([2, 3], [3, 4])  # None; s is set([1, 2, 3, 4])

If s and t are sets, s.update(t) is equivalent to s |= t; however, note that the |= augmented assignment requires both sides to be sets, while the update method also accepts sequences and dicts.

It is permissible to call update without any arguments; this leaves the set unchanged.

Parameters