set

Experimental. This API is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting --experimental_enable_starlark_set.

The built-in mutable set type. Example set expressions:

x = set()           # x is an empty set
y = set([1, 2, 3])  # y is a set with 3 elements
3 in y              # True
0 in y              # False
len(x)              # 0
len(y)              # 3

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"

The elements of a set must be hashable; x may be an element of a set if and only if x may be used as a key of a dict.

A set itself is not hashable; therefore, you cannot have a set with another set as an element.

You cannot access the elements of a set by index, but you can iterate over them, and you can obtain the list of a set's elements in iteration order using the list() built-in function. Just like for lists, it is an error to mutate a set while it is being iterated over. The order of iteration matches insertion order:

s = set([3, 1, 3])
s.add(2)
# prints 3, 1, 2
for item in s:
    print(item)
list(s)  # [3, 1, 2]

A set s is equal to t if and only if t is a set containing the same elements, possibly with a different iteration order. In particular, a set is not equal to its list of elements.

Sets are not ordered; the <, <=, >, and >= operations are not defined for sets, and a list of sets cannot be sorted - unlike in Python.

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. The | operation has an augmented assignment version; s |= t adds to s all the elements of t.

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

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. The & operation has an augmented assignment version; s &= t removes from s all the elements not found in t.

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

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 site set. The - operation has an augmented assignment version; s -= t removes from s all the elements found in t.

set([1, 2]) - set([2, 3])  # set([1])
set([1, 2]) - set([3, 4])  # set([1, 2])
s = set([1, 2])
s -= set([0, 1])           # s now equals set([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. The ^ operation has an augmented assignment version; s ^= t removes from s any element of t found in s and adds to s any element of t not found in s.

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

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)

Parameters

clear

None set.clear()

difference

set set.difference(*others)

For example,

set([1, 2, 3]).intersection([1, 2], [2, 3]) == set([2])

Parameters

difference_update

None set.difference_update(*others)

For example,

x = set([1, 2, 3, 4])
x.difference_update([2, 3], [3, 4])
# x is now set([1])

Parameters

discard

None set.discard(element)

Parameters

intersection

set set.intersection(*others)

For example,

set([1, 2, 3]).intersection([1, 2], [2, 3]) == set([2])

Parameters

intersection_update

None set.intersection_update(*others)

For example,

x = set([1, 2, 3, 4])
x.intersection_update([2, 3], [3, 4])
# x is now set([3])

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)

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)

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

remove

None set.remove(element)

Parameters

symmetric_difference

set set.symmetric_difference(other)

For example,

set([1, 2, 3]).symmetric_difference([2, 3, 4]) == set([1, 4])

Parameters

symmetric_difference_update

None set.symmetric_difference_update(other)

For example,

set([1, 2, 3]).symmetric_difference([2, 3, 4]) == set([1, 4])

Parameters

union

set set.union(*others)

For example,

set([1, 2]).union([2, 3, 4], [4, 5]) == set([1, 2, 3, 4, 5])

Parameters

update

None set.update(*others)

For example,

x = set([1, 2])
x.update([2, 3], [3, 4])
# x is now set([1, 2, 3, 4])

Parameters