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(Array<T>, (T) → Boolean): Number

Counts the elements in an array that match the results of a function.

Parameters
Name Description

array

The input array that contains elements to match.

matchingFunction

A function to apply to elements in the input array.

Example

This counts the values in the array that are equal to the result of the matchingFunction ((($ mod 2) == 0)).

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 }

divideBy

divideBy(Array<T>, 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

Items in the input array.

amount

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 ]
      ]
    }
 ]
}

drop

drop(Array<T>, Number): Array<T>

Drops the first n elements. It returns the original array when n <= 0 and an empty array when n > sizeOf(array).

Introduced in DataWeave 2.2.0. Supported by Mule 4.2 and later.

Parameters
Name Description

array

The left array of elements.

n

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"
]

dropWhile

dropWhile(Array<T>, (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.

Introduced in DataWeave 2.2.0. Supported by Mule 4.2 and later.

Parameters
Name Description

array

The array of elements.

condition

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
]

every

every(Array<T>, (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

list

The input array.

condition

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(Null, (Nothing) → Boolean): Boolean

Helper function that enables every to work with a null value.

Introduced in DataWeave 2.3.0. Supported by Mule 4.3 and later.

firstWith

firstWith(Array<T>, (item: T, index: Number) → Boolean): T | Null

Returns the first element that satisfies the condition, or returns null if no element meets the condition.

Introduced in DataWeave 2.3.0. Supported by Mule 4.3 and later.

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
}

indexOf

indexOf(Array<T>, T): Number

Returns the index of the first occurrence of an element within the array.

Introduced in DataWeave 2.2.0. Supported by Mule 4.2 and later.

Parameters
Name Description

array

The array of elements.

toFind

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(Array<T>, (item: T) → Boolean): Number

Returns the index of the first occurrence of an element that matches a condition within the array.

Introduced in DataWeave 2.2.0. Supported by Mule 4.2 and later.

Parameters
Name Description

array

The array of elements.

condition

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

join

join(Array<L>, Array<R>, (leftValue: L) → String, (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.

Introduced in DataWeave 2.2.0. Supported by Mule 4.2 and later.

Parameters
Name Description

left

The left-side array of objects.

right

The right-side array of objects.

leftCriteria

The criteria used to extract the ID for the left collection.

rightCriteria

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(Array<L>, Array<R>, (leftValue: L) → String, (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.

Introduced in DataWeave 2.2.0. Supported by Mule 4.2 and later.

Parameters
Name Description

left

The left-side array of objects.

right

The right-side array of objects.

leftCriteria

The criteria used to extract the ID for the left collection.

rightCriteria

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(Array<L>, Array<R>, (leftValue: L) → String, (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.

Introduced in DataWeave 2.2.0. Supported by Mule 4.2 and later.

Parameters
Name Description

left

The left-side array of objects.

right

The right-side array of objects.

leftCriteria

The criteria used to extract the ID for the left collection.

rightCriteria

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(Array<T>, (item: T) → Boolean): { success: Array<T>, failure: Array<T> }

Separates the array into the elements that satisfy the condition from those that do not.

Introduced in DataWeave 2.2.0. Supported by Mule 4.2 and later.

Parameters
Name Description

array

The array of elements to split.

condition

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
  ]
}

slice

slice(Array<T>, Number, Number): Array<T>

Selects the interval of elements that satisfy the condition: from <= indexOf(array) < until

Introduced in DataWeave 2.2.0. Supported by Mule 4.2 and later.

Parameters
Name Description

array

The array of elements.

from

The lowest index to include from the array.

until

The lowest index to exclude 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
]

some

some(Array<T>, (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

list

The input array.

condition

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(Null, (Nothing) → Boolean): Boolean

Helper function that enables some to work with a null value.

Introduced in DataWeave 2.3.0. Supported by Mule 4.3 and later.

splitAt

splitAt(Array<T>, Number): Pair<Array<T>, Array<T>>

Splits an array into two at a given position.

Introduced in DataWeave 2.2.0. Supported by Mule 4.2 and later.

Parameters
Name Description

array

The array of elements.

n

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"
  ]
}

splitWhere

splitWhere(Array<T>, (item: T) → Boolean): Pair<Array<T>, Array<T>>

Splits an array into two at the first position where the condition is met.

Introduced in DataWeave 2.2.0. Supported by Mule 4.2 and later.

Parameters
Name Description

array

The array of elements to split.

condition

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"
  ]
}

sumBy

sumBy(Array<T>, (T) → Number): Number

Returns the sum of the values of the elements in an array.

Parameters
Name Description

array

The input array.

numberSelector

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 ] }

take

take(Array<T>, Number): Array<T>

Selects the first n elements. It returns an empty array when n <= 0 and the original array when n > sizeOf(array).

Introduced in DataWeave 2.2.0. Supported by Mule 4.2 and later.

Parameters
Name Description

array

The array of elements.

n

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"
]

takeWhile

takeWhile(Array<T>, (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.

Introduced in DataWeave 2.2.0. Supported by Mule 4.2 and later.

Parameters
Name Description

array

The array of elements.

condition

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
]