up: LIST     index Zimbu documentation

CLASS T.list<Titem> @public

summary

     

The builtin type list.

A list contains zero or more items of the type specified in the declaration. The items are accessed by index. The first item has index zero.

A list can be used both as a stack and as a queue.

To use a list as a stack use the add() and remove() methods.

To use a list as a queue use the add() and remove(0) methods.

Adding and removing items at the end is the most efficient. Adding and removing at the start takes some more time. Adding and removing in the middle is not very efficient.

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

 list<int> intList = [1, 2, 3]  # list initializer
 IO.print(intList[1])           # get list item by index
 intList[0] = 99                # set list item by index

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

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

NEW() @public  Create a new empty list.
NEW(len, value) @public  Create a list with len items set to value.
$size() int @public  Return the number of items in the list.
$ToString() string @public  Return a string representation of the list.
$ToString(format) string @public  Return a string representation of the list with specified formatting.
$Type() type @public  Return the type of the list.
$copy() list<Titem> @public  Return a shallow copy of the list.
$get(index) Titem @public  Get the item at index.
$getLast(index) Titem @public  Get the last item.
$set(index, value) list<Titem> @public  Set the item at index.
$Iterator() I.Iterator<Titem> @public  Return a BOX.ListIterator.
$KeyIterator() I.KeyIterator<int, Titem> @public  Return a BOX.ListKeyIterator.
$slice(start) list<Titem> @public  Create a new list with all items starting at start.
$slice(start, end) list<Titem> @public  Create a new list with all items starting at start to end (inclusive).
$sliceSize(start, length) list<Titem> @public  Create a new list with all items starting at start with up to length items.
$sliceWrap(start) list<Titem> @public  Create a new list with all items starting at start.
$sliceWrap(start, end) list<Titem> @public  Create a new list with all items starting at start to end (inclusive).
$sliceWrapSize(start, length) list<Titem> @public  Create a new list with all items starting at start with up to length items.
$add(item) list<Titem> @public  Adds an item to the end of the list.
$add(item, index) list<Titem> @public  Adds an item after item index in the list.
$insert(item) list<Titem> @public  Inserts an item before the start of the list.
$insert(item, index) list<Titem> @public  Inserts an item before item index in the list.
$clear() list<Titem> @public  Removes all items from the list.
$clear(index) list<Titem> @public  Removes item index from the list and returns the list.
$clearItem(item) list<Titem> @public  Removes item from the list and returns the list.
$remove() Titem @public  Removes the last item from the list and returns it.
$remove(index) Titem @public  Removes the item at index from the list and returns it.
$removeItem(item) Titem @public  Remove item from the list and return it.
$remove(from, to) list<Titem> @public  Removes items from to to (inclusive) from the list and returns them in a new list.
$extend(other) list<Titem> @public  Appends all items of other to this list.
$concat(other) list<Titem> @public  Create a new list with all items of this list and other.
$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.
$join() string @public  Return all items converted to a string and concatenated, separated by a single space.
$join(sep) string @public  Return all items converted to a string and concatenated, separated by sep, which is used as a character.
$join(sep) string @public  Return all items converted to a string and concatenated, separated by sep.
$reverse() list<Titem> @public  Reverse the order of the list.
$sort() list<Titem> @public  Sort all items in ascending order. Supported for a list of string, int and objects.
$sort(ascending) list<Titem> @public  Sort all items in the specified order. Supported for a list of string, int and objects.
$map(f) list<Titem> @public  Execute function f on each item. Each item is replaced by the result of the function.
$keyMap(f) list<Titem> @public  Execute function f on each item. Each item is replaced by the result of the function.
$mapTo(f) list<Tresult> @public  Create a new list where each item is the result of executing function f on each item of this list.
$keyMapTo(f) list<Tresult> @public  Create a new list where each item is the result of executing function f on each item of this list.
$forEach(f) list<Titem> @public  Call method f for every item in the list.
$forKeyEach(f) list<Titem> @public  Call method f for every item in the list.
$reduce(f) Titem @public  Execute function f on each item to collect a result value.
$reduce(init, f) Titem @public  Execute function f on each item to collect a result value.
$reduceTo(init, f) Tresult @public  Execute function f on each item to collect a result value.
$filter(f) list<Titem> @public  Create a new list with those items where function f returns TRUE.
 
 

members (alphabetically)

     

PROC NEW() @public

     

Create a new empty list.

PROC NEW(int len, Titem value) @public

     

Create a list with len items set to value.

If Titem is a reference type all items contain that reference, thus refer to the same object.

Example:

 list<string> entries = NEW(20, "empty")

FUNC $Iterator() I.Iterator<Titem> @public

     

Return a BOX.ListIterator.

FUNC $KeyIterator() I.KeyIterator<int, Titem> @public

     

Return a BOX.ListKeyIterator.

FUNC $ToString() string @public

     

Return a string representation of the list.

