Collections/A

From CommonJS Spec Wiki
Jump to: navigation, search

STATUS: RECOMMENDATION. NOT STANDARDS TRACK

Lookup Table

del(key) this
  • Deletes an item for a key.
  • Returns the mutated collection.
  • For ordered collections, accepts a beginning key and an ending key, deleting all items in that range of keys excluding the ending key.
  • Implemented in terms of remove.
set(key, value) this
  • Adds or overwrites an item for a key.
  • Returns the mutated collection.
  • Implemented in terms of insert.
cut(key, value_opt) Value
  • Deletes an item for a key.
  • If no item has the given key and no default value is provided, throws a KeyError.
  • Returns the corresponding value, or the default value.
  • Implemented in terms of get and del.
has(key, eq_opt, hash_opt) Boolean
  • Returns whether key is among items.
put(key, value) Value
  • Adds an item for a key.
  • returns the mutated collection.
  • In an ordered collection, reserves the right to change the keys of some other items to make room for the new item by shifting later items right.
  • Throws a key error if there is already an item with that key and it cannot be moved to a different key.
  • Implemented in terms of set and has.
get(key, value_opt) Value
  • Returns a value for the given key.
  • If there is no value for the given key and no default value is provided, throws a KeyError.
  • Implemented in terms of retrieve and has.
getset(key, value) Value
  • If there is no value for the given key, sets the value for the key to the given value.
  • Returns the value for the given key.
  • Implemented in terms of get and set.
keys() Set of Key
values() Array of Value
items() Array of [Key, Value] pairs

Lookup Set

insert(item, eq_opt, hash_opt) this
  • Adds or overwrites a value.
  • Returns the mutated collection.
  • Defaults to an implementation in terms of find and set.
retrieve(item, eq_opt, hash_opt) Item
  • Returns the contained value that is naturally equivalent to a given value.
  • Throws a value error if none exists.
  • Defaults to an implementation in terms of find and get.
remove(item, eq_opt, hash_opt) this
  • Removes a value.
  • Throws a value error if the value isn't in the collection.
  • Returns the mutated collection.
  • Defaults to an implementation in terms of find and del.
discard(item, eq_opt, hash_opt) this
  • Removes a value if it exists.
  • Returns the mutated collection.
  • Implemented in terms of has and remove.
find(item, eq_opt, hash_opt) Item
  • Returns the key for a given value.
  • Accepts an optional equivalence relation to override the default of eq.