Skip to main content

Collection functions

Manipulate different collections.

contains()​

Checks if value is in collection. If collection is a string, it's checked for a substring of value, otherwise deep equality is used for equality comparisons. If fromIndex is negative, it's used as the offset from the end of collection.

Aliases: includes()

contains(collection, value, [fromIndex])

Arguments​

collection (Array | Object)
The collection to process.
value (Any)
The value to search for.
fromIndex (Number)
(Optional) The index of the element to start finding from. Default value is 0

Returns​

(Boolean)
true if value is found, else false.

Examples​

InputExpressionResult
"Hello World"
contains(@, 'World')
true
[1, 2, 3]
contains(@, 1)
true
[1, 2, 3]
contains(@, 1, 1)
false
{ "a": 1, "b": 2 }
contains(@, 1)
true

count_by()​

Creates an Object composed of keys generated from the results of running each element of collection thru iteratee. The corresponding value of each key is the number of times the key was returned by iteratee. The iteratee is invoked with one argument (value).

count_by(collection, [iteratee])

Arguments​

collection (Array)
The collection to process.
iteratee (Expression | Array | Object | String)
(Optional) The iteratee invoked for each element of the array. Default value is &@

Returns​

(Object)
The new object with elements count.

Examples​

InputExpressionResult
[6.1, 4.2, 6.3]
count_by(@, &floor(@))
{ "4": 1, "6": 2 }
[
    {
        "type": "red",
        "value": 1
    },
    {
        "type": "green",
        "value": 2
    },
    {
        "type": "blue",
        "value": 1
    }
]
count_by(@, &value)
{ "1": 2, "2": 1 }
[
    {
        "type": "red",
        "value": 1
    },
    {
        "type": "green",
        "value": 2
    },
    {
        "type": "blue",
        "value": 1
    }
]
count_by(@, {type: 'red'})
{
    "true": 1,
    "false": 2
}
["one", "two", "three"]
count_by(@, 'length')
{
    "3": 2,
    "5": 1
}

every()​

Checks if predicate returns truthy for all elements of collection. Iteration is stopped once predicate returns falsey. The predicate is invoked with an array of three arguments: [value, index|key, collection].

Note: This function returns true for empty collections because everything is true of elements of empty collections.

every(collection, [predicate])

Arguments​

collection (Array | Object)
The collection to process.
predicate (Expression | Array | Object | String)
(Optional) an expression, should return truthy for all elements in the collection, otherwise function will return false. Default value is &[0]

Returns​

(Boolean)
true if all elements pass the predicate check, else false.

Examples​

InputExpressionResult
[2.1, 3.5, 4.6]
every(@, &floor([0])>2)
false
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 35
    },
    {
        "name": "Fred",
        "age": 20
    }
]
every(@, &[0].age>18)
true
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 35
    },
    {
        "name": "Fred",
        "age": 20
    }
]
every(@, &length([0].name)>3)
false

filter()​

Iterates over elements of collection, returning an array of all elements predicate returns truthy for. The predicate is invoked with an array of three arguments: [value, index|key, collection].

filter(collection, [predicate])

Arguments​

collection (Array | Object)
The collection to process.
predicate (Expression | Array | Object | String)
(Optional) The expression invoked per iteration. Default value is &[0]

Returns​

(Array)
The resulted array with filtered elements.

Examples​

InputExpressionResult
[2.1, 3.5, 4.6]
filter(@, &floor([0])>2)
[3.5, 4.6]
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 35
    },
    {
        "name": "Fred",
        "age": 20
    }
]
filter(@, &[0].age>20)
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 35
    }
]

See also​

find()​

Iterates over elements of collection, returning the first element predicate returns truthy for. The predicate is invoked with an array of three arguments: [value, index|key, collection].

find(collection, [predicate], [fromIndex])

Arguments​

collection (Array | Object)
The collection to process.
predicate (Expression | Array | Object | String)
(Optional) The expression invoked per iteration. Default value is &[0]
fromIndex (Number)
(Optional) The index of the element to search from. Default value is 0

Returns​

(Any)
The matched element, else null.

Examples​

