up: ARRAY     index Zimbu documentation

CLASS T.array<Titem> @public

summary

     

The builtin type array. An array contains zero or more items of the type specified in the declaration:

 array<Type> myarray      # array with 1 dimension
 array<Type, 3> myarray   # array with 3 dimensions
NOTE: Currently only one-dimensional arrays are implemented.

An array is similar to a list, but is created with a fixed size and all elements initialized at the default value. It is not possible to insert or delete items.

Arrays can be resized, but this is inefficient.

Besides the object methods, Zimbu has these syntax items for arrays:

 array<int> intArray = [1, 2, 3]  # initialize from a list
 IO.print(intArray[1])            # get array item by index
 intArray[0] = 99                 # set array item by index

When getting an item by index with intArray[index] and index is out of range, it returns the default item value (NIL, zero, FALSE)

When setting an item by index with intArray[index] = value and index is out of range this throws an exception.

NEW(count) @public  Create a new one-dimensional array with count items.
$Size() int @public  Return the number of items a one-dimensional array can hold.
$ToString() string @public  Return a string representation of the array.
$ToString(format) string @public  Return a string representation of the array with specified formatting.
$Type() type @public  Return the type of the array.
$resize(count) array<Titem> @public  Resize a one-dimensional array to contain count items.
$set(index, values) array<Titem> @file  Set the items starting at position index to the byteString values.
$set(index, values) array<Titem> @file  Set the items starting at position index to the array values.
$set(index, values) array<Titem> @file  Set the items starting at position index to the list values.
$has(item) bool @public  Return TRUE if there is an item that equals item.
$find(item) int @public  Return the index of the first item that equals item.
$map(f) array<Titem> @public  Execute function f on each item. Each item is replaced by the result of the function.
$keyMap(f) array<Titem> @public  Execute function f on each item. Each item is replaced by the result of the function.
$mapTo(f) array<Tresult> @public  Create a new array where each item is the result of executing function f on each item of this array.
$keyMapTo(f) array<Tresult> @public  Create a new array where each item is the result of executing function f on each item of this array.
$forEach(f) array<Titem> @public  Call method f for every item in the array.
$forKeyEach(f) array<Titem> @public  Call method f for every item in the array.
 
 

members (alphabetically)

     

PROC NEW(int count) @public

     

Create a new one-dimensional array with count items.

All items are set to their default value (NIL, FALSE, 0).

FUNC $Size() int @public

     

Return the number of items a one-dimensional array can hold.

It does not matter if some array entries were never set, they will have the default value (NIL, FALSE, 0).

When used on NIL Size() returns zero, it does not throw an E.NilAccess exception.

FUNC $ToString() string @public

     

Return a string representation of the array.

Starts with "[" and ends in "]". Items are separated with ", ".

An empty array returns "[]".

 string s = ["a", "b"].ToString()
 # s == "["a", "b"]".

A NIL array returns "NIL"

Each item is converted to a string by calling its ToString() method, if there is one.

If the list contains itself somehow, instead of recursing "[recursive-array]" will be used. However, if multiple threads are doing this for the same array the effect is unpredictable.

FUNC $ToString(string format) string @public

     

Return a string representation of the array with specified formatting.

Currently works like ToString() without a format argument.

TODO: limit depth, limit number of items (like string truncation, optional ellipses), etc.

FUNC $Type() type @public

     

Return the type of the array.

Invoking ToString() on the returned type results in something like "array<string>".

FUNC $find(Titem item) int @public

     

Return the index of the first item that equals item.

When Titem is a value type, a string or a byteString then the value is compared. Otherwise IS is used, the item at the index IS item.

Returns -1 if item is not found or when the array is NIL.

FUNC $forEach(proc<Titem> f) array<Titem> @public

     

Call method f for every item in the array.

The argument for f is the value of the item.

Returns the array.

FUNC $forKeyEach(proc<int, Titem> f) array<Titem> @public

     

Call method f for every item in the array.

The first argument for f is the index in the array, the second argument is the value of the item.

Returns the array.

FUNC $has(Titem item) bool @public

     

Return TRUE if there is an item that equals item.

This is equivalent to:

 $find(item) != -1
Returns FALSE when the array is NIL.

FUNC $keyMap(func<Titem => Titem> f) array<Titem> @public

     

Execute function f on each item. Each item is replaced by the result of the function.

f has two arguments: The index in the array and the current value of the item. f must return the new value of the item.

Keep in mind that items have their default value when never set, which an be NIL.

When the array is NIL nothing happens.

 array<string> a = ["a", "b", "c"]
 a.keyMap({ i, s => i .. ":" .. s })
 # a == ["0:a", "1:b", "2:c"]

Returns the array.

FUNC $keyMapTo(func<int, Titem => Tresult> f) array<Tresult> @public

     

Create a new array where each item is the result of executing function f on each item of this array.

This is like keyMap() but with a different result type.

f has two arguments: The index in the array and the value of the item. f must return the value for the new array.

 array<int> il = [11, 22, 33]
 array<string> sl = il.keyMapTo({ i, n => i .. ": " .. n })
 # sl == ["0: 11", "1: 22", "2: 33"]

Returns the new array. Returns NIL when the array is NIL.

FUNC $map(func<Titem => Titem> f) array<Titem> @public

     

Execute function f on each item. Each item is replaced by the result of the function.

f has one argument, which is the current value of the item, and must return the new value of the item.

Keep in mind that items have their default value when never set, which can be NIL.

When the array is NIL nothing happens.

 array<string> a = ["a", "b", "c"]
 a.map({ s => s .. ":" })
 # a == ["a:", "b:", "c:"]

Returns the array.

FUNC $mapTo(func<Titem => Tresult> f) array<Tresult> @public

     

Create a new array where each item is the result of executing function f on each item of this array.

This is like map() but with a different result type.

f has one argument, which is the value of the item, and must return the value for the new array.

 array<int> ia = [1, 2, 3]
 array<string> sl = ia.mapTo({ n => n .. ":" })
 # sl == ["1:", "2:", "3:"]

Returns the new array. Returns NIL when the array is NIL.

FUNC $resize(int count) array<Titem> @public

     

Resize a one-dimensional array to contain count items.

If the array was larger before, the items at count and further are discarded.

If the array was smaller before, the new item locations are set to the default value (NIL, FALSE, 0).

Returns the array.

FUNC $set(int index, byteString values) array<Titem> @file

     

Set the items starting at position index to the byteString values.

Titem must be a number type: int or byte.

If values contains more items that the array has space then the extra items are not used.

Returns the array.

FUNC $set(int index, array<Titem> values) array<Titem> @file

     

Set the items starting at position index to the array values.

If values contains more items that the array has space then the extra items are not used.

Returns the array.

FUNC $set(int index, list<Titem> values) array<Titem> @file

     

Set the items starting at position index to the list values.

If values contains more items that the array has space then the extra items are not used.

Returns the array.

license

      Copyright 2012 Bram Moolenaar All Rights Reserved.

      Licensed under the Apache License, Version 2.0. See the LICENSE file or obtain a copy at: http://www.apache.org/licenses/LICENSE-2.0