This module contains helper functions for working with arrays.
To use this module, you must import it to your DataWeave code, for example,
by adding the line import * from dw::core::Arrays
to the header of your
DataWeave script.
Functions
countBy
countBy<T>(array: Array<T>, matchingFunction: (T) -> Boolean): Number
Counts the elements in an array that return true
when the matching function is applied to the value of each element.
Parameters
Name | Description |
---|---|
|
The input array that contains elements to match. |
|
A function to apply to elements in the input array. |
Example
This example counts the number of elements in the input array ([1, 2, 3, 4]) that
return true
when the function (($ mod 2) == 0)
is applied their values. In this
case, the values of two of the elements, both 2
and 4
, match because
2 mod 2 == 0
and 4 mod 2 == 0
. As a consequence, the countBy
function returns 2
.
Note that mod
returns the modulus of the operands.
Source
1
2
3
4
5
%dw 2.0
import * from dw::core::Arrays
output application/json
---
{ "countBy" : [1, 2, 3, 4] countBy (($ mod 2) == 0) }
Output
1
{ "countBy": 2 }
countBy(array: Null, matchingFunction: (Nothing) -> Any): Null
Helper function that enables countBy
to work with a null
value.
divideBy
divideBy<T>(items: Array<T>, amount: Number): Array<Array<T>>
Breaks up an array into sub-arrays that contain the specified number of elements.
When there are fewer elements in the input array than the specified number, the function fills the sub-array with those elements. When there are more elements, the function fills as many sub-arrays needed with the extra elements.
Parameters
Name | Description |
---|---|
|
Items in the input array. |
|
The number of elements allowed per sub-array. |
Example
This example breaks up arrays into sub-arrays based on the specified amount
.
Source
1
2
3
4
5
6
7
8
9
10
11
%dw 2.0
import * from dw::core::Arrays
output application/json
---
{
"divideBy" : [
{ "divideBy2" : [1, 2, 3, 4, 5] divideBy 2 },
{ "divideBy2" : [1, 2, 3, 4, 5, 6] divideBy 2 },
{ "divideBy3" : [1, 2, 3, 4, 5] divideBy 3 }
]
}
Output
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
"divideBy": [
{
"divideBy2": [
[ 1, 2 ],
[ 3, 4 ],
[ 5 ]
]
},
{
"divideBy2": [
[ 1, 2 ],
[ 3, 4 ],
[ 5, 6 ]
]
},
{
"divideBy3": [
[ 1, 2, 3 ],
[ 4, 5 ]
]
}
]
}
divideBy(items: Null, amount: Any): Null
Helper function that enables divideBy
to work with a null
value.
drop
drop<T>(array: Array<T>, n: Number): Array<T>
Drops the first n
elements. It returns the original array when n <= 0
and an empty array when n > sizeOf(array)
.
Parameters
Name | Description |
---|---|
|
The left array of elements. |
|
The number of elements to take. |
Example
This example returns an array that only contains the third element of the input array. It drops the first two elements from the output.
Source
1
2
3
4
5
6
%dw 2.0
import * from dw::core::Arrays
var users = ["Mariano", "Leandro", "Julian"]
output application/json
---
drop(users, 2)
Output
1
2
3
[
"Julian"
]
drop(array: Null, n: Any): Null
Helper function that enables drop
to work with a null
value.
dropWhile
dropWhile<T>(array: Array<T>, condition: (item: T) -> Boolean): Array<T>
Drops elements from the array while the condition is met but stops the selection process when it reaches an element that fails to satisfy the condition.
Parameters
Name | Description |
---|---|
|
The array of elements. |
|
The condition (or expression) used to match an element in the array. |
Example
This example returns an array that omits elements that are less than or equal to 2
.
The last two elements (2
and 1
) are included in the output array because the
function stops dropping elements when it reaches the 3
, which is greater than 2
.
Source
1
2
3
4
5
6
%dw 2.0
import * from dw::core::Arrays
output application/json
var arr = [0,1,3,2,1]
---
arr dropWhile $ < 3
Output
1
2
3
4
5
[
3,
2,
1
]
dropWhile(array: Null, condition: (item: Nothing) -> Any): Null
Helper function that enables dropWhile
to work with a null
value.
every
every<T>(list: Array<T>, condition: (T) -> Boolean): Boolean
Returns true
if every element in the array matches the condition.
The function stops iterating after the first negative evaluation of an element in the array.
Parameters
Name | Description |
---|---|
|
The input array. |
|
A condition (or expression) to apply to elements in the input array. |
Example
This example applies a variety of expressions to the input arrays. The $
references values of the elements.
Source
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
%dw 2.0
import * from dw::core::Arrays
var arr0 = [] as Array<Number>
output application/json
---
{ "results" : [
"ok" : [
[1,1,1] every ($ == 1),
[1] every ($ == 1)
],
"err" : [
[1,2,3] every ((log('should stop at 2 ==', $) mod 2) == 1),
[1,1,0] every ($ == 1),
[0,1,1,0] every (log('should stop at 0 ==', $) == 1),
[1,2,3] every ($ == 1),
arr0 every true,
]
]
}
Output
1
2
3
4
5
6
7
8
9
10
{
"results": [
{
"ok": [ true, true ]
},
{
"err": [ false, false, false, false, false ]
}
]
}
every(value: Null, condition: (Nothing) -> Any): Boolean
Helper function that enables every
to work with a null
value.
firstWith
firstWith<T>(array: Array<T>, condition: (item: T, index: Number) -> Boolean): T | Null
Returns the first element that satisfies the condition, or returns null
if no
element meets the condition.
Parameters
Name | Description |
---|---|
array |
The array of elements to search. |
condition |
The condition to satisfy. |
Example
This example shows how firstWith
behaves when an element matches and when an element does not match.
Source
1
2
3
4
5
6
7
8
9
%dw 2.0
output application/json
import firstWith from dw::core::Arrays
var users = [{name: "Mariano", lastName: "Achaval"}, {name: "Ana", lastName: "Felisatti"}, {name: "Mariano", lastName: "de Sousa"}]
---
{
a: users firstWith ((user, index) -> user.name == "Mariano"),
b: users firstWith ((user, index) -> user.name == "Peter")
}
Output
1
2
3
4
5
6
7
{
"a": {
"name": "Mariano",
"lastName": "Achaval"
},
"b": null
}
firstWith(array: Null, condition: (item: Nothing, index: Nothing) -> Any): Null
Helper function that enables firstWith
to work with a null
value.
indexOf
indexOf<T>(array: Array<T>, toFind: T): Number
Returns the index of the first occurrence of an element within the array. If the value is not found, the function returns -1
.
Parameters
Name | Description |
---|---|
|
The array of elements. |
|
The element to find. |
Example
This example returns the index of the matching value from the input array.
The index of "Julian"
is 2
.
Source
1
2
3
4
5
6
%dw 2.0
import * from dw::core::Arrays
output application/json
var users = ["Mariano", "Leandro", "Julian"]
---
indexOf(users, "Julian")
Output
1
2
indexWhere
indexWhere<T>(array: Array<T>, condition: (item: T) -> Boolean): Number
Returns the index of the first occurrence of an element that matches a
condition within the array. If no element matches the condition, the function returns -1
.
Parameters
Name | Description |
---|---|
|
The array of elements. |
|
The condition (or expression) used to match an element in the array. |
Example
This example returns the index of the value from the input array that
matches the condition in the lambda expression,
(item) → item startsWith "Jul"
.
Source
1
2
3
4
5
6
%dw 2.0
import * from dw::core::Arrays
output application/json
var users = ["Mariano", "Leandro", "Julian"]
---
users indexWhere (item) -> item startsWith "Jul"
Output
1
2
indexWhere(array: Null, condition: (item: Nothing) -> Any): Null
Helper function that enables indexWhere
to work with a null
value.
join
join<L <: Object, R <: Object>(left: Array<L>, right: Array<R>, leftCriteria: (leftValue: L) -> String, rightCriteria: (rightValue: R) -> String): Array<Pair<L, R>>
Joins two arrays of objects by a given ID criteria.
join
returns an array all the left
items, merged by ID with any
right items that exist.
Parameters
Name | Description |
---|---|
|
The left-side array of objects. |
|
The right-side array of objects. |
|
The criteria used to extract the ID for the left collection. |
|
The criteria used to extract the ID for the right collection. |
Example
This example shows how join behaves. Notice that the output only includes
objects where the values of the input user.id
and product.ownerId
match.
The function includes the "l"
and "r"
keys in the output.
Source
1
2
3
4
5
6
7
%dw 2.0
import * from dw::core::Arrays
var users = [{id: "1", name:"Mariano"},{id: "2", name:"Leandro"},{id: "3", name:"Julian"},{id: "5", name:"Julian"}]
var products = [{ownerId: "1", name:"DataWeave"},{ownerId: "1", name:"BAT"}, {ownerId: "3", name:"DataSense"}, {ownerId: "4", name:"SmartConnectors"}]
output application/json
---
join(users, products, (user) -> user.id, (product) -> product.ownerId)
Output
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
[
{
"l": {
"id": "1",
"name": "Mariano"
},
"r": {
"ownerId": "1",
"name": "DataWeave"
}
},
{
"l": {
"id": "1",
"name": "Mariano"
},
"r": {
"ownerId": "1",
"name": "BAT"
}
},
{
"l": {
"id": "3",
"name": "Julian"
},
"r": {
"ownerId": "3",
"name": "DataSense"
}
}
]
leftJoin
leftJoin<L <: Object, R <: Object>(left: Array<L>, right: Array<R>, leftCriteria: (leftValue: L) -> String, rightCriteria: (rightValue: R) -> String): Array<{ l: L, r?: R }>
Joins two arrays of objects by a given ID criteria.
leftJoin
returns an array all the left
items, merged by ID with any right
items that meet the joining criteria.
Parameters
Name | Description |
---|---|
|
The left-side array of objects. |
|
The right-side array of objects. |
|
The criteria used to extract the ID for the left collection. |
|
The criteria used to extract the ID for the right collection. |
Example
This example shows how join behaves. Notice that it returns all objects from
the left-side array (left
) but only joins items from the right-side array
(right
) if the values of the left-side user.id
and right-side
product.ownerId
match.
Source
1
2
3
4
5
6
7
%dw 2.0
import * from dw::core::Arrays
var users = [{id: "1", name:"Mariano"},{id: "2", name:"Leandro"},{id: "3", name:"Julian"},{id: "5", name:"Julian"}]
var products = [{ownerId: "1", name:"DataWeave"},{ownerId: "1", name:"BAT"}, {ownerId: "3", name:"DataSense"}, {ownerId: "4", name:"SmartConnectors"}]
output application/json
---
leftJoin(users, products, (user) -> user.id, (product) -> product.ownerId)
Output
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
[
{
"l": {
"id": "1",
"name": "Mariano"
},
"r": {
"ownerId": "1",
"name": "DataWeave"
}
},
{
"l": {
"id": "1",
"name": "Mariano"
},
"r": {
"ownerId": "1",
"name": "BAT"
}
},
{
"l": {
"id": "2",
"name": "Leandro"
}
},
{
"l": {
"id": "3",
"name": "Julian"
},
"r": {
"ownerId": "3",
"name": "DataSense"
}
},
{
"l": {
"id": "5",
"name": "Julian"
}
}
]
outerJoin
outerJoin<L <: Object, R <: Object>(left: Array<L>, right: Array<R>, leftCriteria: (leftValue: L) -> String, rightCriteria: (rightValue: R) -> String): Array<{ l?: L, r?: R }>
Joins two array of objects by a given ID
criteria.
outerJoin
returns an array with all the left
items, merged by ID
with the right
items in cases where any exist, and it returns right
items that are not present in the left
.
Parameters
Name | Description |
---|---|
|
The left-side array of objects. |
|
The right-side array of objects. |
|
The criteria used to extract the ID for the left collection. |
|
The criteria used to extract the ID for the right collection. |
Example
This example shows how join behaves. Notice that the output includes
objects where the values of the input user.id
and product.ownerId
match,
and it includes objects where there is no match for the value of the
user.id
or product.ownerId
.
Source
1
2
3
4
5
6
7
%dw 2.0
import * from dw::core::Arrays
var users = [{id: "1", name:"Mariano"},{id: "2", name:"Leandro"},{id: "3", name:"Julian"},{id: "5", name:"Julian"}]
var products = [{ownerId: "1", name:"DataWeave"},{ownerId: "1", name:"BAT"}, {ownerId: "3", name:"DataSense"}, {ownerId: "4", name:"SmartConnectors"}]
output application/json
---
outerJoin(users, products, (user) -> user.id, (product) -> product.ownerId)
Output
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
[
{
"l": {
"id": "1",
"name": "Mariano"
},
"r": {
"ownerId": "1",
"name": "DataWeave"
}
},
{
"l": {
"id": "1",
"name": "Mariano"
},
"r": {
"ownerId": "1",
"name": "BAT"
}
},
{
"l": {
"id": "2",
"name": "Leandro"
}
},
{
"l": {
"id": "3",
"name": "Julian"
},
"r": {
"ownerId": "3",
"name": "DataSense"
}
},
{
"l": {
"id": "5",
"name": "Julian"
}
},
{
"r": {
"ownerId": "4",
"name": "SmartConnectors"
}
}
]
partition
partition<T>(array: Array<T>, condition: (item: T) -> Boolean): { success: Array<T>, failure: Array<T> }
Separates the array into the elements that satisfy the condition from those that do not.
Parameters
Name | Description |
---|---|
|
The array of elements to split. |
|
The condition (or expression) used to match an element in the array. |
Example
This example partitions numbers found within an input array. The
even numbers match the criteria set by the lambda expression
(item) → isEven(item)
. The odd do not. The function generates the
"success"
and "failure"
keys within the output object.
Source
1
2
3
4
5
6
%dw 2.0
import * from dw::core::Arrays
output application/json
var arr = [0,1,2,3,4,5]
---
arr partition (item) -> isEven(item)
Output
1
2
3
4
5
6
7
8
9
10
11
12
{
"success": [
0,
2,
4
],
"failure": [
1,
3,
5
]
}
partition(array: Null, condition: (item: Nothing) -> Any): Null
Helper function that enables partition
to work with a null
value.
slice
slice<T>(array: Array<T>, from: Number, until: Number): Array<T>
Selects the interval of elements that satisfy the condition:
from <= indexOf(array) < until
Parameters
Name | Description |
---|---|
|
The array of elements. |
|
The starting index of the interval of elements to include from the array. |
|
The ending index of the interval of elements to include from the array. |
Example
This example returns an array that contains the values of indices 1, 2, and 3 from the input array. It excludes the values of indices 0, 4, and 5.
Source
1
2
3
4
5
6
%dw 2.0
import * from dw::core::Arrays
output application/json
var arr = [0,1,2,3,4,5]
---
slice(arr, 1, 4)
Output
1
2
3
4
5
[
1,
2,
3
]
slice(array: Null, from: Any, until: Any): Null
Helper function that enables slice
to work with a null
value.
some
some<T>(list: Array<T>, condition: (T) -> Boolean): Boolean
Returns true
if at least one element in the array matches the specified condition.
The function stops iterating after the first element that matches the condition is found.
Parameters
Name | Description |
---|---|
|
The input array. |
|
A condition (or expression) used to match elements in the array. |
Example
This example applies a variety of expressions to elements of several input arrays.
The $
in the condition is the default parameter for the current element of the
array that the condition evaluates.
Note that you can replace the default $
parameter with a lambda expression that
contains a named parameter for the current array element.
Source
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
%dw 2.0
import * from dw::core::Arrays
output application/json
---
{ "results" : [
"ok" : [
[1,2,3] some (($ mod 2) == 0),
[1,2,3] some ((nextNum) -> (nextNum mod 2) == 0),
[1,2,3] some (($ mod 2) == 1),
[1,2,3,4,5,6,7,8] some (log('should stop at 2 ==', $) == 2),
[1,2,3] some ($ == 1),
[1,1,1] some ($ == 1),
[1] some ($ == 1)
],
"err" : [
[1,2,3] some ($ == 100),
[1] some ($ == 2)
]
]
}
Output
1
2
3
4
5
6
7
8
9
10
{
"results": [
{
"ok": [ true, true, true, true, true, true, true ]
},
{
"err": [ false, false ]
}
]
}
some(list: Null, condition: (Nothing) -> Any): Boolean
Helper function that enables some
to work with a null
value.
splitAt
splitAt<T>(array: Array<T>, n: Number): Pair<Array<T>, Array<T>>
Splits an array into two at a given position.
Parameters
Name | Description |
---|---|
|
The array of elements. |
|
The index at which to split the array. |
Example
Source
1
2
3
4
5
6
%dw 2.0
import * from dw::core::Arrays
output application/json
var users = ["Mariano", "Leandro", "Julian"]
---
users splitAt 1
Output
1
2
3
4
5
6
7
8
9
{
"l": [
"Mariano"
],
"r": [
"Leandro",
"Julian"
]
}
splitAt(array: Null, n: Any): Null
Helper function that enables splitAt
to work with a null
value.
splitWhere
splitWhere<T>(array: Array<T>, condition: (item: T) -> Boolean): Pair<Array<T>, Array<T>>
Splits an array into two at the first position where the condition is met.
Parameters
Name | Description |
---|---|
|
The array of elements to split. |
|
The condition (or expression) used to match an element in the array. |
Example
Source
1
2
3
4
5
6
%dw 2.0
import * from dw::core::Arrays
output application/json
var users = ["Mariano", "Leandro", "Julian", "Tomo"]
---
users splitWhere (item) -> item startsWith "Jul"
Output
1
2
3
4
5
6
7
8
9
10
{
"l": [
"Mariano",
"Leandro"
],
"r": [
"Julian",
"Tomo"
]
}
splitWhere(array: Null, condition: (item: Nothing) -> Any): Null
Helper function that enables splitWhere
to work with a null
value.
sumBy
sumBy<T>(array: Array<T>, numberSelector: (T) -> Number): Number
Returns the sum of the values of the elements in an array.
Parameters
Name | Description |
---|---|
|
The input array. |
|
A DataWeave selector that selects the values of the numbers in the input array. |
Example
This example calculates the sum of the values of elements some arrays. Notice
that both of the sumBy
function calls produce the same result.
Source
1
2
3
4
5
6
7
8
9
10
%dw 2.0
import * from dw::core::Arrays
output application/json
---
{
"sumBy" : [
[ { a: 1 }, { a: 2 }, { a: 3 } ] sumBy $.a,
sumBy([ { a: 1 }, { a: 2 }, { a: 3 } ], (item) -> item.a)
]
}
Output
1
{ "sumBy" : [ 6, 6 ] }
sumBy(array: Null, numberSelector: (Nothing) -> Any): Null
Helper function that enables sumBy
to work with a null
value.
take
take<T>(array: Array<T>, n: Number): Array<T>
Selects the first n
elements. It returns an empty array when n <= 0
and the original array when n > sizeOf(array)
.
Parameters
Name | Description |
---|---|
|
The array of elements. |
|
The number of elements to select. |
Example
This example outputs an array that contains the values of first two elements of the input array.
Source
1
2
3
4
5
6
%dw 2.0
import * from dw::core::Arrays
var users = ["Mariano", "Leandro", "Julian"]
output application/json
---
take(users, 2)
Output
1
2
3
4
[
"Mariano",
"Leandro"
]
take(array: Null, n: Any): Null
Helper function that enables take
to work with a null
value.
takeWhile
takeWhile<T>(array: Array<T>, condition: (item: T) -> Boolean): Array<T>
Selects elements from the array while the condition is met but stops the selection process when it reaches an element that fails to satisfy the condition.
To select all elements that meet the condition, use the filter
function.
Parameters
Name | Description |
---|---|
|
The array of elements. |
|
The condition (or expression) used to match an element in the array. |
Example
This example iterates over the elements in the array and selects only those
with an index that is <= 1
and stops selecting elements when it reaches
one that is greater than 2
. Notice that it does not select the second 1
because
of the 2
that precedes it in the array. The function outputs the result into an array.
Source
1
2
3
4
5
6
%dw 2.0
import * from dw::core::Arrays
output application/json
var arr = [0,1,2,1]
---
arr takeWhile $ <= 1
Output
1
2
3
4
[
0,
1
]
takeWhile(array: Null, condition: (item: Nothing) -> Any): Null
Helper function that enables takeWhile
to work with a null
value.