MoveToId (Stringlist subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
mNo edit summary
 
(2 intermediate revisions by 2 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>stringlist</var> to a <var>$list</var>. <var>MoveToId</var> is a subroutine that accepts one argument: the <var>$list</var> identifier of the <var>$list</var> to which data is to be moved. For more information about <var>$list</var> identifiers, see the <var>[[Sirius Functions Reference Manual]]</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>listid</th>
 
<td>The <var>$list</var> identifier of the <var>$list</var> to which data is to be moved.</td></tr>
<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 the original contents of the target <var>$list</var>.<li><var>MoveToId</var> copies to the target <var>$list</var> 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 <var>$list</var>. It does '''not''' 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>Stringlist</var>s of existing applications that use $lists.<li><var>stringlists</var> should always be used in preference to <var>$lists</var>, so <var>MoveToId</var> is provided only for the migration of existing <var>$list</var> applications to the use of <var>stringlists</var>.</ul>
<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 28: Line 42:


==See also==
==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}}
{{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)