InputExpressionResult
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 35
    },
    {
        "name": "Fred",
        "age": 20
    }
]
find(@, &[0].name == 'Ben')
{
    "name": "Ben",
    "age": 35
}
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 35
    },
    {
        "name": "Fred",
        "age": 20
    }
]
find(@, &[0].age < 40, 2)
{
    "name": "Fred",
    "age": 20
}

See also​

find_last()​

This function is like find() except that it iterates over elements of collection from right to left. The predicate is invoked with an array of three arguments: [value, index|key, collection].

find_last(collection, [predicate], [fromIndex])

Arguments​

collection (Array | Object)
The collection to process.
predicate (Expression | Array | Object | String)
(Optional) The expression invoked per iteration. Default value is &[0]
fromIndex (Number)
(Optional) The index of the element to search from. Default value is length(collection)-1

Returns​

(Any)
The matched element, else null.

Examples​

InputExpressionResult
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 35
    },
    {
        "name": "Fred",
        "age": 20
    }
]
find_last(@, &[0].age > 25)
{
    "name": "Ben",
    "age": 35
}

flat_map()​

Creates a flattened array of values by running each element in collection thru mapper and flattening the mapped results. The mapper is invoked with an array of three named arguments: [value, index|key, collection].

flat_map(collection, [mapper])

Arguments​

collection (Array | Object | Null)
The collection to process.
mapper (Expression | Array | Object | String)
(Optional) The expression invoked per iteration. Expression signature is (value, index|key, collection). Default value is &value.

Returns​

(Array)
The new flattened array.

Examples​

InputExpressionResult
[
    {
        "name": "feature1",
        "versions": ["1.0", ["2.0", "2.1"]]
    },
    {
        "name": "feature2",
        "versions": ["1.0", "2.0"]
    }
]
flat_map(@, &[0].versions)
["1.0", ["2.0", "2.1"], "1.0", "2.0"]

See also​

flat_map_deep()​

This method is similar to flat_map(); it creates a flattened array of values by running each element in collection thru mapper and flattening the mapped results recursively. The mapper is invoked with an array of three named arguments: [value, index|key, collection].

flat_map_deep(collection, [mapper])

Arguments​

collection (Array | Object | Null)
The collection to process.
mapper (Expression | Array | Object | String)
(Optional) The expression invoked per iteration. Expression signature is (value, index|key, collection). Default value is &value.

Returns​

(Array)
The new flattened array.

Examples​

InputExpressionResult
[
    {
        "name": "feature1",
        "versions": ["1.0", ["2.0", "2.1"]]
    },
    {
        "name": "feature2",
        "versions": ["1.0", "2.0"]
    }
]
flat_map_deep(@, &[0].versions)
["1.0", "2.0", "2.1", "1.0", "2.0"]

See also​

flat_map_depth()​

This method is similar to flat_map(); it creates a flattened array of values by running each element in collection thru mapper and flattening the mapped results recursively up to depth times. The mapper is invoked with an array of three named arguments: [value, index|key, collection].

flat_map_depth(collection, [mapper], [depth])

Arguments​

collection (Array | Object | Null)
The collection to process.
mapper (Expression | Array | Object | String)
(Optional) The expression invoked per iteration. Expression signature is (value, index|key, collection). Default value is &value.
depth (Number)
(Optional) The maximum recursion depth. Default value is 1.

Returns​

(Array)
The new flattened array.

Examples​

InputExpressionResult
[
    {
        "name": "feature1",
        "versions": ["1.0", ["2.0", "2.1"]]
    },
    {
        "name": "feature2",
        "versions": ["1.0", "2.0"]
    }
]
flat_map_depth(@, &[0].versions, 2)
["1.0", "2.0", "2.1", "1.0", "2.0"]

See also​

group_by()​

Creates an object composed of keys generated from the results of running each element of collection thru iteratee. The order of grouped values is determined by the order they occur in collection. The corresponding value of each key is an array of elements responsible for generating the key. The iteratee is invoked with one argument: @ (current element).

group_by(collection, [iteratee])

Arguments​

collection (Array | Object)
The collection to process.
iteratee (Expression | Array | Object | String)
(Optional) The expression invoked per iteration. The iteratee expression is invoked with one argument: @ (current element). Default value is &@.

Returns​

