ballerina/lang.array Ballerina library

function 'map(any|error[] arr,  function(any|error) returns (any|error) func) returns any|error[]

Applies a function to each member of an array and returns an array of the results.

int[] numbers = [0, 1, 2];
numbers.map(n => n * 2) ⇒ [0,2,4]

function enumerate(any|error[] arr) returns [int, any|error][]

Returns a new array consisting of index and member pairs.

[1, 2, 3, 4].enumerate() ⇒ [[0,1],[1,2],[2,3],[3,4]]

function every(any|error[] arr,  function(any|error) returns (boolean) func) returns boolean

Tests whether a function returns true for every member of an array.

The parameter func is called for each member of arr in order unless and until a call returns false. When the array is empty, returns true.

int[] numbers = [1, 2, 3, 5];
numbers.every(n => n % 2 == 0) ⇒ false

function filter(any|error[] arr,  function(any|error) returns (boolean) func) returns any|error[]

Selects the members from an array for which a function returns true.

int[] numbers = [12, 43, 60, 75, 10];
numbers.filter(n => n > 50) ⇒ [60,75]

function forEach(any|error[] arr,  function(any|error) returns (() ) func) returns () 

Applies a function to each member of an array.

The parameter func is applied to each member of parameter arr in order.

int total = 0;
[1, 2, 3].forEach(function (int i) {
    total += i;
});
total ⇒ 6

function fromBase16(string str) returns byte[]|error

Returns the byte array that a string represents in Base16.

str must consist of the characters 0..9, A..F, a..f and whitespace as allowed by a Ballerina Base16Literal.

array:fromBase16("aaabcfccadafcd") ⇒ [170,171,207,204,173,175,205]
array:fromBase16("aaabcfccadafcd==") ⇒ error

function fromBase64(string str) returns byte[]|error

Returns the byte array that a string represents in Base64.

parameter str must consist of the characters A..Z, a..z, 0..9, +, /, = and whitespace as allowed by a Ballerina Base64Literal.

array:fromBase64("aGVsbG8gYmE=") ⇒ [104,101,108,108,111,32,98,97]
array:fromBase64("aGVsbG8gYmE--") ⇒ error

function indexOf(AnydataType[] arr, AnydataType val, int startIndex) returns int?

Returns the index of first member of an array that is equal to a given value if there is one. Returns () if not found. Equality is tested using ==.

string[] strings = ["a", "b", "d", "b", "d"];
strings.indexOf("e") is () ⇒ true
strings.indexOf("b") ⇒ 1
strings.indexOf("b", 2) ⇒ 3

function iterator(any|error[] arr) returns object {
    public isolated function next() returns record {|
        Type value;
    |}?;
} 

Returns an iterator over an array.

object {
    public isolated function next() returns record {|int value;|}?;
} iterator = [2, 4, 6, 8].iterator();
iterator.next() ⇒ {"value":2}

function lastIndexOf(AnydataType[] arr, AnydataType val, int startIndex) returns int?

Returns the index of last member of an array that is equal to a given value if there is one. Returns () if not found. Equality is tested using ==.

string[] strings = ["a", "b", "d", "b", "d", "b"];
strings.lastIndexOf("e") is () ⇒ true
strings.lastIndexOf("b") ⇒ 5
strings.lastIndexOf("b", strings.length() - 2) ⇒ 3

function length((any|error)[] arr) returns int

Returns the number of members of an array.

["a", "b", "c", "d"].length() ⇒ 4

function pop(any|error[] arr) returns any|error

Removes and returns the last member of an array.

The array must not be empty.

int[] numbers = [2, 4, 6, 8, 10];
numbers.pop() ⇒ 10
int[] values = [];
values.pop() ⇒ panic

function push(any|error[] arr, any|error... vals) returns () 

Adds values to the end of an array.

int[] numbers = [2];
numbers.push(4, 6);
numbers ⇒ [2,4,6]
int[] moreNumbers = [8, 10, 12, 14];
numbers.push(...moreNumbers);
numbers ⇒ [2,4,6,8,10,12,14]

function reduce(any|error[] arr,  function(any|error, any|error) returns (any|error) func, any|error initial) returns any|error

Combines the members of an array using a combining function.