Starts with "[" and ends in "]". Items are separated with ", ". An empty list returns "[]".

 string s = [12, 34].ToString()
 # s == "[12, 34]".

A NIL list 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-list]" will be used. However, if multiple threads are doing this for the same list the effect is unpredictable.

FUNC $ToString(string format) string @public

     

Return a string representation of the list 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 list.

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

FUNC $add(Titem item) list<Titem> @public

     

Adds an item to the end of the list.

Returns the list.

FUNC $add(Titem item, int index) list<Titem> @public

     

Adds an item after item index in the list.

When index is 0 the new item will be at position 1. When index is negative it is used relative to the end of the list. When index is -1 the item is added to the end of the list. When index is -2 it is inserted before the last item in the list.

When the index is higher than the list size the item is appended to the list. When the index is negative and the absolute value higher than the list size the item is prepended to the list.

Returns the list.

FUNC $clear() list<Titem> @public

     

Removes all items from the list.

Returns the list.

FUNC $clear(int index) list<Titem> @public

     

Removes item index from the list and returns the list.

index is used as with $add(): a negative index is relative to the end of the list.

When index is out of range the list is unchanged.

$remove(index) does the same but returns the removed item.

Returns the list.

FUNC $clearItem(Titem item) list<Titem> @public

     

Removes item from the list and returns the list.

When item is not in the list then nothing happens.

$remove(item) does the same but returns the removed item.

Returns the list.

FUNC $concat(list<Titem> other) list<Titem> @public

     

Create a new list with all items of this list and other.

If other is NIL the result is a copy of this list.

This is equivalent to using copy().extend(other).

Returns the new list.

FUNC $copy() list<Titem> @public

     

Return a shallow copy of the list.

The returned list is a new instance, the items are the same ones as in the current list, not copies.

FUNC $extend(list<Titem> other) list<Titem> @public

     

Appends all items of other to this list.

If other is NIL the list is unchanged.

Returns the list.

FUNC $filter(func<Titem => bool> f) list<Titem> @public

     

Create a new list with those items where function f returns TRUE.

 list<int> numberList = [1, -8, 3, 0]
 VAR positives = numberList.filter({ a => a > 0 })
 # positives is [1, 3].

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.

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

     

Call method f for every item in the list.

The argument for f is the value.

Returns the list.

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

     

Call method f for every item in the list.

The first argument for f is the index in the list, the second argument is the value.

Returns the list.

FUNC $get(int index) Titem @public

     

Get the item at index.

Same as using list[index].

FUNC $getLast(int index) Titem @public

     

Get the last item.

Same as using list[list.Size() - 1].

FUNC $has(Titem item) bool @public

     

Return TRUE if there is an item that equals item.

This is equivalent to:

 $find(item) != -1

FUNC $insert(Titem item) list<Titem> @public

     

Inserts an item before the start of the list.

Returns the list.

FUNC $insert(Titem item, int index) list<Titem> @public

     

Inserts an item before item index in the list.

index is used as with $add(): a negative index is relative to the end of the list. For example, to insert an item just before the last item in the list:

 myList.insert(item, -1)

Returns the list.

FUNC $join() string @public

     

Return all items converted to a string and concatenated, separated by a single space.

 IO.print([1, 2, 3].join())  # prints "1 2 3"

FUNC $join(int sep) string @public

     

Return all items converted to a string and concatenated, separated by sep, which is used as a character.

 IO.print([1, 2, 3].join('+'))  # prints "1+2+3"

FUNC $join(string sep) string @public

     

Return all items converted to a string and concatenated, separated by sep.

 IO.print([1, 2, 3].join(", "))  # prints "1, 2, 3"

FUNC $keyMap(func<int, Titem => Titem> f) list<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 list and the current value of the item. f must return the new value of the item.

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

Returns the list.

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

     

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

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

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

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

Returns the new list.

FUNC $map(func<Titem => Titem> f) list<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.

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

Returns the list.

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

     

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

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

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

Returns the new list.

FUNC $reduce(func<Titem, Titem => Titem> f) Titem @public

     

Execute function f on each item to collect a result value.

This first time f is called the first argument has the first item of the list.

If the list is empty the default item value (zero, FALSE, NIL) is returned.

If the list contains only one item that item is returned.

 list<int> numberList = [1, 2, 3, 4]
 int total = numberList.reduce({ a, b => a + b })
 # total is 10.

FUNC $reduce(Titem init, func<Titem, Titem => Titem> f) Titem @public

     

Execute function f on each item to collect a result value.

This first time f is called the first argument has the initvalue.

If the list is empty the init value is returned.

 list<int> numberList = [1, -8, 3, 4]
 int positiveMax = numberList.reduce(1, { a, b => b > a ? b : a })
 # positiveMax is 4.

FUNC $reduceTo(Tresult init, func<Tresult, Titem => Tresult> f) Tresult @public

     

