List

List queries, transformations, etc. Lists are a series of zero or more values, all of the same fundamental type. There can be lists of numbers, text, or records. Lists of boolean values are not supported. The first value of a list is at index 1 (one).

Definitions:

Commands:

Erase:[index:][count:] Remove one or more values from a list.
Erase:[index:][count:]as:do:[else:] Remove a number of values from a list starting at a specified index.
Find:value: Search a list for a specific value.
Is empty: Determine if the length of the list is zero.
List length: Determine the number of values in a list.
Map:using:list: Transform the values from one list and append the results to another.
Num list: Collect one or more numbers into a list.
Pop:[front:] Remove a value from the end ( or the start ) of a list.
Pop:[front:]as:do:[else:] Remove a value from the end ( or the start ) of a list.
Push:value:[front:] Add a value to the end ( or the beginning ) of a list.
Range:[start:][by:] Generate a list of numbers r[i] = (start + step*i) where i>=0.
Record list: Collect one or more records into a list.
Reduce:using:list: Pack the values of a list down into a single value.
Repeat across:as:do:[else:] Run a series of statements for each value in a list.
Reverse list: Reverse the order of the values in a list.
Slice:[start:][end:] Create a new list from part of another list.
Sort:[field:][descending:][case:] Rearrange the values in a list.
Splice:[start:][count:][insert:] Modify a list by adding and removing values.
Text list: Collect one or more text values into a list.

Commands

Erase:[index:][count:]

Remove one or more values from a list.

Slots:

Execute

Terms:

Erase:	Address	The list to modify.
index: optional	NumEval	The one-based index at which to start removing values. If not specified, starts with the first value.
count: optional	NumEval	The number of values to remove. If not specified, removes one value.

Erase:[index:][count:]as:do:[else:]

Remove a number of values from a list starting at a specified index. Run a series of statements, giving them a new local variable containing a list of removed values.

Slots:

Execute

Terms:

Erase:	Address	The list to modify.
index: optional	NumEval	The one-based index at which to start removing values. If not specified, starts with the first value.
count: optional	NumEval	The number of values to remove. If not specified, removes one value.
as:	Text	The new local variable which contains the erased values.
do:	Execute repeats	The statements to call with the erased values. If no "else" branch is specified, and no values were removed, this will be called with an empty list.
else: optional	Brancher	Optional statements to run if no values were removed.

Find:value:

Search a list for a specific value.

The [rt.NumEval] version returns the index of the value in the list.

Slots:

Terms:

Find:	Assignment	The list to search.
value:	Assignment	The value to find.

Is empty:

Determine if the length of the list is zero.

Slots:

BoolEval

Terms:

empty:

Assignment

The list to measure.

List length:

Determine the number of values in a list.

Slots:

NumEval

Terms:

length:

Assignment

The list to measure.

Map:using:list:

Transform the values from one list and append the results to another. The designated pattern is called with each value, one value at a time.

Slots:

Execute

Terms:

Map:	Address	The list to push new values into. The type of this list needs to match the type of the list being evaluated.
using:	Text	The pattern to call for every value in the list being evaluated.
list:	Assignment	The list being evaluated. Every value in this list will be sent to the mapping pattern. The type of this list needs to match the type of the list being written to.

Num list:

Collect one or more numbers into a list.

Slots:

NumListEval

Terms:

list:

NumEval repeats

One or more number values to evaluate.

Pop:[front:]

Remove a value from the end ( or the start ) of a list.

Slots:

Execute

Terms:

Pop:	Address	The list to modify.
front: optional	BoolEval	Whether to remove from the front or the back of the list. If not specified, removes from the back.

Pop:[front:]as:do:[else:]

Remove a value from the end ( or the start ) of a list. Run a series of statements, giving them a new local variable containing the removed value.

Slots:

Execute

Terms:

Pop:	Address	The list to modify.
front: optional	BoolEval	Control whether to remove from the front or the back of the list. If not specified, removes from the back.
as:	Text	The name of a new local variable to receive the removed value. The variable is only in scope for the duration of the "do" statements.
do:	Execute repeats	A series of statements to run if a value was removed.
else: optional	Brancher	Optional statements to run if the specified list was empty. There are no special local variables defined when this is called.