The combining function takes the combined value so far and a member of the array, and returns a new combined value.

[1, 2, 3].reduce(isolated function (int total, int next) returns int => total + next, 0) ⇒ 6

function remove(any|error[] arr, int index) returns any|error

Removes a member of an array.

This removes the member of parameter arr with index parameter index and returns it. It panics if there is no such member.

int[] numbers = [2, 4, 6, 8];
numbers.remove(1) ⇒ 4
numbers.remove(7) ⇒ panic

function removeAll((any|error)[] arr) returns () 

Removes all members of an array.

Panics if any member cannot be removed.

int[] numbers = [2, 4, 6, 8];
numbers.removeAll();
numbers ⇒ []
int[2] values = [1, 2];
values.removeAll() ⇒ panic

function reverse(any|error[] arr) returns any|error[]

Reverses the order of the members of an array.

[2, 4, 12, 8, 10].reverse() ⇒ [10,8,12,4,2]

function setLength((any|error)[] arr, int length) returns () 

Changes the length of an array.

setLength(arr, 0) is equivalent to removeAll(arr).

int[] numbers = [2, 4, 6, 8];
numbers.setLength(2);
numbers ⇒ [2,4]
numbers.setLength(0);
numbers ⇒ []

function shift(any|error[] arr) returns any|error

Removes and returns first member of an array.

The array must not be empty.

int[] numbers = [2, 4, 6, 8, 10];
numbers.shift() ⇒ 2
int[] values = [];
values.shift() ⇒ panic

function slice(any|error[] arr, int startIndex, int endIndex) returns any|error[]

Returns a subarray using a start index (inclusive) and an end index (exclusive).

int[] numbers = [2, 4, 6, 8, 10, 12];
numbers.slice(3) ⇒ [8,10,12]
numbers.slice(0, 4) ⇒ [2,4,6,8]
numbers.slice(0, 10) ⇒ panic

function some(any|error[] arr,  function(any|error) returns (boolean) func) returns boolean

Tests whether a function returns true for some member of an array.

The parameter func is called for each member of parameter arr in order unless and until a call returns true. When the array is empty, returns false.

int[] numbers = [1, 2, 3, 5];
numbers.some(n => n % 2 == 0) ⇒ true

function sort(any|error[] arr, SortDirection direction, ( function(any|error) returns (OrderedType))? key) returns any|error[]

Sorts an array.

If the member type of the array is not ordered, then the parameter key function must be specified. Sorting works the same as with the parameter sort clause of query expressions.

string[] strings = ["c", "a", "B"];
strings.sort() ⇒ ["B","a","c"]
strings.sort("descending") ⇒ ["c","a","B"]
strings.sort(key = string:toLowerAscii) ⇒ ["a","B","c"]
strings.sort("descending", string:toLowerAscii) ⇒ ["c","B","a"]

function toBase16(byte[] arr) returns string

Returns the string that is the Base16 representation of an array of bytes.

The representation is the same as used by a Ballerina Base16Literal. The result will contain only characters 0..9, a..f. There will be no whitespace in the returned string.

byte[] byteArray = [170, 171, 207, 204, 173, 175, 205];
byteArray.toBase16() ⇒ aaabcfccadafcd

function toBase64(byte[] arr) returns string

Returns the string that is the Base64 representation of an array of bytes.

The representation is the same as used by a Ballerina Base64Literal. The result will contain only characters A..Z, a..z, 0..9, +, / and =. There will be no whitespace in the returned string.

byte[] byteArray = [104, 101, 108, 108, 111, 32, 98, 97];
byteArray.toBase64() ⇒ aGVsbG8gYmE=

function toStream(any|error[] arr) returns stream<any|error>

Returns a stream from the given array.

stream<string> strm = ["a", "b", "c", "d"].toStream();
strm.next() ⇒ {"value":"a"}

function unshift(any|error[] arr, any|error... vals) returns () 

Adds values to the start of an array.

The values newly added to the array will be in the same order as they are in parameter vals.

int[] numbers = [14];
numbers.unshift(10, 12);
numbers ⇒ [10,12,14]
int[] moreNumbers = [2, 4, 6, 8];
numbers.unshift(...moreNumbers);
numbers ⇒ [2,4,6,8,10,12,14]