OldAPI/list/ProposalK

From CommonJS Spec Wiki
Jump to: navigation, search
/*** List 
    is `Iterable`

    Different than Python:

    - append: `push`
    - extend: `add`
    - count: `len`
    - index: `find`
    - insert: `put`
    - remove: `del`

    Same as Python:

    - `pop`
    - `sort`
    - `reverse`

*/

    /**** toIter
        - `stateless`
    */

    /**** len
        - `stateless`
    */

    /**** push
        - `stateful`
        - `chainable`
    */

    /**** pop
        - `stateful`
    */

    /**** unshift
        - `stateful`
        - `chainable`
    */

    /**** shift
        - `stateful`
    */

    /**** reverse
        - `stateful`
        - `chainable`
    */

    /**** reversed
        - `stateless`
    */

    /**** reversedIter
        - `stateless`
    */

    /**** sort
        - `stateful`
        - `chainable`
    */

    /**** sorted
        - `stateless`
        - `chainable`
    */

    /**** slice
        - `stateful`
        - `chainable`
    */

    /**** sliced
        - `stateless`
        - `chainable`
    */

    /**** splice
        - `stateful`
    */

    /**** spliced
        - `stateless`
        - `chainable`
    */

    /**** clear
        - `stateful`
        - `chainable`
    */

    /**** first
        - `stateless`
    */

    /**** last
        - `stateless`
    */

    /**** begins
        returns whether the first elements of
        a given list-like-object are equal, by way of `eq`,
        the respective elements in this list.

        In Python, this function is called ``startswith``.
        This divergence from Python nomenclature is
        a matter of idealism.  Ideally the semantic group
        of `start`, `stop`, `pause`, `resume`,
        and `run` are all temporal verbs, whereas the
        semantic group `begins`, `ends`, `first`,
        `last`, and such all apply to the state of
        spatial segments or lists.

        - `stateless`
    */

    /**** ends
        returns whether the last elements of a given
        list-like-object are equal, by way of `eq`,
        the respective elements in this list.

        In Python, this function is called ``endsWith``.
        See ``startsWith`` for the rationale.

        - `stateless`
    */

    /**** reduce
        reduce is an in place operation.
        see reduced for a stateless variant

        - `stateful`
        - `chainable`
    */

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

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

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

    /**** values
        an alias of `copy` so that lists can be used
        as dictionary like objects.

        - `stateless`
    */

    /**** itemsIter
        enumerates the values of the list.

        - `stateless`
    */

    /**** items
        returns a list of the enumerated values from 
        this list, using `itemsIter`.

        - `stateless`
    */

    /**** get
        gets a value by its offset.

        - `stateless`
    */

    /**** set
        sets a value at a particular offset.

        - `stateful`
        - `chainable`
    */

    /**** put
        displaces the item at a given index, sending
        successive elements down the line.

        - `stateful`
        - `chainable`
    */

    /**** cut
        gets the value at a given offset and delete
        the value from the list.

        - `stateful`
    */

    /**** del
        removes a value from the list, shifting all
        successive values into its void.
        
        - `stateful`
        - `chainable`
    */

    /**** has
        returns whether the list contains
        a given value.

        - `stateless`
    */

    /**** hasKey
        returns whether the list contains a value
        at a given index.

        - `stateless`
    */

    /**** hasValue
        retunrs whether the list contains
        a given value.
        Uses `has`.

        - `stateless`
    */

    /**** find
        returns the first index of a given value
        in the list, or throws a `ValueError`
        if none can be found.

        - `stateless`
    */

    /**** findReverse
        returns the last index of a given value
        in the list, or throws a `ValueError`
        if none can be found.

        - `stateless`
    */


    /**** insert
        an alias of `push`
    */
    /**** retrieve */
    /**** remove */
    /**** discard */

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

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

    /**** eq
        returns whether this list has the same cardinality, order,
        and respective values as another object.

        - `stateless`
    */

    /**** lt
        returns whether the the most significant, distinct
        value between the respective values of this list and another
        list-like object is less than the other.

        - `stateless`
    */

    /**** join
        returns a `String` of the joined string values of
        the values in this list, on a given delimiter or simply
        concatenated.

        - `stateless`
    */

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

    /**** toArray
        - `stateless`
    */

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

/*** toList
    constructs a `List` from any given iterable.
    Defers to a `toList` or `toIter` method of the given
    object if it exists.

    - `poymorphic` on `toList` or `toIter`
*/

/*** toArray
    constructs a native JavaScript `Array` from
    any iterable.

    - `polymorphic` on `toArray` or `toIter`
*/

/*** len
    returns the length of a `List`, `Array`, `Object`,
    or any other object that provides a `len` member
    function.

    - `polymorphic`
*/

/*** reversed
    returns a `List` of the values from an iterable
    in reversed order.

    - `stateless`
*/

/*** sorted
    returns a `List` of the values in a given `Iteration` in
    sorted order.  Accepts an optional override of `compare`,
    a binary relation that returns a `Number` that has the same
    comparison relationship with ``0`` as the relationship between
    the given values.  For example, ``-1`` if the first is less
    than the second, or ``0`` if they are equal.

    - `stateless`
*/

/*** slice
    - `polymorphic`
    - `not-curry`
    - `stateless`
*/

/*** splice
*/