Skip to main content

Collection functions

The following list contains the functions that you can use to manipulating 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().


  • contains()
  • count_by()
  • every()
  • filter()
  • find()
  • find_last()
  • flat_map()
  • flat_map_deep()
  • flat_map_depth()
  • group_by()
  • includes()
  • key_by()
  • length()
  • map()
  • order_by()
  • partition()
  • reduce()
  • reduce_right()
  • reject()
  • sample()
  • sample_size()
  • shuffle()
  • size()
  • some()
  • sort()
  • sort_by()
  • sort_with()