$ListMove: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Automatically generated page update)
Line 13: Line 13:


==Syntax==
==Syntax==
<p class="syntax"><span class="term">%result</span> = <span class="literal">$ListMove</span>(<span class="term">list_id_target, list_id_source)
<p class="syntax"><span class="term">%result</span> = <span class="literal">$ListMove</span>(<span class="term">list_id_target</span>, <span class="term">list_id_source</span>)
</p>
</p>
<p>
<p>
</p>
<var class="term">%result</var> is set either to the number of items in the moved $list, or to an error code.</p>
<p>%result is set either to the number of items in the moved $list, or to an error code.</p>
<p class="code">-5 - Required argument not specified
<p class="code">  
-6 - Source or target $list identifier invalid
-5 - Required argument not specified
-6 - Source or target $list identifier invalid
</p>
</p>
<p class="caption">$ListMove Error Codes
<p class="caption">$ListMove Error Codes
Line 26: Line 25:


If the target $list for <var>$ListMove</var> is not empty when the function is invoked the current contents are deleted before the source $list contents replace it. That is,
If the target $list for <var>$ListMove</var> is not empty when the function is invoked the current contents are deleted before the source $list contents replace it. That is,
<p class="code"> %RC = $ListMove(%TARGET, %SOURCE)
<p class="code">%RC = $ListMove(%TARGET, %SOURCE)
</p>
</p>


is equivalent to
is equivalent to


<p class="code"> %RC = $ListDel(%TARGET)
<p class="code">%RC = $ListDel(%TARGET)
%RC = $ListMove(%TARGET, %SOURCE)
%RC = $ListMove(%TARGET, %SOURCE)
</p>
</p>


Line 41: Line 40:
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
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


<p class="code"> SUBROUTINE LSORT(%LIST IS FLOAT OUTPUT)
<p class="code">SUBROUTINE LSORT(%LIST IS FLOAT OUTPUT)
   
   
%OLIST IS FLOAT
%OLIST IS FLOAT
%RC IS FLOAT
%RC IS FLOAT
   
   
%OLIST = $ListSrt(%LIST, '1,10,A')
%OLIST = $ListSrt(%LIST, '1,10,A')
%RC = $ListDel(%LIST)
%RC = $ListDel(%LIST)
%LIST = %OLIST
%LIST = %OLIST
RETURN
RETURN
   
   
END SUBROUTINE
END SUBROUTINE
</p>
</p>


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. <var>$ListMove</var> makes it possible to make such a subroutine completely reentrant.
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. <var>$ListMove</var> makes it possible to make such a subroutine completely reentrant.


<p class="code"> SUBROUTINE LSORT(%LIST IS FLOAT)
<p class="code">SUBROUTINE LSORT(%LIST IS FLOAT)
   
   
%OLIST IS FLOAT
%OLIST IS FLOAT
%RC IS FLOAT
%RC IS FLOAT
   
   
%OLIST = $ListSrt(%LIST, '1,10,A')
%OLIST = $ListSrt(%LIST, '1,10,A')
%RC = $ListMove(%LIST, %OLIST)
%RC = $ListMove(%LIST, %OLIST)
RETURN
RETURN
   
   
END SUBROUTINE
END SUBROUTINE
</p>
</p>
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.  
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.  
Line 71: Line 70:
Another common problem <var>$ListMove</var> 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
Another common problem <var>$ListMove</var> 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


<p class="code"> %SLIST = $ListSrt(%LIST, %CRITERIA)
<p class="code">%SLIST = $ListSrt(%LIST, %CRITERIA)
%RC = $ListDel(%LIST)
%RC = $ListDel(%LIST)
%LIST = %SLIST
%LIST = %SLIST
</p>
</p>


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


<p class="code"> %SWITCH = 1 - %SWITCH
<p class="code">%SWITCH = 1 - %SWITCH
IF %SWITCH THEN
IF %SWITCH THEN
%SLIST = $ListSrt(%LIST, %CRITERIA)
%SLIST = $ListSrt(%LIST, %CRITERIA)
ELSE
ELSE
%SLIST = $ListSrt(%LIST, %CRITERIA)
%SLIST = $ListSrt(%LIST, %CRITERIA)
END IF
END IF
   
   
%RC = $ListDel(%LIST)
%RC = $ListDel(%LIST)
%LIST = %SLIST
%LIST = %SLIST
</p>
</p>


Needless to say, this is quite ugly. With $ListMove, the code can be simplified to
Needless to say, this is quite ugly. With $ListMove, the code can be simplified to


<p class="code"> %SLIST = $ListSrt(%LIST, %CRITERIA)
<p class="code">%SLIST = $ListSrt(%LIST, %CRITERIA)
%RC = $ListMove(%LIST, %SLIST)
%RC = $ListMove(%LIST, %SLIST)
</p>
</p>
<p class="code">


==Products authorizing {{PAGENAMEE}}==  
==Products authorizing {{PAGENAMEE}}==  

Revision as of 14:15, 11 April 2013

Move a $list

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)

Products authorizing $ListMove