CLASS T.sortedList<Titem> @public

summary

The builtin type sortedList.

SortedLists keep a list in sorted order. Either using the Compare method of the item or an explicitly specified sort method.

This is similar to a priority queue. However, the order is determined by the items themselves, not by a separately provided priority.

Example:

 sortedList<string> sl = NEW()
 sl.add('yes').add('no').add('maybe')
 IO.print("sortedList: " .. sl.ToString())

Results in: sortedList: ["maybe", "no", "yes"]

The sorting only happens when an item is added. When an item is modified it needs to be removed and added back to update the sort order.

Implements I.Iterable<Titem>

	NEW() @public	Create a new empty sortedList.
	NEW(items) @public	Create a new sortedList from a list of items.
	$Size() int @public	Return the number of items in the sortedList.
	$ToString() string @public	Return a string representation of the sortedList.
	$copy() SortedList<Titem> @public	Return a copy of the sortedList.
	$Iterator() I.Iterator<Titem> @public	Get an iterator to go over the items in sorted order.
	$KeyIterator() I.KeyIterator<int, Titem> @public	Get a key iterator to go over the items in sorted order.
	$getList() list<Titem> @public	Return the ordinary list with the items.
	$setSortMethod(method) @public	Set the method to use for comparing two items.
	$get(index) Titem @public	Return the item at position index.
	$set(index, value) SortedList<Titem> @public	Set the item at index.
	$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) SortedList<Titem> @public	Add an item to the sortedList.
	$add(item, index) SortedList<Titem> @public	Add an item to the sortedList. Identical to add(item).
	$insert(item) SortedList<Titem> @public	Add an item to the sortedList. Identical to add(item).
	$insert(item, index) SortedList<Titem> @public	Add an item to the sortedList. Identical to add(item).
	$clear() SortedList<Titem> @public	Make the sortedList empty.
	$clear(index) SortedList<Titem> @public	Remove an item at index from the sortedList. and return the sortedList.
	$remove() Titem @public	Removes the last item from the list and returns it.
	$remove(index) Titem @public	Removes the item at index from the sortedList and returns it.
	$remove(from, to) list<Titem> @public	Removes items from to to (inclusive) from the list and returns them in a new list.
	$extend(items) SortedList<Titem> @public	Add a all items of list items to this sortedList.
	$extend(items) SortedList<Titem> @public	Add a all items of sortedList items to this sortedList.
	$concat(other) SortedList<Titem> @public	Create a new list with all items of this list and list other
	$concat(other) SortedList<Titem> @public	Create a new list with all items of this list and sortedList other
	$has(item) bool @public	Check if an item is present in the sortedList.
	$find(item) int @public	Return the index of item in the sortedList.
	$join() string @file	Return all items converted to a string and concatenated, separated by a single space.
	$join(sep) string @file	Return all items converted to a string and concatenated, separated by sep.
	$sort() SortedList<Titem> @public	Ensures that the items are sorted.
	$map(f) SortedList<Titem> @public	Execute function f on each item. Each item is replaced by the result of the function.
	$keyMap(f) SortedList<Titem> @public	Execute function f on each item. Each item is replaced by the result of the function.
	$mapTo<Tresult>(f) SortedList<Tresult> @public	Create a new sortedList where each item is the result of executing function f on each item of this sortedList.
	$keyMapTo<Tresult>(f) SortedList<Tresult> @public	Create a new sortedList where each item is the result of executing function f on each item of this sortedList.
	$forEach(f) sortedList<Titem> @public	Call method f for every item in the sortedList.
	$forKeyEach(f) sortedList<Titem> @public	Call method f for every item in the sortedList.
	$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<Tresult>(init, f) Tresult @public	Execute function f on each item to collect a result value.

Included from BOX.ByItem:
	$removeItem(item) Titem @public	Remove item and return it.
	$clearItem(item) THIS @public	Remove item and return THIS.

Included from BOX.MaxMin:
	$max() Titem @public	Return the maximum value in the Box.
	$min() Titem @public	Return the minimum value in the Box.