Push:value:[front:]

Add a value to the end ( or the beginning ) of a list.

Slots:

Execute

Terms:

Push:	Address	The list to modify.
value:	Assignment	The value to add to the list.
front: optional	BoolEval	Control whether to add the new value to the front or to the back of the list. If not specified, adds to the back.

Range:[start:][by:]

Generate a list of numbers r[i] = (start + step*i) where i>=0. Inputs are truncated to produce whole numbers. A positive step ends the series when the returned value would exceed stop. A negative step ends before generating a value less than stop.

Slots:

NumListEval

Terms:

Range:	NumEval	The last number to generate.
start: optional	NumEval	The first number generated. Defaults to one(1) if not specified.
by: optional	NumEval	The step to reach the next number. Defaults to one(1), errors if zero.

Record list:

Collect one or more records into a list. All of the records must be of the same type.

Slots:

RecordListEval

Terms:

list:

RecordEval repeats

One or more record values to evaluate.

Reduce:using:list:

Pack the values of a list down into a single value. The designated pattern is called with a pair of parameters for each value in the list:

the current value from the list;
the value being packed.

The pattern is expected to return the newly updated value.

Slots:

Execute

Terms:

Reduce:	Address	The value being packed.
using:	Text	The pattern to call for every value in the list being reduced.
list:	Assignment	The list being reduced.

Repeat across:as:do:[else:]

Run a series of statements for each value in a list. Several local variables are available to those statements:

the value in the list, named as specified.
"index", the one-based index of the current value in the list.
"first", a boolean indicating if this is the first value
"last", a boolean indicating if this is the last value.

If the list was empty, this runs the else branch instead.

Slots:

Execute

Terms:

across:	Assignment	The list to read values from.
as:	Text	The name of a (new) variable, given to the "do" statements, filled with the values from the list, one at a time.
do:	Execute repeats	A series of statements to run.
else: optional	Brancher	Optional statements to run if the specified list was empty. There are no special local variables defined when this is called.

Reverse list:

Reverse the order of the values in a list. The first becomes last, the weak become strong, the list gets reversed, all that.

Slots:

Execute

Terms:

list:

Address

The list to modify.

Slice:[start:][end:]

Create a new list from part of another list. Start is optional, if omitted slice starts at the beginning. If start is greater the length, an empty array is returned. Slice doesn't include the ending index. Negatives indices indicates an offset from the end. When end is omitted, or if its greater than the the length of the list, the slice will include everything from start up to and including the last value.

Slots:

Terms:

Slice:	Assignment	The list to copy values from.
start: optional	NumEval	The one-based index to start copying from. See the command documentation for full details.
end: optional	NumEval	The one-based index of the last value to copy. See the command documentation for full details.

Sort:[field:][descending:][case:]

Rearrange the values in a list.

Slots:

Execute

Terms:

Sort:	Address	The list to modify.
field: optional	TextEval	Use the specified field to compare values. Optional, and only makes sense for lists containing records or objects.
descending: optional	BoolEval	When true, reorder the list by decreasing value: largest value first. Otherwise, reorder the list by increasing value: smallest value first.
case: optional	BoolEval	When sorting text this indicates whether the lower case letters should be considered different than upper case letters. By default, they are considered the same. ( This uses ascii comparisons, so uppercase 'A' is considered less than lowercase 'a' )

Splice:[start:][count:][insert:]

Modify a list by adding and removing values. The type of the values being added must match the type of the list. ( ie. Text cant be added to a list of numbers, and numbers cant be added to a list of text. ) If the starting index is negative, this begins that many values from the end of the array; if list's length plus the start is less than zero, this begins from index zero. If the remove count is missing, this removes all values from the start to the end; if the remove count is zero or negative, no values are removed.

Slots:

Terms:

Splice:	Address	The list to modify.
start: optional	NumEval	The one-based index to start cutting from. See the command documentation for full details.
count: optional	NumEval	The number of values to cut. See the command documentation for full details.
insert: optional	Assignment	Optionally, a set of new values to inject into the list, starting at the location that was cut. See the command documentation for full details.

Text list:

Collect one or more text values into a list.

Slots:

TextListEval

Terms:

list:

TextEval repeats

One or more text statements to evaluate.