lang.array
ballerina/lang.array Ballerina library
Module overview
The lang.array
module corresponds to the list
basic type.
Functions![](/images/permalink.svg)
'map![](/images/permalink.svg)
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]
Parameters
- arr any|error[] - the array
Return Type
- any|error[] - new array containing result of applying parameter
func
to each member of parameterarr
in order
enumerate![](/images/permalink.svg)
Returns a new array consisting of index and member pairs.
[1, 2, 3, 4].enumerate() ⇒ [[0,1],[1,2],[2,3],[3,4]]
Parameters
- arr any|error[] - the array
every![](/images/permalink.svg)
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
Parameters
- arr any|error[] - the array
Return Type
- boolean - true if applying parameter func returns true for every member of
arr
; otherwise, false
filter![](/images/permalink.svg)
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]
Parameters
- arr any|error[] - the array
Return Type
- any|error[] - new array only containing members of parameter
arr
for which parameterfunc
evaluates to true
forEach![](/images/permalink.svg)
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
fromBase16![](/images/permalink.svg)
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
Parameters
- str string - Base16 string representation
Return Type
- byte[]|error - the byte array or error
fromBase64![](/images/permalink.svg)
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
Parameters
- str string - Base64 string representation
Return Type
- byte[]|error - the byte array or error
indexOf![](/images/permalink.svg)
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
Parameters
- arr AnydataType[] - the array
- val AnydataType - member to search for
- startIndex int (default 0) - index to start the search from
Return Type
- int? - index of the member if found, else
()
iterator![](/images/permalink.svg)
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}
Parameters
- arr any|error[] - the array
Return Type
- object {
public isolated function next() returns record {|
Type value;
|}?;
} - a new iterator object that will iterate over the members of parameter
arr
lastIndexOf![](/images/permalink.svg)
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
Parameters
- arr AnydataType[] - the array
- val AnydataType - member to search for
- startIndex int (default arr.length() - 1) - index to start searching backwards from
Return Type
- int? - index of the member if found, else
()
length![](/images/permalink.svg)
Returns the number of members of an array.
["a", "b", "c", "d"].length() ⇒ 4
Parameters
- arr (any|error)[] - the array
Return Type
- int - number of members in parameter
arr
pop![](/images/permalink.svg)
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
Parameters
- arr any|error[] - the array
Return Type
- any|error - removed member
push![](/images/permalink.svg)
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]
reduce![](/images/permalink.svg)
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
Parameters
- arr any|error[] - the array
- initial any|error - initial value for the first argument of combining parameter
func
Return Type
- any|error - result of combining the members of parameter
arr
using parameterfunc
remove![](/images/permalink.svg)
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
Return Type
- any|error - the member of parameter
arr
that was at parameterindex
removeAll![](/images/permalink.svg)
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
Parameters
- arr (any|error)[] - the array
reverse![](/images/permalink.svg)
Reverses the order of the members of an array.
[2, 4, 12, 8, 10].reverse() ⇒ [10,8,12,4,2]
Parameters
- arr any|error[] - the array to be reversed
Return Type
- any|error[] - parameter
arr
with its members in reverse order
setLength![](/images/permalink.svg)
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 ⇒ []
shift![](/images/permalink.svg)
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
Parameters
- arr any|error[] - the array
Return Type
- any|error - the value that was the first member of the array
slice![](/images/permalink.svg)
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
Parameters
- arr any|error[] - the array
- startIndex int - index of first member to include in the slice
- endIndex int (default arr.length()) - index of first member not to include in the slice
Return Type
- any|error[] - array slice within specified range
some![](/images/permalink.svg)
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
Parameters
- arr any|error[] - the array
Return Type
- boolean - true if applying parameter
func
returns true for some member ofarr
; otherwise, false
sort![](/images/permalink.svg)
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"]
Parameters
- arr any|error[] - the array to be sorted;
- direction SortDirection (default ASCENDING) - direction in which to sort
- key (
function(any|error) returns (OrderedType)
)? (default ()) - function that returns a key to use to sort the members
Return Type
- any|error[] - a new array consisting of the members of parameter
arr
in sorted order
toBase16![](/images/permalink.svg)
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
Parameters
- arr byte[] - the array
Return Type
- string - Base16 string representation
toBase64![](/images/permalink.svg)
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=
Parameters
- arr byte[] - the array
Return Type
- string - Base64 string representation
toStream![](/images/permalink.svg)
Returns a stream from the given array.
stream<string> strm = ["a", "b", "c", "d"].toStream(); strm.next() ⇒ {"value":"a"}
Parameters
- arr any|error[] - The array from which the stream is created
unshift![](/images/permalink.svg)
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]
Enums![](/images/permalink.svg)
lang.array: SortDirection![](/images/permalink.svg)
Direction for sort
function.
Members
Union types![](/images/permalink.svg)
lang.array: Type![](/images/permalink.svg)
Type
A type parameter that is a subtype of any|error
.
Has the special semantic that when used in a declaration
all uses in the declaration must refer to same type.
lang.array: Type1![](/images/permalink.svg)
Type1
A type parameter that is a subtype of any|error
.
Has the special semantic that when used in a declaration
all uses in the declaration must refer to same type.
Anydata types![](/images/permalink.svg)
lang.array: AnydataType![](/images/permalink.svg)
AnydataType
A type parameter that is a subtype of anydata|error
.
Has the special semantic that when used in a declaration
all uses in the declaration must refer to same type.