(Object)
The composed aggregate object.

Examples​

InputExpressionResult
[1.1, 1.5, 2.0, 2.3, 2.6]
group_by(@, &floor(@))
{
    "1": [1.1, 1.5],
    "2": [2, 2.3, 2.6]
}
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 40
    },
    {
        "name": "Fred",
        "age": 30
    }
]
group_by(@, &age)
{
    "30": [
        {
            "name": "Fred",
            "age": 30
        }
    ],
    "40": [
        {
            "name": "Mike",
            "age": 40
        },
        {
            "name": "Ben",
            "age": 40
        }
    ]
}

includes()​

Alias for contains().

key_by()​

Creates an object composed of keys generated from the results of running each element of collection thru iteratee. The corresponding value of each key is the last element responsible for generating the key. The iteratee is invoked with one argument: @ (current element).

key_by(collection, [iteratee])

Arguments​

collection (Array | Object | Null)
The collection to iterate over.
iteratee (Expression | Array | Object | String)
(Optional) The expression invoked per iteration. The iteratee expression is invoked with one argument: @ (current element). Default value is &@.

Returns​

(Object)
The composed aggregate object.

Examples​

InputExpressionResult
[
    {
        "dir": "left",
        "code": 97
    },
    {
        "dir": "right",
        "code": 100
    }
]
key_by(@, 'dir')
{
    "left": {
        "dir": "left",
        "code": 97
    },
    "right": {
        "dir": "right",
        "code": 100
    }
}
[
    {
        "dir": "left",
        "code": 97
    },
    {
        "dir": "right",
        "code": 100
    }
]
key_by(@, &join(['id',code],'_'))
{
    "id_97": {
        "dir": "left",
        "code": 97
    },
    "id_100": {
        "dir": "right",
        "code": 100
    }
}

length()​

Alias for size().

map()​

Creates an array of values by running each element in collection thru mapper. The mapper is invoked with an array of three named arguments: [value, index|key, collection].

map(collection, [mapper])

Arguments​

collection (Array | Object | Null)
The collection to process.
mapper (Expression | Array | Object | String)
(Optional) The expression invoked per iteration. Expression signature is (value, index|key, collection). Default value is &value.

Returns​

(Array)
The new mapped array.

Examples​

InputExpressionResult
[4, 8]
map(@, &add([0], 2))
[6, 10]
{ "a": 4, "b": 8 }
map(@, &add([0], 2))
[6, 10]
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 40
    },
    {
        "name": "Fred",
        "age": 30
    }
]
map(@, &[0].name)
["Mike", "Ben", "Fred"]

See also​

order_by()​

This method is like sort_by() except that it allows specifying the sort orders of the iteratees to sort by. If orders is unspecified, all values are sorted in ascending order. Otherwise, specify an order of desc for descending or asc for ascending sort order of corresponding values.

order_by(collection, [iteratees], [orders])

Arguments​

collection (Array | Object)
The collection to process.
iteratee (Expression | Array | Object | String)
(Optional) The expression invoked per iteration. The iteratee expression is invoked with one argument: @ (current element). Default value is &@.
orders (String | Array)
(Optional) The sort orders of iteratees. Default value is asc

Returns​

(Array)
The new sorted array.

Examples​

InputExpressionResult
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 50
    },
    {
        "name": "Fred",
        "age": 30
    }
]
order_by(@, &age)
[
    {
        "name": "Fred",
        "age": 30
    },
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 50
    }
]
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 50
    },
    {
        "name": "Fred",
        "age": 30
    }
]
order_by(@,
    [&length(name), &age],
    ['asc', 'desc']
)
[
  {
    "name": "Ben",
    "age": 50
  },
  {
    "name": "Mike",
    "age": 40
  },
  {
    "name": "Fred",
    "age": 30
  }
]

See also​

partition()​

Creates an array of elements of the collection split into two groups, the first of which contains elements predicate returns truthy for, the second of which contains elements predicate returns falsey for. The predicate is invoked with one argument: (value).

partition(collection, [predicate])

Arguments​

collection (Array | Object)
The collection to process.
predicate (Expression | Array | Object | String)
(Optional) The expression, invoked per iteration. Default value is &[0]

Returns​

