OldAPI/set/ProposalK

/*** 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 */