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).

List.Utils.findInList(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).

    findInList(function(a,b){return a>3}, [1,1,3,3,5,5]) = 4
    findInList(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}) = {"a": 1, "c": 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){return a>=4}, [1,2,3,4]) = true
    any(function(a){return 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){return a>=4}, [1,2,3,4]) = false
    all(function(a){return 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, 3]

    removeFromList([1,2,3,4,3], 3, null, true) = [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>