This API documentation is for Ballerina 1.2.0. View API documentation for the latest release.

Functions - lang.array

enumerate

Returns a new array consisting of index and member pairs.

filter

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

forEach

Applies a function to each member of an array.

fromBase16

Returns the byte array that a string represents in Base16.

fromBase64

Returns the byte array that a string represents in Base64.

indexOf

Returns the index of first member of arr that is equal to val if there is one.

iterator

Returns an iterator over an array.

lastIndexOf

Returns the index of last member of arr that is equal to val if there is one.

length

Returns the number of members of an array.

map

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

pop

Removes and returns the last member of an array.

push

Adds values to the end of an array.

reduce

Combines the members of an array using a combining function.

remove

Removes a member of an array.

removeAll

Removes all members of an array.

reverse

Reverses the order of the members of an array.

setLength

Changes the length of an array.

shift

Removes and returns first member of an array.

slice

Returns a subarray starting from startIndex (inclusive) to endIndex (exclusive).

sort

Sorts an array using a comparator function.

toBase16

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

toBase64

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

toStream

Returns a stream from the given array.

unshift

Adds values to the start of an array.

enumerate

(Type[] arr)

returns [int, Type][]

Returns a new array consisting of index and member pairs.

Parameters

  • arr Type[]
  • the array

  • Return Type

    ([int, Type][])
  • array of index, member pairs

filter

(Type[] arr, function(Type) returns (boolean) func)

returns Type[]

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

Parameters

  • arr Type[]
  • the array

  • func function(Type) returns (boolean)
  • a predicate to apply to each member to test whether it should be selected

  • Return Type

    (Type[])
  • new array only containing members of arr for which func evaluates to true

forEach

(Type[] arr, function(Type) returns (()) func)

Applies a function to each member of an array. The parameter func is applied to each member of array arr in order.

Parameters

  • arr Type[]
  • the array

  • func function(Type) returns (())
  • a function to apply to each member

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.

Parameters

  • str string
  • Base16 string representation

  • Return Type

    (byte[] | error)
  • the byte array or error

fromBase64

(string str)

returns byte[] | error

Returns the byte array that a string represents in Base64. str must consist of the characters A..Z, a..z, 0..9, +, /, = and whitespace as allowed by a Ballerina Base64Literal.

Parameters

  • str string
  • Base64 string representation

  • Return Type

    (byte[] | error)
  • the byte array or error

indexOf

(PureType[] arr, PureType val, int startIndex)

returns int?

Returns the index of first member of arr that is equal to val if there is one. Returns () if not found. Equality is tested using ==.

Parameters

  • arr PureType[]
  • the array

  • val PureType
  • 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

(Type[] arr)

returns object { public function next () returns (record {| (any|error) value; |}?); }

Returns an iterator over an array.

Parameters

  • arr Type[]
  • the array

  • Return Type

    (object { public function next () returns (record {| (any|error) value; |}?); })
  • a new iterator object that will iterate over the members of arr.

lastIndexOf

(PureType[] arr, PureType val, int startIndex)

returns int?

Returns the index of last member of arr that is equal to val if there is one. Returns () if not found. Equality is tested using ==.

Parameters

  • arr PureType[]
  • the array

  • val PureType
  • member to search for

  • startIndex int (default arr.length(arr) - 1)
  • index to start searching backwards from

  • Return Type

    (int?)
  • index of the member if found, else ()

length

(any | error[] arr)

returns int

Returns the number of members of an array.

Parameters

  • arr any | error[]
  • the array

  • Return Type

    (int)
  • number of members in arr

map

(Type[] arr, function(Type) returns (Type1) func)

returns Type1[]

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

Parameters

  • arr Type[]
  • the array

  • func function(Type) returns (Type1)
  • a function to apply to each member

  • Return Type

    (Type1[])
  • new array containing result of applying func to each member of arr in order

pop

(Type[] arr)

returns Type

Removes and returns the last member of an array. The array must not be empty.

Parameters

  • arr Type[]
  • the array

  • Return Type

    (Type)
  • removed member

push

(Type[] arr, Type... vals)

Adds values to the end of an array.

Parameters

  • arr Type[]
  • the array

  • vals Type...
  • values to add to the end of the array

reduce

(Type[] arr, function(Type1, Type) returns (Type1) func, Type1 initial)

returns Type1

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.

Parameters

  • arr Type[]
  • the array

  • func function(Type1, Type) returns (Type1)
  • combining function

  • initial Type1
  • initial value for the first argument of combining parameter func

  • Return Type

    (Type1)
  • result of combining the members of arr using func

    For example

     reduce([1, 2, 3], function (int total, int n) returns int { return total + n; }, 0)
    

    is the same as sum(1, 2, 3).

remove

(Type[] arr, int index)

returns Type

Removes a member of an array.

Parameters

  • arr Type[]
  • the array

  • index int
  • index of member to be removed from arr

  • Return Type

    (Type)
  • the member of arr that was at index This removes the member of arr with index index and returns it. It panics if there is no such member.

removeAll

(any | error[] arr)

Removes all members of an array.

Parameters

  • arr any | error[]
  • the array Panics if any member cannot be removed.

reverse

(Type[] arr)

returns Type[]

Reverses the order of the members of an array.

Parameters

  • arr Type[]
  • the array to be reversed

  • Return Type

    (Type[])
  • arr with its members in reverse order

setLength

(any | error[] arr, int length)

Changes the length of an array.

Parameters

  • arr any | error[]
  • the array of which to change the length

  • length int
  • new length setLength(arr, 0) is equivalent to removeAll(arr).

shift

(Type[] arr)

returns Type

Removes and returns first member of an array. The array must not be empty.

Parameters

  • arr Type[]
  • the array

  • Return Type

    (Type)
  • the value that was the first member of the array

slice

(Type[] arr, int startIndex, int endIndex)

returns Type[]

Returns a subarray starting from startIndex (inclusive) to endIndex (exclusive).

Parameters

  • arr Type[]
  • the array

  • startIndex int
  • index of first member to include in the slice

  • endIndex int (default arr.length(arr))
  • index of first member not to include in the slice

  • Return Type

    (Type[])
  • array slice within specified range

sort

(Type[] arr, function(Type, Type) returns (int) func)

returns Type[]

Sorts an array using a comparator function. The comparator function must return a value less than, equal to or greater than zero according as its first argument is to be ordered before, equal to or after its second argument.

Parameters

  • arr Type[]
  • the array to be sorted

  • func function(Type, Type) returns (int)
  • comparator function

  • Return Type

    (Type[])
  • arr with its members sorted

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.

Parameters

  • arr byte[]
  • the array

  • Return Type

    (string)
  • Base16 string representation

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.

Parameters

  • arr byte[]
  • the array

  • Return Type

    (string)
  • Base64 string representation

toStream

(Type[] arr)

returns stream<Type>

Returns a stream from the given array.

Parameters

  • arr Type[]
  • The array from which the stream is created

  • Return Type

    (stream<Type>)
  • The stream representation of the array arr

unshift

(Type[] arr, Type... vals)

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 vals.

Parameters

  • arr Type[]
  • the array

  • vals Type...
  • values to add to the start of the array