Execute function f on each item to collect a result value.

This first time f is called the first argument has the init value.

If the list is empty the init value is returned.

 list<int> numberList = [1, -8, 3, 4]
 string values = numberList.reduceTo("values:", { r, v => r .. " " .. v })
 # values is "values: 1 -8 3 4"

FUNC $remove() Titem @public

     

Removes the last item from the list and returns it.

This does the same as remove(-1).

When using a list as a stack, it is most efficient to use add() to push items and remove() to pop items. Using insert() and remove(0) will also work but is less efficient.

FUNC $remove(int index) Titem @public

     

Removes the item at index from the list and returns it.

index is used as with $add(): a negative index is relative to the end of the list.

$clear(index) does the same but returns the list.

When index is out of range the list is unchanged and the default item value returned (NIL, zero, FALSE).

FUNC $remove(int from, int to) list<Titem> @public

     

Removes items from to to (inclusive) from the list and returns them in a new list.

from and to are used as with $add(): a negative index is relative to the end of the list.

 list<string> myList = ["zero", "one", "two", "three", "four", "five"]
 list<string> removed = myList.remove(1, 3)
 # removed == ["one", "two", "three"]

When from or to is before the list then index zero is used. When from or to is past the end of the list then the last item in the list is used. If the from item is beyond the to item the list is unmodified and an empty list is returned.

FUNC $removeItem(Titem item) Titem @public

     

Remove item from the list and return it.

Throws an E.KeyNotFound exception if the item is not present.

FUNC $reverse() list<Titem> @public

     

Reverse the order of the list.

Returns the list

FUNC $set(int index, Titem value) list<Titem> @public

     

Set the item at index.

Same as assigning to list[index]. A negative index is relative to the end, -1 refers to the last item.

Throws an E.OutOfRange exception when index does not refer to an existing list item.

Returns the list.

FUNC $size() int @public

     

Return the number of items in the list.

When the list is NIL this returns zero, it does not throw an E.NilAccess exception.

FUNC $slice(int start) list<Titem> @public

     

Create a new list with all items starting at start.

When start is before the first item zero is used. When start is beyond the last item an empty list is returned.

When Titem is a reference type both the original list and the slice point to the same objects, as with a shallow copy.

When start is zero this is equivalent to $copy().

Returns the new list. When the list is NIL returns NIL.

FUNC $slice(int start, int end) list<Titem> @public

     

Create a new list with all items starting at start to end (inclusive).

When start is before the first item zero is used. When end is beyond the last item the last item is used. When end is before start then an empty list is returned.

When Titem is a reference type both the original list and the slice point to the same objects, as with a shallow copy.

Returns the new list. When the list is NIL returns NIL.

FUNC $sliceSize(int start, int length) list<Titem> @public

     

Create a new list with all items starting at start with up to length items.

When start is before the first item zero is used. When start is beyond the last item an empty list is returned.

When Titem is a reference type both the original list and the slice point to the same objects, as with a shallow copy.

Returns the new list. When the list is NIL returns NIL.

FUNC $sliceWrap(int start) list<Titem> @public

     

Create a new list with all items starting at start.

start is used as with $add(): a negative start is relative to the end of the list.

When start is before the first item zero is used. When start is beyond the last item an empty list is returned.

When Titem is a reference type both the original list and the slice point to the same objects, as with a shallow copy.

When start is zero this is equivalent to $copy().

Returns the new list. When the list is NIL returns NIL.

FUNC $sliceWrap(int start, int end) list<Titem> @public

     

Create a new list with all items starting at start to end (inclusive).

start and end are used as with $add(): a negative index is relative to the end of the list.

When start is before the first item zero is used. When end is beyond the last item the last item is used. When end is before start then an empty list is returned.

When Titem is a reference type both the original list and the slice point to the same objects, as with a shallow copy.

Returns the new list. When the list is NIL returns NIL.

FUNC $sliceWrapSize(int start, int length) list<Titem> @public

     

Create a new list with all items starting at start with up to length items.

start is used as with $add(): a negative index is relative to the end of the list.

When start is before the first item zero is used. When start is beyond the last item an empty list is returned.

When Titem is a reference type both the original list and the slice point to the same objects, as with a shallow copy.

Returns the new list. When the list is NIL returns NIL.

FUNC $sort() list<Titem> @public

     

Sort all items in ascending order. Supported for a list of string, int and objects.

When Titem is a class it must have the Compare() method:

 FUNC Compare(Titem other) int
The method must return 0 when the value of other is equal to the value of the current item, smaller than zero when other has a larger value and larger than zero if other has a smaller value.

Returns the list, which is now sorted.

FUNC $sort(bool ascending) list<Titem> @public

     

Sort all items in the specified order. Supported for a list of string, int and objects.

This is the same as sort(), but when ascending if FALSE then the sort order is descending.

Returns the list, which is now sorted.

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