OldAPI/dict/ProposalK

/*** Dict
    an unordered collection of key to value mappings.
    Unlike `Object`, a `Dict` object's key domain includes any
    object, with better performance when the `hash` of each
    key does not collide.  That is, the `Number` ``1`` and the
    `String` ``"1"`` are distinct objects.

    `Dict` inherits from  `Iterable` and `Set`, overriding the `eq` and
    `hash` of the underlying `Set` to use versions that hash and compare
    equivalence based on the pair component of key value pairs.

    Different than Python ``dict``:

    - ``update``: `add`
    - ``has_key``: `hasKey`
    - ``iteritems``: `itemsIter`
    - ``iterkeys``: `keysIter`
    - ``itervalues``: `valuesIter`
    - ``fromkeys(S, v)``: ``Dict(each(S.keys(), function (k) {return [k, v]}))``
    - ``setdefault``: use `set` and `get`
    - ``__del__`` -> `remove`
    - ``__contains__`` -> `has`

    Same as Python:

    - `get`
    - `clear`
    - `copy`
    - `items`
    - `keys`
    - `values`
    - `pop`

*/

    /**** keysIter
        returns an `Iter` of keys from the 
        key and value pairs (items) in the dictionary.
        Uses `itemsIter`.

        - `stateless`
    */

    /**** keys
        returns a `Set` of keys from the 
        key and value pairs (items) in the dictionary.
        Uses `keysIter` and `itemsIter`.

        - `stateless`
    */

    /**** valuesIter
        returns an `Iter` of values from the
        key and value pairs (items) in the dictinoary.
        Uses `itemsIter`.

        - `stateless`
    */

    /**** values
        returns a `List` of values from the
        key and value pairs (items) in the dictionary.
        Uses `valuesIter` and `itemsIter`.

        - `stateless`
    */

    /**** itemsIter
        returns an iteration, `Iter`, of the key and
        value pairs (items) in the dictionary.
        Items are represented as native JavaScript
        `Array` objects.
        Uses `iter`, which is defined for the
        `Set` base-type.

        - `stateless`
    */

    /**** items
        returns a `List` of the key and value
        pairs (items) in the dictionary.
        Items are represnted as native JavaScript
        `Array` objects.
        Uses `itemsIter`.

        - `stateless`
    */

    /**** get
        returns the value of an item in
        the dictionary that has a given
        key.  If there is item for the key,
        attempts to return a default value, 
        checking whether you've specified
        a default value to return as a second
        argument, or deferring to `getDefault`.
        If no acceptable default exists,
        throws a `KeyError`.

        accepts:
        - a key (any object)
        - an optional default value, which
           can be `undefined` or `null`
           if you wish to avoid throwing
           a `KeyError`.

        - `stateless`
    */

    /**** set 
        stores a key and corresponding value
        (an item) in the dictionary.  If
        an item already exists in the dictionary
        that has the same key, it is overwritten.

        - stateful
        - chainable
    */

    /**** put
        an alias for `set`
    */

    /**** has
        returns whether a dictionary contains
        a given key.
    */

    /**** cut
        returns the value for a given key and
        removes the corresponding key, value pair
        from the dictionary.

        - `stateful`
    */

    /**** del
        deletes the key and value pair (item)
        in the dictionary
        that has a given key.

        - `stateful`
        - `chainable`
    */

    /**** getDefault
        an overridable function that returns
        a value or throws a KeyError if you
        attempt to `get` an item for a key
        that the dictionary does not contain.

        - `stateless`, but overrides may
           be stateful.
    */

    /**** hasValue
        returns whether the dictionary contains
        an item with the given value.

        - `stateless`
    */

    /**** hasKey
        an alias of `has`

        - `stateless`
    */

    /**** update
        Sets the given iterable of key value pairs on this
        dictionary, overriding any existing keys.

        - `stateful`
        - `chainable`
    */

    /**** updated
        Returns a new copy of this dictionary that has been
        updated with the pairs in a given iterable.
        
        - `stateless`
        - `chainable`
    */

    /**** complete
        Sets the given iterable of key value pairs on this
        dictionary, except for those with existing keys.

        - `stateful`
        - `chainable`
    */

    /**** completed
        Returns a new copy of this dictionary that has been
        completed with the pairs in a given iterable.

        - `stateless`
        - `chainable`
    */

    /**** find
        - `stateless`
    */

    /**** findReverse
        since dictionary keys are not ordered, `findReverse`
        is an alias of `find`.

        - `stateless`
    */

    /**** add
        - `stateful`
        - `chainable`
    */

    /**** added
        - `stateless`
        - `chainable`
    */

    /**** eq
        - `stateless`
    */

    /**** repr
        - `stateless`
    */

    /**** string
        - `stateless`
    */

    /**** hash
        - `stateless`
    */

    /**** invoke
        an alias of `get` that permits a dictionary
        to be used as a unary relation on its 
        domain of keys to its range of values.
    */

/*** toDict
*/

/*** toObject
    Creates a new native JavaScript `Object`
    from any instance.

    Defers to any user defined `toObject` method
    of the given object.  Failing that, defers
    to `dict` to convert the given object to
    a `Dict` and then creates an `Object` from
    that dictionary's key value pairs.
*/

/*** hasKey
    - `polymorphic`
*/

/*** hasValue
    - `polymorphic`
*/

/*** update
    - `polymoprhic`
    - `stateful`
    - `chainable`
*/

/*** updated
    - `polymorphic`
    - `stateless`
    - `chainable`
*/

/*** complete
    - `polymoprhic`
    - `stateful`
    - `chainable`
*/

/*** completed
    - `polymorphic`
    - `stateless`
    - `chainable`
*/

/*** clear
    removes all key value pairs from list and dict-like objects
    including native Arrays, Objects, and types that override
    the `clear` function like `Dict` and `List`.

    - `polymorphic`
    - `stateful`
    - `chainable`
*/

/*** keys
    - `polymorphic`
    - `stateless`
*/

/*** keysIter
    - `polymorphic`
    - `stateless`
*/

/*** values
    - `polymorphic`
    - `stateless`
*/

/*** valuesIter
    - `polymorphic`
    - `stateless`
*/

/*** items
    - `polymorphic`
    - `stateless`
*/

/*** itemsIter
    - `polymorphic`
    - `stateless`
*/