MoveToId (Stringlist subroutine): Difference between revisions
Jump to navigation
Jump to search
m (syntax digram, tags and links) |
mNo edit summary |
||
| (4 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Stringlist:MoveToId subtitle}} | {{Template:Stringlist:MoveToId subtitle}} | ||
This method moves data (<var>stringlist</var> items) from a <var> | This method moves data (<var>stringlist</var> items) from a <var>Stringlist</var> to a [[$lists|$list]]. <var>MoveToId</var> is a subroutine that accepts one argument: the $list identifier of the $list to which data is to be moved. | ||
==Syntax== | ==Syntax== | ||
{{Template:Stringlist:MoveToId syntax}} | {{Template:Stringlist:MoveToId syntax}} | ||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>sl</th> | <tr><th>sl</th> | ||
<td>A <var>Stringlist</var> object.</td></tr> | <td>A <var>Stringlist</var> object.</td></tr> | ||
<tr><th> | |||
<td>The | <tr><th>listId</th> | ||
<td>The $list identifier of the $list to which data is to be moved.</td></tr> | |||
</table> | </table> | ||
==Usage notes== | ==Usage notes== | ||
<ul><li>All errors in <var>MoveToId</var> result in request cancellation.<li>After <var>MoveToId</var> is invoked, the method <var>Stringlist</var> is emptied, although the object variable is still valid (non-null).<li><var>MoveToId</var> discards | <ul><li>All errors in <var>MoveToId</var> result in request cancellation. | ||
<li>After <var>MoveToId</var> is invoked, the method <var>Stringlist</var> is emptied, although the object variable is still valid (non-null). | |||
<li><var>MoveToId</var> discards any current contents of the target $list. | |||
<li><var>MoveToId</var> copies to the target $list any image association that is set via <var>[[BindImage (Stringlist subroutine)|BindImage]]</var>. | |||
<li><var>MoveToId</var> simply moves the <var>Stringlist</var> internal data pointers to the to the target $list. It does <b><i>not</i></b> actually perform any data movement; therefore, it is extremely efficient. | |||
<li><var>MoveToId</var> is intended to facilitate the migration to the use of <var>Stringlists</var> of existing applications that use $lists. | |||
<li><var>stringlists</var> should always be used in preference to $lists, so <var>MoveToId</var> is provided only for the migration of existing $list applications to the use of <var>Stringlists</var>. | |||
</ul> | |||
==Examples== | ==Examples== | ||
Suppose complex subroutine Summarize takes a $list identifier as its input parameter. Now, suppose some code that has a <var>Stringlist</var> in %list wants to pass the <var>Stringlist</var> to Summarize. | Suppose complex subroutine <code>Summarize</code> takes a $list identifier as its input parameter. Now, suppose some code that has a <var>Stringlist</var> in <code>%list</code> wants to pass the <var>Stringlist</var> to <code>Summarize</code>. | ||
The following code illustrates how this can be accomplished: | The following code illustrates how this can be accomplished: | ||
| Line 27: | Line 41: | ||
</p> | </p> | ||
[[ | ==See also== | ||
<ul> | |||
<li><var>[[MoveFromId (Stringlist subroutine)|MoveFromId]]</var> does the converse operation (move $list data into a <var>Stringlist</var>)</ul> | |||
{{Template:Stringlist:MoveToId footer}} | |||
Latest revision as of 18:51, 31 October 2012
Move data from Stringlist to $list (Stringlist class)
This method moves data (stringlist items) from a Stringlist to a $list. MoveToId is a subroutine that accepts one argument: the $list identifier of the $list to which data is to be moved.
Syntax
sl:MoveToId( listId)
Syntax terms
| sl | A Stringlist object. |
|---|---|
| listId | The $list identifier of the $list to which data is to be moved. |
Usage notes
- All errors in MoveToId result in request cancellation.
- After MoveToId is invoked, the method Stringlist is emptied, although the object variable is still valid (non-null).
- MoveToId discards any current contents of the target $list.
- MoveToId copies to the target $list any image association that is set via BindImage.
- MoveToId simply moves the Stringlist internal data pointers to the to the target $list. It does not actually perform any data movement; therefore, it is extremely efficient.
- MoveToId is intended to facilitate the migration to the use of Stringlists of existing applications that use $lists.
- stringlists should always be used in preference to $lists, so MoveToId is provided only for the migration of existing $list applications to the use of Stringlists.
Examples
Suppose complex subroutine Summarize takes a $list identifier as its input parameter. Now, suppose some code that has a Stringlist in %list wants to pass the Stringlist to Summarize.
The following code illustrates how this can be accomplished:
%listid = $listnew %list:moveToId(%listId) call summarize(%listId) %list:moveFromId(%listId) return
See also
- MoveFromId does the converse operation (move $list data into a Stringlist)