$ListMove

From m204wiki
Revision as of 23:44, 12 September 2013 by JALWiccan (talk | contribs) (Automatically generated page update)
Jump to navigation Jump to search

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.

Error codes

-5 - Required argument not specified -6 - Source or target $list identifier invalid

Usage notes

  • 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)

    Products authorizing $ListMove