(Array)
The array of grouped elements.

Examples​

InputExpressionResult
[0, 1, 2, 3, 4]
partition(@, &@ > 2)
[
    [3, 4],
    [0, 1, 2]
]
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 50
    },
    {
        "name": "Fred",
        "age": 30
    }
]
partition(@, &age > 30)
[
    [
        {
            "name": "Mike",
            "age": 40
        },
        {
            "name": "Ben",
            "age": 50
        }
    ],
    [
        {
            "name": "Fred",
            "age": 30
        }
    ]
]

reduce()​

Reduces collection to a value which is the accumulated result of running each element in collection thru iteratee, where each successive invocation is supplied the return value of the previous. If accumulator is not given, the first element of collection is used as the initial value. The iteratee is invoked with an array of four arguments: (accumulator, value, index|key, collection).

reduce(collection, [iteratee], [accumulator])

Arguments​

collection (Array | Object)
The collection to process.
predicate (Expression | Array | Object | String)
(Optional) The expression, invoked per iteration. Default value is &[0]
accumulator (Any)
(Optional) The initial value of the accumulator. Default value is the first element of collection

Returns​

(Any)
The accumulated value.

Examples​

InputExpressionResult
[1, 2, 3, 4, 5]
reduce(@, &multiply([0], [1]))
120
{
    "a": 1,
    "b": 2,
    "c": 1
}
reduce(@,
  &set(
    [0],
    [[1]],
    [
      get([0], [[1]]),
      [2]
    ][]
  ),
`{}`)
{
    "1": ["a", "c"],
    "2": ["b"]
}

See also​

reduce_right()​

This method is like reduce() except that it iterates over elements of collection from right to left.

reduce_right(collection, [iteratee], [accumulator])

Arguments​

collection (Array | Object)
The collection to process.
predicate (Expression | Array | Object | String)
(Optional) The expression, invoked per iteration. Default value is &[0]
accumulator (Any)
(Optional) The initial value of the accumulator. Default value is the first element of collection

Returns​

(Any)
The accumulated value.

Examples​

InputExpressionResult
[1, 2, 3, 4]
reduce_right(@, &[[0], [1]] | [])
[4, 3, 2, 1]

See also​

reject()​

The opposite of filter() this function returns the elements of collection that predicate does not return truthy for. The iteratee is invoked with an array of three arguments: (value, index|key, collection).

reject(collection, [predicate])

Arguments​

collection (Array | Object)
The collection to process.
predicate (Expression | Array | Object | String)
(Optional) The expression, invoked per iteration. Default value is &[0]

Returns​

(Array)
The new filtered array.

Examples​

InputExpressionResult
[2.1, 3.5, 4.6]
reject(@, &floor([0]) > 3)
[2.1, 3.5]
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 35
    },
    {
        "name": "Fred",
        "age": 20
    }
]
reject(@, &[0].age > 20)
[
    {
        "name": "Fred",
        "age": 20
    }
]

See also​

sample()​

Gets a random element from collection.

sample(collection)

Arguments​

collection (Array | Object)
The collection to process.

Returns​

(Any)
The random element from the original collection.

Examples​

InputExpressionResult
[1, 2, 3, 4, 5]
sample(@)
2

See also​

sample_size()​

Gets n random elements at unique keys from collection up to the size of collection.

sample_size(collection, [n])

Arguments​

collection (Array | Object)
The collection to process.
n (Number)
(Optional) The number of elements to sample. Default value is 1

Returns​

(Array)
The array with random elements from the original collection.

Examples​

InputExpressionResult
[1, 2, 3, 4, 5]
sample_size(@, 3)
[2, 5, 1]
[1, 2, 3, 4, 5]
sample_size(@, 6)
[1, 5, 4, 3, 2]

See also​

shuffle()​

Creates an array of shuffled values from the collection, using a version of the Fisher-Yates shuffle algorithm.

shuffle(collection)

Arguments​

collection (Array | Object)
The collection to process.

Returns​

(Array)
The new array with shuffled elements.

Examples​

