ServerJS/API/set/ProposalK
From MozillaWiki
/*** Set
An unordered collection of unique values.
Accepts:
- optional ``values`` (may be ``undefined``, or any iterable object,
by way of the polymorphic `toIter`)
- optional custom ``hash`` relation.
- optional custom ``eq`` binary equivalence relation.
Inherits member functions from `Iterable`.
`Set` operations operate in constant time best case,
and linear for degenerate cases.
If you insert an object in a set and modify that object
in such a way that its ``hash`` result changes, it
will be irrecoverable.
Most other libraries enforce that only immutable
objects should be inserted in sets for this reason,
so be careful.
*/
/*** insert
inserts a value in the `Set`.
Position is not relevant. Replaces
an existing value if the value has the same
`hash` key and is `eq` to an existing
value. The `hash` function and `eq` function
can be overridden in the `Set` constructor.
- `stateful`
- `chainable`
*/
/*** retrieve
retrieves a value from the `Set` that has
the same `hash` key and is `eq` to a given
value. `eq` and `hash` can be overridden
in the `Set` constructor.
- `stateless`
*/
/**** remove
removes a value from the `Set` if it has
the same `hash` and is `eq` to the value.
throws a `ValueError` if no matching value
can be found.
- `stateful`
- `chainable`
*/
/**** discard
discards a value from the `Set` if it has
the same `hash` and is `eq` to the value.
Unlike `remove`, does not throw a `ValueError`
if no matching value can be found.
- `stateful`
- `chainable`
*/
/**** clear
removes all values in this set.
- `stateful`
- `chainable`
*/
/**** has
returns whether a set contains a given value.
uses `eq` and `hash` to attempt to find
the value in the set. These functions
can be overridden in the `Set` constructor.
*/
/**** find
searches all of the values in set for one
that is `eq` to a given value. returns that
value. throws a `ValueError` if no value
can be found.
- accepts a value to find
- accepts an optional override to the `eq` function
- `stateless`
*/
/**** toIter */
/**** eq */
/**** union
augments itself with any values that exist in another
iterable.
- `stateful`
- `chainable`
*/
/**** intersect
- `stateful`
- `chainable`
*/
/**** difference
- `stateful`
- `chainable`
*/
/**** unioned
returns all elements that are in itself and another iterable.
- `stateless`
- `chainable`
*/
/**** intersected
returns all values that are in
this set and another.
- `stateless`
- `chainable`
*/
/**** differenced
returns the set of all values that are
in this set but not another.
- `stateless`
- `chainable`
*/
/**** symmetricDifferenced
returns the set of all values that are exactly one
set between itself and another.
- `stateless`
- `chainable`
*/
/**** isSuperSet
returns whether this set contains all of the values
in a given container.
- `stateless`
*/
/**** isSubSet
returns whether a given container contains all of
this set's values.
- `stateless`
*/
/**** added
alias of `unioned`
- `stateless`
- `chainable`
*/
/**** add
alias of `union`
- `stateful`
- `chainable`
*/
/**** muled
alias of `intersected`
- `stateless`
- `chainable`
*/
/**** mul
alias of `intersect`
- `stateful`
- `chainable`
*/
/**** subed
alias of `differenced`
- `stateless`
- `chainable`
*/
/**** sub
alias of `difference`
- `stateful`
- `chainable`
*/
/**** and
alias of `intersect`
- `stateful`
- `chainable`
*/
/**** anded
alias of `intersected`
- `stateless`
- `chainable`
*/
/**** or
alias of `union`
- `stateful`
- `chainable`
*/
/**** ored
alias of `unioned`
- `stateless`
- `chainable`
*/
/**** xor
alias of `symmetricDifferenced`
- `stateful`
- `chainable`
*/
/**** xored
alias of `symmetricDifferenced`
- `stateless`
- `chainable`
*/
/**
Functions
=========
Functions that operate on sets, or arrays
coercible to sets using the polymorphic
`toSet` function.
*/
/*** toSet */
/*** insert */
/*** retrieve */
/*** remove */
/*** discard */
/*** clear */
/*** has */
/*** union */
/*** intersect */
/*** difference */
/*** symetricDifference */
/*** isSuperSet */
/*** isSubSet */
