$ListMove
Move a $list
Note: Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $ListMove function, because Stringlists are not tied to an internally generated list identifier.
This function changes the association of a $list from one $list identifier to another. It is especially useful for making it possible to repeatedly execute the same set of code that creates $lists without losing the results of previous executions.
The $ListMove function accepts two arguments and returns a numeric result.
The first argument is the identifier of the target $list. This is a required argument.
The second argument is the identifier of the source $list. This is a required argument.
Syntax
%result = $ListMove(list_id_target, list_id_source)
%result is set either to the number of items in the moved $list, or to an error code.
-5 - Required argument not specified -6 - Source or target $list identifier invalid
$ListMove Error Codes
If the target $list for $ListMove is not empty when the function is invoked the current contents are deleted before the source $list contents replace it. That is,
%RC = $ListMove(%TARGET, %SOURCE)
is equivalent to
%RC = $ListDel(%TARGET) %RC = $ListMove(%TARGET, %SOURCE)
After a $ListMove is completed, the source $list is empty since its former contents are then associated with the target $list.
$ListMove performs no logical I/O; it simply moves the pointer to the anchor page for a $list from one area of VTBL to another. Because of this $ListMove is very efficient, no matter what the size of the $list being moved.
Many $functions, for example $ListNew, $ListCpy, and $ListSrt, return the same $list identifier for each particular instance of the $function. Because of this, it can be inconvenient writing code that uses these functions if the code is to be executed repeatedly. For example, suppose you have a subroutine that simply sorts an input $list. A natural way to code this might be
SUBROUTINE LSORT(%LIST IS FLOAT OUTPUT) %OLIST IS FLOAT %RC IS FLOAT %OLIST = $ListSrt(%LIST, '1,10,A') %RC = $ListDel(%LIST) %LIST = %OLIST RETURN END SUBROUTINE
The problem with this subroutine is that it always returns the same $list identifier in %LIST. This means that if it is invoked multiple times with different input $lists, only the result of the last invocation will ever be saved since all invocations will be associated with the same $list identifier. $ListMove makes it possible to make such a subroutine completely reentrant.
SUBROUTINE LSORT(%LIST IS FLOAT) %OLIST IS FLOAT %RC IS FLOAT %OLIST = $ListSrt(%LIST, '1,10,A') %RC = $ListMove(%LIST, %OLIST) RETURN END SUBROUTINE
With $LISTMOVE, the result of subroutine LSORT is associated with the identifier of the input $list so it can be invoked with different input $lists without interfering with the results of previous invocations.
Another common problem $ListMove helps with is the problem that occurs in scrolling applications where an end-user might be allowed to sort a $list based on many different sort criteria. Intuitively, this would map to a simple chunk of code such as
%SLIST = $ListSrt(%LIST, %CRITERIA) %RC = $ListDel(%LIST) %LIST = %SLIST
Unfortunately, in such an application, the above chunk of code might be executed multiple times which means that on the second invocation, the $ListDel would actually delete the result of the $ListSrt. Before the availability of $ListMove, a common technique for dealing with this was to have two identical $ListSrt statements that would get alternately executed on consecutive invocations of the same chunk of code, as in
%SWITCH = 1 - %SWITCH IF %SWITCH THEN %SLIST = $ListSrt(%LIST, %CRITERIA) ELSE %SLIST = $ListSrt(%LIST, %CRITERIA) END IF %RC = $ListDel(%LIST) %LIST = %SLIST
Needless to say, this is quite ugly. With $ListMove, the code can be simplified to
%SLIST = $ListSrt(%LIST, %CRITERIA) %RC = $ListMove(%LIST, %SLIST)