InputExpressionResult
[1, 2, 3, 4, 5]
shuffle(@)
[3, 4, 5, 2, 1]
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 35
    },
    {
        "name": "Fred",
        "age": 20
    }
]
shuffle(@)
[
    {
        "name": "Ben",
        "age": 35
    },
    {
        "name": "Fred",
        "age": 20
    },
    {
        "name": "Mike",
        "age": 40
    }
]

size()​

Gets the size of collection by returning its length for array-like values or the number of own enumerable string keyed properties for objects.

Aliases: length().

size(collection)

Arguments​

collection (Array | Object)
The collection to process.

Returns​

(Number)
The collection size.

Examples​

InputExpressionResult
[1, 2, 3, 4, 5]
size(@)
5
{ "a": 1, "b": 2 }
size(@)
2
"Hello World!"
size(@)
12

some()​

Checks if predicate returns truthy for any element of collection. Iteration is stopped once predicate returns truthy. The predicate is invoked with an array of three arguments: [value, index|key, collection].

some(collection, [predicate])

Arguments​

collection (Array | Object)
The collection to process.
predicate (Expression | Array | Object | String)
(Optional) The expression, invoked per iteration. Default value is &[0]

Returns​

(Boolean)
true if any element passes the predicate check, else false.

Examples​

InputExpressionResult
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 35
    },
    {
        "name": "Fred",
        "age": 20
    }
]
some(@, &[0].name=='Ben')
true

sort()​

Returns an array of collection elements, sorted in ascending order with custom comparator. A comparator represents a compare function determining which element comes before the other.

This function performs a stable sort, that is, it preserves the original sort order of equal elements. The comparator is invoked with an array of two elements: [element, otherElement].

Aliases: sort_with().

sort(collection, [comparator])

Arguments​

collection (Array | Object)
The collection to process.
comparator (Expression)
(Optional) The comparator expression invoked per element to compare elements of arrays. Default value is &([0] > [1] && 1 || [0] < [1] && -1 || 0)

Returns​

(Array)
The new sorted array.

Examples​

InputExpressionResult
[
    { "name": "Scotty", "age": 18 },
    { "name": "Tommy", "age": 21 },
    { "name": "Sally", "age": 71 },
    { "name": "Billy", "age": 18 },
    { "name": "Timmy", "age": 21 }
]
sort(@,
  &(
    [0].age > [1].age && 1 ||
    [0].age < [1].age && -1 ||
    0
  )
)
[
    {
        "name": "Scotty",
        "age": 18
    },
    {
        "name": "Billy",
        "age": 18
    },
    {
        "name": "Tommy",
        "age": 21
    },
    {
        "name": "Timmy",
        "age": 21
    },
    {
        "name": "Sally",
        "age": 71
    }
]

sort_by()​

Creates an array of elements, sorted in ascending order by the results of running each element in a collection thru each iteratee. This method performs a stable sort, that is, it preserves the original sort order of equal elements.

sort_by(collection, [iteratees])

Arguments​

collection (Array | Object)
The collection to process.
iteratees (Expression | Expression[] | Array | Object | String)
(Optional) The expression invoked per iteration. The iteratee expression is invoked with one argument: @ (current element). Default value is &@.

Returns​

(Array)
The new sorted array.

Examples​

InputExpressionResult
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 35
    },
    {
        "name": "Fred",
        "age": 20
    }
]
sort_by(@, &age)
[
    {
        "name": "Fred",
        "age": 20
    },
    {
        "name": "Ben",
        "age": 35
    },
    {
        "name": "Mike",
        "age": 40
    }
]
[
    {
        "name": "Mike",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 35
    },
    {
        "name": "Fred",
        "age": 20
    }
]
sort_by(@, [&length(name), &age])
[
    {
        "name": "Ben",
        "age": 35
    },
    {
        "name": "Fred",
        "age": 20
    },
    {
        "name": "Mike",
        "age": 40
    }
]
[
    {
        "name": "Fred",
        "age": 40
    },
    {
        "name": "Ben",
        "age": 35
    },
    {
        "name": "Fred",
        "age": 20
    }
]
sort_by(@, ['name', 'age'])
[
    {
        "name": "Ben",
        "age": 35
    },
    {
        "name": "Fred",
        "age": 20
    },
    {
        "name": "Fred",
        "age": 40
    }
]

See also​

sort_with()​

Alias for sort().