diff options
Diffstat (limited to 'docs/new_sets_doc.md')
| -rwxr-xr-x | docs/new_sets_doc.md | 556 |
1 files changed, 200 insertions, 356 deletions
diff --git a/docs/new_sets_doc.md b/docs/new_sets_doc.md index feec3b8..e34107f 100755 --- a/docs/new_sets_doc.md +++ b/docs/new_sets_doc.md @@ -1,3 +1,18 @@ +<!-- 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.make"></a> + ## sets.make <pre> @@ -9,26 +24,19 @@ Creates a new set. All elements must be hashable. -### Parameters +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.make-elements"></a>elements | Optional sequence to construct the set out of. | <code>None</code> | + +**RETURNS** + +A set containing the passed in values. -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.make-elements"> - <td><code>elements</code></td> - <td> - optional. default is <code>None</code> - <p> - Optional sequence to construct the set out of. - </p> - </td> - </tr> - </tbody> -</table> +<a id="#sets.copy"></a> ## sets.copy @@ -38,27 +46,20 @@ sets.copy(<a href="#sets.copy-s">s</a>) Creates a new set from another set. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.copy-s"> - <td><code>s</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.copy-s"></a>s | A set, as returned by <code>sets.make()</code>. | none | + +**RETURNS** + +A new set containing the same elements as `s`. + + +<a id="#sets.to_list"></a> + ## sets.to_list <pre> @@ -67,26 +68,19 @@ sets.to_list(<a href="#sets.to_list-s">s</a>) Creates a list from the values in the set. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.to_list-s"> - <td><code>s</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.to_list-s"></a>s | A set, as returned by <code>sets.make()</code>. | none | + +**RETURNS** + +A list of values inserted into the set. + +<a id="#sets.insert"></a> ## sets.insert @@ -99,36 +93,21 @@ Inserts an element into the set. Element must be hashable. This mutates the original set. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.insert-s"> - <td><code>s</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - <tr id="sets.insert-e"> - <td><code>e</code></td> - <td> - required. - <p> - The element to be inserted. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.insert-s"></a>s | A set, as returned by <code>sets.make()</code>. | none | +| <a id="sets.insert-e"></a>e | The element to be inserted. | none | + +**RETURNS** + +The set `s` with `e` included. + + +<a id="#sets.contains"></a> + ## sets.contains <pre> @@ -137,35 +116,20 @@ sets.contains(<a href="#sets.contains-a">a</a>, <a href="#sets.contains-e">e</a> Checks for the existence of an element in a set. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.contains-a"> - <td><code>a</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - <tr id="sets.contains-e"> - <td><code>e</code></td> - <td> - required. - <p> - The element to look for. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.contains-a"></a>a | A set, as returned by <code>sets.make()</code>. | 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.is_equal"></a> ## sets.is_equal @@ -175,36 +139,21 @@ sets.is_equal(<a href="#sets.is_equal-a">a</a>, <a href="#sets.is_equal-b">b</a> Returns whether two sets are equal. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.is_equal-a"> - <td><code>a</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - <tr id="sets.is_equal-b"> - <td><code>b</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.is_equal-a"></a>a | A set, as returned by <code>sets.make()</code>. | none | +| <a id="sets.is_equal-b"></a>b | A set, as returned by <code>sets.make()</code>. | none | + +**RETURNS** + +True if `a` is equal to `b`, False otherwise. + + +<a id="#sets.is_subset"></a> + ## sets.is_subset <pre> @@ -213,35 +162,20 @@ sets.is_subset(<a href="#sets.is_subset-a">a</a>, <a href="#sets.is_subset-b">b< Returns whether `a` is a subset of `b`. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.is_subset-a"> - <td><code>a</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - <tr id="sets.is_subset-b"> - <td><code>b</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.is_subset-a"></a>a | A set, as returned by <code>sets.make()</code>. | none | +| <a id="sets.is_subset-b"></a>b | A set, as returned by <code>sets.make()</code>. | none | + +**RETURNS** + +True if `a` is a subset of `b`, False otherwise. + +<a id="#sets.disjoint"></a> ## sets.disjoint @@ -254,36 +188,21 @@ Returns whether two sets are disjoint. Two sets are disjoint if they have no elements in common. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.disjoint-a"> - <td><code>a</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - <tr id="sets.disjoint-b"> - <td><code>b</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.disjoint-a"></a>a | A set, as returned by <code>sets.make()</code>. | none | +| <a id="sets.disjoint-b"></a>b | A set, as returned by <code>sets.make()</code>. | none | + +**RETURNS** + +True if `a` and `b` are disjoint, False otherwise. + + +<a id="#sets.intersection"></a> + ## sets.intersection <pre> @@ -292,35 +211,20 @@ sets.intersection(<a href="#sets.intersection-a">a</a>, <a href="#sets.intersect Returns the intersection of two sets. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.intersection-a"> - <td><code>a</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - <tr id="sets.intersection-b"> - <td><code>b</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.intersection-a"></a>a | A set, as returned by <code>sets.make()</code>. | none | +| <a id="sets.intersection-b"></a>b | A set, as returned by <code>sets.make()</code>. | none | + +**RETURNS** + +A set containing the elements that are in both `a` and `b`. + +<a id="#sets.union"></a> ## sets.union @@ -330,27 +234,20 @@ sets.union(<a href="#sets.union-args">args</a>) Returns the union of several sets. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.union-args"> - <td><code>args</code></td> - <td> - optional. - <p> - An arbitrary number of sets or lists. - </p> - </td> - </tr> - </tbody> -</table> +**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`. + + +<a id="#sets.difference"></a> + ## sets.difference <pre> @@ -359,35 +256,20 @@ sets.difference(<a href="#sets.difference-a">a</a>, <a href="#sets.difference-b" Returns the elements in `a` that are not in `b`. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.difference-a"> - <td><code>a</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - <tr id="sets.difference-b"> - <td><code>b</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.difference-a"></a>a | A set, as returned by <code>sets.make()</code>. | none | +| <a id="sets.difference-b"></a>b | A set, as returned by <code>sets.make()</code>. | none | + +**RETURNS** + +A set containing the elements that are in `a` but not in `b`. + +<a id="#sets.length"></a> ## sets.length @@ -397,27 +279,20 @@ sets.length(<a href="#sets.length-s">s</a>) Returns the number of elements in a set. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.length-s"> - <td><code>s</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.length-s"></a>s | A set, as returned by <code>sets.make()</code>. | none | + +**RETURNS** + +An integer representing the number of elements in the set. + + +<a id="#sets.remove"></a> + ## sets.remove <pre> @@ -429,35 +304,20 @@ Removes an element from the set. Element must be hashable. This mutates the original set. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.remove-s"> - <td><code>s</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - <tr id="sets.remove-e"> - <td><code>e</code></td> - <td> - required. - <p> - The element to be removed. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.remove-s"></a>s | A set, as returned by <code>sets.make()</code>. | 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 @@ -467,27 +327,20 @@ sets.repr(<a href="#sets.repr-s">s</a>) Returns a string value representing the set. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.repr-s"> - <td><code>s</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.repr-s"></a>s | A set, as returned by <code>sets.make()</code>. | none | + +**RETURNS** + +A string representing the set. + + +<a id="#sets.str"></a> + ## sets.str <pre> @@ -496,24 +349,15 @@ sets.str(<a href="#sets.str-s">s</a>) Returns a string value representing the set. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.str-s"> - <td><code>s</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.str-s"></a>s | A set, as returned by <code>sets.make()</code>. | none | + +**RETURNS** + +A string representing the set. |