xref: /aosp_15_r20/external/bazel-skylib/docs/new_sets_doc.md (revision bcb5dc7965af6ee42bf2f21341a2ec00233a8c8a)

<!-- Generated with Stardoc: http://skydoc.bazel.build -->

Skylib module containing common hash-set algorithms.

An empty set can be created using: `sets.make()`, or it can be created with some starting values
if you pass it an sequence: `sets.make([1, 2, 3])`. This returns a struct containing all of the
values as keys in a dictionary - this means that all passed in values must be hashable.  The
values in the set can be retrieved using `sets.to_list(my_set)`.

An arbitrary object can be tested whether it is a set generated by `sets.make()` or not with the
`types.is_set()` method in types.bzl.

<a id="sets.contains"></a>

## sets.contains

<pre>
sets.contains(<a href="#sets.contains-a">a</a>, <a href="#sets.contains-e">e</a>)
</pre>

Checks for the existence of an element in a set.

**PARAMETERS**


| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.contains-a"></a>a |  A set, as returned by `sets.make()`.   |  none |
| <a id="sets.contains-e"></a>e |  The element to look for.   |  none |

**RETURNS**

True if the element exists in the set, False if the element does not.


<a id="sets.copy"></a>

## sets.copy

<pre>
sets.copy(<a href="#sets.copy-s">s</a>)
</pre>

Creates a new set from another set.

**PARAMETERS**


| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.copy-s"></a>s |  A set, as returned by `sets.make()`.   |  none |

**RETURNS**

A new set containing the same elements as `s`.


<a id="sets.difference"></a>

## sets.difference

<pre>
sets.difference(<a href="#sets.difference-a">a</a>, <a href="#sets.difference-b">b</a>)
</pre>

Returns the elements in `a` that are not in `b`.

**PARAMETERS**


| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.difference-a"></a>a |  A set, as returned by `sets.make()`.   |  none |
| <a id="sets.difference-b"></a>b |  A set, as returned by `sets.make()`.   |  none |

**RETURNS**

A set containing the elements that are in `a` but not in `b`.


<a id="sets.disjoint"></a>

## sets.disjoint

<pre>
sets.disjoint(<a href="#sets.disjoint-a">a</a>, <a href="#sets.disjoint-b">b</a>)
</pre>

Returns whether two sets are disjoint.

Two sets are disjoint if they have no elements in common.


**PARAMETERS**


| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.disjoint-a"></a>a |  A set, as returned by `sets.make()`.   |  none |
| <a id="sets.disjoint-b"></a>b |  A set, as returned by `sets.make()`.   |  none |

**RETURNS**

True if `a` and `b` are disjoint, False otherwise.


<a id="sets.insert"></a>

## sets.insert

<pre>
sets.insert(<a href="#sets.insert-s">s</a>, <a href="#sets.insert-e">e</a>)
</pre>

Inserts an element into the set.

Element must be hashable.  This mutates the original set.


**PARAMETERS**


| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.insert-s"></a>s |  A set, as returned by `sets.make()`.   |  none |
| <a id="sets.insert-e"></a>e |  The element to be inserted.   |  none |

**RETURNS**

The set `s` with `e` included.


<a id="sets.intersection"></a>

## sets.intersection

<pre>
sets.intersection(<a href="#sets.intersection-a">a</a>, <a href="#sets.intersection-b">b</a>)
</pre>

Returns the intersection of two sets.

**PARAMETERS**


| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.intersection-a"></a>a |  A set, as returned by `sets.make()`.   |  none |
| <a id="sets.intersection-b"></a>b |  A set, as returned by `sets.make()`.   |  none |

**RETURNS**

A set containing the elements that are in both `a` and `b`.


<a id="sets.is_equal"></a>

## sets.is_equal

<pre>
sets.is_equal(<a href="#sets.is_equal-a">a</a>, <a href="#sets.is_equal-b">b</a>)
</pre>

Returns whether two sets are equal.

**PARAMETERS**


| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.is_equal-a"></a>a |  A set, as returned by `sets.make()`.   |  none |
| <a id="sets.is_equal-b"></a>b |  A set, as returned by `sets.make()`.   |  none |

**RETURNS**

True if `a` is equal to `b`, False otherwise.


<a id="sets.is_subset"></a>

## sets.is_subset

<pre>
sets.is_subset(<a href="#sets.is_subset-a">a</a>, <a href="#sets.is_subset-b">b</a>)
</pre>

Returns whether `a` is a subset of `b`.

**PARAMETERS**


| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.is_subset-a"></a>a |  A set, as returned by `sets.make()`.   |  none |
| <a id="sets.is_subset-b"></a>b |  A set, as returned by `sets.make()`.   |  none |

**RETURNS**

True if `a` is a subset of `b`, False otherwise.


<a id="sets.length"></a>

## sets.length

<pre>
sets.length(<a href="#sets.length-s">s</a>)
</pre>

Returns the number of elements in a set.

**PARAMETERS**


| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.length-s"></a>s |  A set, as returned by `sets.make()`.   |  none |

**RETURNS**

An integer representing the number of elements in the set.


<a id="sets.make"></a>

## sets.make

<pre>
sets.make(<a href="#sets.make-elements">elements</a>)
</pre>

Creates a new set.

All elements must be hashable.


**PARAMETERS**


| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.make-elements"></a>elements |  Optional sequence to construct the set out of.   |  `None` |

**RETURNS**

A set containing the passed in values.


<a id="sets.remove"></a>

## sets.remove

<pre>
sets.remove(<a href="#sets.remove-s">s</a>, <a href="#sets.remove-e">e</a>)
</pre>

Removes an element from the set.

Element must be hashable.  This mutates the original set.


**PARAMETERS**


| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.remove-s"></a>s |  A set, as returned by `sets.make()`.   |  none |
| <a id="sets.remove-e"></a>e |  The element to be removed.   |  none |

**RETURNS**

The set `s` with `e` removed.


<a id="sets.repr"></a>

## sets.repr

<pre>
sets.repr(<a href="#sets.repr-s">s</a>)
</pre>

Returns a string value representing the set.

**PARAMETERS**


| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.repr-s"></a>s |  A set, as returned by `sets.make()`.   |  none |

**RETURNS**

A string representing the set.


<a id="sets.str"></a>

## sets.str

<pre>
sets.str(<a href="#sets.str-s">s</a>)
</pre>

Returns a string value representing the set.

**PARAMETERS**


| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.str-s"></a>s |  A set, as returned by `sets.make()`.   |  none |

**RETURNS**

A string representing the set.


<a id="sets.to_list"></a>

## sets.to_list

<pre>
sets.to_list(<a href="#sets.to_list-s">s</a>)
</pre>

Creates a list from the values in the set.

**PARAMETERS**


| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.to_list-s"></a>s |  A set, as returned by `sets.make()`.   |  none |

**RETURNS**

A list of values inserted into the set.


<a id="sets.union"></a>

## sets.union

<pre>
sets.union(<a href="#sets.union-args">args</a>)
</pre>

Returns the union of several sets.

**PARAMETERS**


| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.union-args"></a>args |  An arbitrary number of sets.   |  none |

**RETURNS**

The set union of all sets in `*args`.