$ListMove: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
mNo edit summary
Line 2: Line 2:
<span class="pageSubtitle"><section begin="desc" />Move a $list<section end="desc" /></span>
<span class="pageSubtitle"><section begin="desc" />Move a $list<section end="desc" /></span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListMove function is [[to be entered]].</p>
<p class="warning">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.</p>


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.  
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.  
Line 11: Line 11:


The second argument is the identifier of the source $list. This is a required argument.
The second argument is the identifier of the source $list. This is a required argument.
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> %RESULT = $ListMove(list_id_target, list_id_source)
<p class="syntax"><section begin="syntax" /> %RESULT = $ListMove(list_id_target, list_id_source)
Line 23: Line 24:
<p class="caption">$ListMove Error Codes
<p class="caption">$ListMove Error Codes
</p>
</p>


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,
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,
<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>
After a $ListMove is completed, the source $list is empty since its former contents are then associated with the target $list.  
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.  
$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
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)
   
   
Line 49: Line 53:
  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. $ListMove 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. $ListMove 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)
   
   
Line 64: Line 70:


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
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
<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
Line 79: Line 88:
  %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)

Revision as of 15:36, 10 February 2011

<section begin="desc" />Move a $list<section end="desc" />

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

<section begin="syntax" /> %RESULT = $ListMove(list_id_target, list_id_source) <section end="syntax" />

$ListMove Function

%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