NAME
    List.Utils

DESCRIPTION
    This module provides functions to operate on lists.

    Most function can operate on elements of JavaScript Arrays or on
    properties of generic Objects.

  List.Utils.grep(FUNCTION, DATA, [RESULT])
    This function selects elements from list DATA for which function
    FUNCTION returns non-false value and stores in RESULT list. Each call to
    FUNCTION passes two arguments: value of processed element and its index
    (array index or property name depending of DATA type).

    If this function is used without RESULT argument new container is
    created, its type is this same as type of DATA.

         grep(function(a){return a>5}, [1,2,3,4,5,6,7,8,9]) = [6,7,8,9]
         grep(function(a){return a>5}, [1,3,5,7,9], {}) = {3: 7, 4: 9}
         grep(function(a,b){return b&1}, {1:"a",2:"b",3:"c"], []) = ["a","c"]

  List.Utils.map(FUNCTION, DATA, [RESULT])
    This function returns new list created from DATA list elements by
    FUNCTION function. Each call to FUNCTION passes two arguments: value of
    processed element and its index (array index or property name depending
    of DATA type).

    If this function is used without RESULT argument new container is
    created, its type is this same as type of DATA.

         map(function(a){return a*2}, [1,2,3,4,5]) = [2,4,6,8,10]
         map(function(a,b){return a+b}, {1:3, 2:2, 3:1}, []) = [4,4,4]

  List.Utils.iterate(FUNCTION, DATA)
    This function invokes function FUNCTION for each element in list DATA.
    Each call to FUNCTION passes two arguments: value of processed element
    and its index (array index or property name depending of DATA type).

         map(function(a){return a*2}, [1,2,3,4,5]) = [2,4,6,8,10]
         map(function(a,b){return a+b}, {1:3, 2:2, 3:1}, []) = [4,4,4]

  List.Utils.find(FUNCTION, DATA)
    This function finds index of first element for which function FUNCTION
    returns non-false value.

    Each call to FUNCTION passes two arguments: value of processed element
    and its index (array index or property name depending of DATA type).

        find(function(a,b){return a>3}, [1,1,3,3,5,5]) = 4
        find(function(a,b){return a>3}, {a:1, b:2, c:3, d:4}) = "d"

  List.Utils.defined(DATA, [RESULT])
    This function creates new list from LIST elements by removing all "null"
    and "undefined" elements.

        defined([1,2,null,4,5]) = [1,2,4,5]
        defined({"a":1, "b":null, "c":3}) = [1,3]

  List.Utils.any(FUNCTION, DATA)
    This function checks that FUNCTION return non-false value for any LIST
    elements.

    Each call to FUNCTION passes two arguments: value of processed element
    and its index (array index or property name depending of DATA type).

        any(function(a){a>4}, [1,2,3,4]) = true
        any(function(a){a>4}, {1:1, 2:2}) = false

  List.Utils.all(FUNCTION, DATA)
    This function checks that FUNCTION return non-false value for all LIST
    elements.

    Each call to FUNCTION passes two arguments: value of processed element
    and its index (array index or property name depending of DATA type).

        all(function(a){a>4}, [1,2,3,4]) = false
        all(function(a){a>4}, {1:5, 2:9}) = true

  List.Utils.bsearch(ARRAY, ELEMENT, COMPARATOR)
    This function finds lowest index of ARRAY element which is greater or
    equal to ELEMENT.

    Two argument function COMPARATOR, which is used as array element
    comparator, should return value "< 0" when its first argument is lower
    than second, "> 0" when second in bigger and 0 when both arguments are
    equal.

         bsearch([1,2,4,6,7], 5, function(a,b){ return a - b }) = 3
         bsearch([1,2,3,4,5,6,7], 5, function(a,b){ return a - b }) = 4

    Note: This function operate only on Arrays

  List.Utils.insertIntoList(ARRAY, ELEMENT, [COMPARATOR])
    This function insert element into list only when ARRAY doesn't contains
    ELEMENT already.

    Two argument function COMPARATOR, which is used to compare array
    elements should return "true" when elements are equal, and "false"
    otherwise.

    This function returns number of items inserted into array (0 or 1).

        insertIntoList([1,2,3,4], 3) = [1,2,3,4]
 
        insertIntoList([2,3,4], 1) = [2,3,4,1]
 
        insertIntoList([{key:1, value:2}, {key:2, value: 2}],
          {key:2, value: 3}, function(a,b){return a.key == b.key}) =
            [{key:1, value:2}, {key:2, value: 2}]
 
        insertIntoList([{key:1, value:2}, {key:2, value: 2}],
          {key:3, value: 2}, function(a,b){return a.key == b.key}) =
            [{key:1, value:2}, {key:2, value: 2}, {key:3, value: 2}]

    Note: This function operate only on Arrays

  List.Utils.removeFromList(ARRAY, ELEMENT, [COMPARATOR], [ALL])
    This function removes ELEMENT from ARRAY. If multiple ELEMENTs exists in
    ARRAY and ALL is non-true only first one will be removed. If ALL is
    non-false all elements will be removed.

    Two argument function COMPARATOR, which is used to compare array
    elements should return "true" when elements are equal, and "false"
    otherwise.

    This function returns number of removed elements.

        removeFromList([1,2,3,4,3], 3) = [1,2,4]
  
        removeFromList([{key:1, value:2}, {key:2, value: 2}], {key:1, value: 5},
          function(a,b){return a.key == b.key}) =
            [{key:2, value: 2}]

    Note: This function operate only on Arrays

AUTHOR
    Pawel Chmielowski <prefiks@aviary.pl>

</html>