members (alphabetically)

PROC NEW() @public

Create a new empty sortedList.

PROC NEW(list<Titem> items) @public

Create a new sortedList from a list of items.

The items does not need to be sorted.

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

Get an iterator to go over the items in sorted order.

Returns a SortedListIterator, which implements I.Iterator, I.MutateIterator and I.BidiIterator. Note that set() and add() are not supported, because it confuses the iterator.

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

Get a key iterator to go over the items in sorted order.

Returns a BOX.ListKeyIterator, which implements I.KeyIterator.

FUNC $Size() int @public

Return the number of items in the sortedList.

FUNC $ToString() string @public

Return a string representation of the sortedList.

Looks like a list of the items: [item1, item2, item3]

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

Add an item to the sortedList.

item will be placed in the correct place to keep the sortedList sorted.

item must not be NIL.

Returns the sortedList.

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

Add an item to the sortedList. Identical to add(item).

index is ignored, this method exists only to be compatible with list.

Returns the sortedList.

FUNC $clear() SortedList<Titem> @public

Make the sortedList empty.

Returns the sortedList.

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

Remove an item at index from the sortedList. and return the sortedList.

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

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

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

Returns the new sortedList.

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

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

Returns the sortedList.

FUNC $copy() SortedList<Titem> @public

Return a copy of the sortedList.

FUNC $extend(list<Titem> items) SortedList<Titem> @public

Add a all items of list items to this sortedList.

Returns the sortedList.

FUNC $extend(sortedList<Titem> items) SortedList<Titem> @public

Add a all items of sortedList items to this sortedList.

Returns the sortedList.

FUNC $find(Titem item) int @public

Return the index of item in the sortedList.

Returns -1 when item is not found.

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

Call method f for every item in the sortedList.

The argument for f is the value.

Returns the sortedList.

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

Call method f for every item in the sortedList.

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

Returns the sortedList.

FUNC $get(int index) Titem @public

Return the item at position index.

FUNC $getList() list<Titem> @public

Return the ordinary list with the items.

Does not make a copy, changing the returned list will change the sortedList without keeping it sorted.

FUNC $has(Titem item) bool @public

Check if an item is present in the sortedList.

Returns TRUE or FALSE.

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

Add an item to the sortedList. Identical to add(item).

Returns the sortedList.

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

Add an item to the sortedList. Identical to add(item).

index is ignored, this method exists only to be compatible with list.

Returns the sortedList.

FUNC $join() string @file

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

FUNC $join(string sep) string @file

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

FUNC $keyMap(func<int, Titem => Titem> f) SortedList<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<Tresult>(func<int, Titem => Tresult> f) SortedList<Tresult> @public

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

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.

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

Returns the new sortedList.

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

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

Returns the sortedList.

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

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

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

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

 sortedList<int> il = [1, 2, 3]
 sortedList<string> sl = il.mapTo({ i => i.ToString() })
 # sl == ["1", "2", "3"]

Returns the new sortedList.

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

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

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

 sortedList<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>(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).

FUNC $remove(int index) Titem @public

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

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

Returns the item. 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.

See list.remove(from to) for details.

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

Set the item at 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 sortedList.

PROC $setSortMethod(func<Titem, Titem => int> method) @public

Set the method to use for comparing two items.

The method must return zero when the two items are equal, < 0 when the first one sorts before the second one and > 0 when the first one sorts after the second one.

When method is NIL the item Compare() method is used.

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. Note: Not a sortedList!. 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. Note: Not a sortedList!. 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. Note: Not a sortedList!. 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. Note: Not a sortedList!. 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. Note: Not a sortedList!. 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.

When start is before the first item zero is used. When going beyond the end of the list items are omitted. When start is after the last item 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. Note: Not a sortedList!. When the list is NIL returns NIL.

FUNC $sort() SortedList<Titem> @public

Ensures that the items are sorted.

Can be used after the list returned by $getList() was modified, or when individual items have been modified.

Returns the sortedList.

license

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