===== Lists =====

Lists are ordered collections of objects of any type. Lists are entered as a sequence of objects enclosed in curly braces ''{'' and ''}''. The syntax rules of each individual object still apply when they are within a list.
Lists can contain any number of items, including none, therefore the empty list ''{ }'' is valid and can be used. Items can be repeated within a list, and the order in which items are inserted is preserved unless the order is intentionally changed, for example using the ''SORT'' command.

----
==== Operating with Lists ====

In most cases, commands will accept a list instead of a single argument and will proceed according to the [[manual:chapter5:listproc|Parallel Processing with Lists section]].
For example, lists can be used to quickly apply the same operation to more than one value:

<code>
2:                     { 1 2 3 }
1:                             1
……………………………………………………………………………………
+
</code>
will result in adding ''1'' to each element on the list: ''{ 2 3 4 }''.

There's operations that are exclusive to lists, for example the command ''ADD'' will concatenate two lists, or append 1 element at the end of the list.

<code>
2:                     { 1 2 3 }
1:                             1
……………………………………………………………………………………
ADD
</code>
will result in ''{ 1 2 3 1 }'' and
<code>
2:                     { 1 2 3 }
1:                     { 4 5 6 }
……………………………………………………………………………………
ADD
</code>
will result in ''{ 1 2 3 4 5 6 }''

Other common commands that operate on lists are:

  * ''→LIST'': Creates a list from loose objects in the stack
  * ''LIST→'': Split a list into individual objects in the stack
  * ''SORT'': Sort the elements of a list
  * ''REVLIST'': Reverses the order of a list


==== Elements within a List ====

Elements in a list can be referred to by a numeric index. The index starts at ''1'' for the first element of the list. To get an element from a list, the ''GET'' command is used:
<code>
2:                  { 11 12 13 }
1:                             2
……………………………………………………………………………………
GET
</code>
will result in ''12''.

Replacing an element is done via the ''PUT'' command:

<code>
3:                  { 11 12 13 }
2:                             2
1:                             3
……………………………………………………………………………………
PUT
</code>
will result in ''{ 11 3 13 }'' because the object ''3'' replaced the object at index ''2''

Elements of a list can also be accessed from within algebraic expression (read-only) by giving the list a name (store the list in a variable using ''STO'' or ''LSTO'') and then including the index in parenthesis, much like a mathematical function.
For example, assuming the list ''{ 11 12 13 }'' was stored in variable ''L'', evaluating ''%%'L(2)+10'%%'' will result in ''22'' as expected.
==== Procedures with Lists ====