MoveToId (Stringlist subroutine): Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
m (1 revision) |
||
| 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 $list. MoveToId is a subroutine that accepts one argument: the $list identifier of the $list to which data is to be moved. For more information about $list identifiers, see the ''Sirius Functions Reference Manual''. | This method moves data (<var>Stringlist</var> items) from a <var>Stringlist</var> to a $list. <var>MoveToId</var> is a subroutine that accepts one argument: the $list identifier of the $list to which data is to be moved. For more information about $list identifiers, see the ''Sirius Functions Reference Manual''. | ||
==Syntax== | ==Syntax== | ||
| Line 14: | Line 14: | ||
==Usage notes== | ==Usage notes== | ||
<ul><li>All errors in MoveToId result in request cancellation.<li>After the MoveToId method is invoked, the method <var>Stringlist</var> is empty, though the object variable is still valid (non-null).<li>MoveToId discards the original contents of the target $list.<li>The MoveToId method copies to the target $list any image association that is set via BindImage.<li>MoveToId simply moves the pointers to the <var>Stringlist</var> data to the target $list. It does '''not''' actually perform any data movement; therefore, it is extremely efficient.<li>MoveToId is intended to facilitate the migration to the use of <var>Stringlist</var>s of existing applications that use $lists. For example, 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. | <ul><li>All errors in <var>MoveToId</var> result in request cancellation.<li>After the <var>MoveToId</var> method is invoked, the method <var>Stringlist</var> is empty, though the object variable is still valid (non-null).<li><var>MoveToId</var> discards the original contents of the target $list.<li>The <var>MoveToId</var> method copies to the target $list any image association that is set via BindImage.<li><var>MoveToId</var> simply moves the pointers to the <var>Stringlist</var> data to the target $list. 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. For example, 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. | ||
The following code illustrates how this can be accomplished: | The following code illustrates how this can be accomplished: | ||
| Line 25: | Line 25: | ||
</pre> | </pre> | ||
<var>Stringlist</var>s should always be used in preference to $lists, so MoveToId is provided only for the migration of existing $list applications to the use of <var>Stringlist</var>s. | <var>Stringlist</var>s 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>Stringlist</var>s. | ||
</ul> | </ul> | ||
[[Category:Stringlist methods|MoveTold subroutine]] | [[Category:Stringlist methods|MoveTold subroutine]] | ||
Revision as of 16:12, 19 January 2011
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. For more information about $list identifiers, see the Sirius Functions Reference Manual.
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 the MoveToId method is invoked, the method Stringlist is empty, though the object variable is still valid (non-null).
- MoveToId discards the original contents of the target $list.
- The MoveToId method copies to the target $list any image association that is set via BindImage.
- MoveToId simply moves the pointers to the Stringlist data 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. For example, 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
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.