# set

{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/StarlarkSet.java" %} {% dynamic setvar version "8.3.0" %} {% dynamic setvar original_path "/rules/lib/core/set" %} {% include "_buttons.html" %} The built-in set type. A set is a mutable, iterable collection of unique values – the set's elements. The type name of a set is `"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)

Adds an element to the set.

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

Parameter | Description
--- | ---
`element` | required Element to add.

## clear

    None set.clear()

Removes all the elements of the set.

## difference

    set set.difference(*others)

Returns a new mutable set containing the difference of this set with 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

Parameter | Description
--- | ---
`others` | required Sets, sequences of hashable elements, or dicts.

## difference_update

    None set.difference_update(*others)

Removes any elements found in any others from this set.

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

Parameter | Description
--- | ---
`others` | required Sets, sequences of hashable elements, or dicts.

## discard

    None set.discard(element)

Removes an element from the set if it is present.

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

Parameter | Description
--- | ---
`element` | required Element to discard. Must be hashable.

## intersection

    set set.intersection(*others)

Returns a new mutable set containing the intersection of this set with 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

Parameter | Description
--- | ---
`others` | required Sets, sequences of hashable elements, or dicts.

## intersection_update

    None set.intersection_update(*others)

Removes any elements not found in all others from this set.

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

Parameter | Description
--- | ---
`others` | required Sets, sequences of hashable elements, or dicts.

## isdisjoint

    bool set.isdisjoint(other)

Returns true if this set has no elements in common with another.

For example,

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

### Parameters

Parameter | Description
--- | ---
`other` | required A set, a sequence of hashable elements, or a dict.

## issubset

    bool set.issubset(other)

Returns true of this set is a subset of another.

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

Parameter | Description
--- | ---
`other` | required A set, a sequence of hashable elements, or a dict.

## issuperset

    bool set.issuperset(other)

Returns true of this set is a superset of another.

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

Parameter | Description
--- | ---
`other` | required A set, a sequence of hashable elements, or a dict.

## pop

    unknown set.pop()

Removes and returns the first element of the set (in iteration order, which is the order in which elements were first added to the set).

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)

Removes an element, which must be present in the set, from the set.

`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

Parameter | Description
--- | ---
`element` | required Element to remove. Must be an element of the set (and hashable).

## symmetric_difference

    set set.symmetric_difference(other)

Returns a new mutable set containing the symmetric difference of this set with another set, sequence, or dict.

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

Parameter | Description
--- | ---
`other` | required A set, a sequence of hashable elements, or a dict.

## symmetric_difference_update

    None set.symmetric_difference_update(other)

Returns a new mutable set containing the symmetric difference of this set with another set, sequence, or dict.

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

Parameter | Description
--- | ---
`other` | required A set, a sequence of hashable elements, or a dict.

## union

    set set.union(*others)

Returns a new mutable set containing the union of this set with 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

Parameter | Description
--- | ---
`others` | required Sets, sequences of hashable elements, or dicts.

## update

    None set.update(*others)

Adds the elements found in others to this set.

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

Parameter | Description
--- | ---
`others` | required Sets, sequences of hashable elements, or dicts.