Copy (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(9 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Template:Stringlist:Copy subtitle}}
{{Template:Stringlist:Copy subtitle}}


This method copies an entire <var>Stringlist</var>, creating a new <var>Stringlist</var>. The <var>Copy</var> method accepts no argument and returns a <var>Stringlist</var> object.  If you are new to object-oriented programming or the Janus APIs you should read about [[Copying objects]].
This method copies an entire <var>Stringlist</var>, creating a new <var>Stringlist</var>. The <var>Copy</var> method accepts no arguments and returns a <var>Stringlist</var> object.  If you are new to object-oriented programming or the Janus APIs, you should read [[Copying objects|"Copying objects"]].


==Syntax==
==Syntax==
{{Template:Stringlist:Copy syntax}}
{{Template:Stringlist:Copy syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%outlist</th>
<tr><th>%outList</th>
<td>A <var>Stringlist</var> to contain the copy of the method <var>Stringlist</var> '''%sl'''</td></tr>
<td>A <var>Stringlist</var> to contain the copy of the method <var>Stringlist</var> <var class="term">sl</var>.</td></tr>
 
<tr><th>sl</th>
<tr><th>sl</th>
<td>A <var>Stringlist</var> object.</td></tr>
<td>A <var>Stringlist</var> object, which may be <var>Null</var>.</td></tr>
</table>
</table>


Line 16: Line 18:
<ul>
<ul>
<li>All errors in <var>Copy</var> result in request cancellation.
<li>All errors in <var>Copy</var> result in request cancellation.
<li>If the method <var>Stringlist</var> was associated with an image, by either the BindImage or New method, the output <var>Stringlist</var> is associated with the same image, as if a BindImage method had been invoked on the result of the <var>Copy</var> method.<li><var>Copy</var> does a page-for-page copy of the input <var>Stringlist</var>. As such, it is very efficient (more efficient than <var>Copy</var>Items), but it is also useless for compressing a <var>Stringlist</var> that has become sparse as the result of heavy Insert, Replace, ChangeItemLength, and RemoveItem activity. Replace and ChangeItemLength cause a <var>Stringlist</var> to become sparse only if <var>Stringlist</var> items are replaced with larger <var>Stringlist</var> items or increased in size. For list compression, use [[CopyItems (Stringlist function)]].
<li>If the method <var>Stringlist</var> was associated with an image, by either <var>[[BindImage (Stringlist subroutine)|BindImage]]</var> or <var>[[New (Stringlist constructor)|New]]</var>, the output <var>Stringlist</var> is associated with the same image, as if a <var>BindImage</var> method had been transparently invoked on the result of the <var>Copy</var>.
 
<li><var>Copy</var> does a page-for-page copy of the input <var>Stringlist</var>. As such, it is very efficient (much more efficient than <var>[[CopyItems (Stringlist function)|CopyItems]]</var>).  However, it is unsuitable for compressing a <var>Stringlist</var> that has become sparse as the result of heavy <var>[[Insert_(Stringlist_function)|Insert]]</var>, <var>[[Replace_(Stringlist_function)|Replace]]</var>, <var>[[ChangeItemLength_(Stringlist_function)|ChangeItemLength]]</var> or <var>[[RemoveItem_(Stringlist_function)|RemoveItem]]</var> activity. <var>Replace</var> or <var>ChangeItemLength</var> may cause a <var>Stringlist</var> to become sparse only if <var>Stringlist</var> items are replaced with larger <var>Stringlist</var> items or increased in size.
 
<li>For list compression, or to append items from one <var>Stringlist</var> to another, use <var>CopyItems</var>.
</ul>
</ul>


[[Category:Stringlist methods|Copy function]]
==See also==
{{Template:Stringlist:Copy footer}}

Latest revision as of 15:16, 31 October 2012

Copy Stringlist (Stringlist class)


This method copies an entire Stringlist, creating a new Stringlist. The Copy method accepts no arguments and returns a Stringlist object. If you are new to object-oriented programming or the Janus APIs, you should read "Copying objects".

Syntax

%outList = sl:Copy

Syntax terms

%outList A Stringlist to contain the copy of the method Stringlist sl.
sl A Stringlist object, which may be Null.

Usage notes

  • All errors in Copy result in request cancellation.
  • If the method Stringlist was associated with an image, by either BindImage or New, the output Stringlist is associated with the same image, as if a BindImage method had been transparently invoked on the result of the Copy.
  • Copy does a page-for-page copy of the input Stringlist. As such, it is very efficient (much more efficient than CopyItems). However, it is unsuitable for compressing a Stringlist that has become sparse as the result of heavy Insert, Replace, ChangeItemLength or RemoveItem activity. Replace or ChangeItemLength may cause a Stringlist to become sparse only if Stringlist items are replaced with larger Stringlist items or increased in size.
  • For list compression, or to append items from one Stringlist to another, use CopyItems.

See also