Index | PAL Intro | Commands | Registers | Indices | Stack | Macros | Classes | Attributes | Errors

list/def - Define a list sequence

CONTENTS

Synopsis
Description
Appending And Merging
Error Handling
Examples
See Also
Author

list/def write, read <, read ... >

Initialises a list sequence, which is a collection of arguments encapsulated inside a single structure. The list sequence will be stored in the write argument (as type PSUNIT_TYPE_LIST). This is a new memory structure that can be released using reg/clr.

One or more read arguments may be provided, defining the contents of the list. A read argument may be a sequence in the format @[list_arguments], or it may be a register containing the type PSUNIT_TYPE_LIST. Registers supplied inside enclosing @[ ... ] sequence brackets are evaluated and their contents are stored in the target list. See pal_indices(5) for a full discussion of list sequence brackets.

If a register of type PSUNIT_TYPE STRING or PSUNIT_TYPE_XVALUE is used in the enclosing @[ ... ] sequence brackets, and the instruction does not generate an error, then the register will be cleared as the data is now referenced elsewhere.

If the read argument is a register of type PSUNIT_TYPE_LIST then the referenced list will either be appended to or merged in the target, depending on its argument position. See APPENDING AND MERGING.

If a read argument of type PSUNIT_TYPE_NULL is provided, that argument is ignored.

An existing list may have new values appended to it using the list/def instruction. To achieve this, provide the register that contains the list in the write and the first read argument. The effect will be, rather than creating a new list, all remaining arguments will be appended to the end of the existing list.

To merge an existing list into the target, simply provide the register that contains the list as any read argument, except the first read argument. In this case the original list is left intact.

A runtime error is generated if a register is provided as a read argument that is not of type PSUNIT_TYPE_LIST, if an attempt is made to insert a list sequence inside a list sequence, or if a register containing the type PSUNIT_TYPE_STRING or PSUNIT_TYPE_XVALUE is referenced inside enclosing @[ ... ] sequence brackets more than once.

list/def P0, @[#5, #130, [Thames]]
	Sets up a new list sequence containing the two 32-bit unsigned integers 5 and 130, and the text "Thames". The new list will be stored in register P0 and can be released again using reg/clr.
list/def P0, P0, @[35, -12]
	Appends the GMP integers 35 and -12 to the end of an existing list sequence in register P0.
list/def P3, P1, @[[*]], P2, @[[*]]
	Merges list sequences in registers P1 and P2 into a new list, terminating each list with an additional element that contains an asterisk character (*). The new list will be stored in register P3. The existing lists in P1 and P2 will remain intact.
list/def P10, @[PULL, PULL, PULL]
	Pulls the topmost three items off the program stack and stores in a new list in register P10.

pal_commands(5), pal_registers(5), pal_indices(5), pal_stack(5), reg_clr(5), func_def(5), mtx_def(5), tree_def(5),
PROSE Assembly Language at prose.sourceforge.net.

Copyright (c) 2002-2012 Mark R. Bannister <cambridge@users.sourceforge.net>.

This is free software and can be downloaded from prose.sourceforge.net; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.