View source for Update (Stringlist function)

{{Template:Stringlist:Update subtitle}}

This method uses an input <var>Stringlist</var> to update the method <var>Stringlist</var>, producing an output <var>Stringlist</var> that contains data from the method <var>Stringlist</var> as modified by the first argument <var>Stringlist</var>. The <var>Update</var> method accepts two arguments and returns a <var>Stringlist</var>. The method <var>Stringlist</var> must contain items with 8-byte sequence numbers.

==Syntax==
{{Template:Stringlist:Update syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%outList</th>
<td>The output <var>Stringlist</var>.</td></tr>
<tr><th>sl</th>
<td>A <var>Stringlist</var> object that must contain items with 8-byte sequence numbers.</td></tr>
<tr><th>updList</th>
<td>A <var>Stringlist</var> that contains update control statements and insertion or replacement lines.</td></tr>
<tr><th>%status</th>
<td>A numeric variable that is set to 0 if the method is successful, or it is set to the item number of the invalid update command if <var class="term">updList</var> contains an invalid item. This is an optional output argument.</td></tr>
</table>

==Usage notes==
<ul>
<li>All errors in <var>Update</var> other than an invalid update item cause request cancellation.
<li>The output <var>Stringlist</var> produced by <var>Update</var> contains sequence numbers just as the input <var>Stringlist</var> in the first argument. This makes it possible to use the output <var>Stringlist</var> as input to subsequent <var>Update</var> call. In this way it is possible to apply multiple updates to a single <var>Stringlist</var>.
<li>The method <var>Stringlist</var> for <var>Update</var> can be most easily created with <var>[[AppendOpenProcedure (Stringlist function)|AppendOpenProcedure]]</var> using its fourth parameter to indicate a sequence number. The input argument <var>Stringlist</var> to <var>Update</var> can be most easily created with <var>[[Compare (Stringlist function)|Compare]]</var>.
<li>The update <var>Stringlist</var> contains update control statements and insertion or replacement lines. The update <var>Stringlist</var> must begin with an update control statement. All update control statements begin with the period-slash character sequence (<code>./</code>); this is followed by a single character indicating the function, and then possibly by sequence numbers indicating the lines in the input <var>Stringlist</var> to which the updates apply. Any items in the method <var>Stringlist</var> that are not updated by the update <var>Stringlist</var> are simply copied into the output <var>Stringlist</var>. 
<p>
The update control statements are:</p>
<table>
<tr><th>./ * comment</th>
<td>This is a comment control statement and it is ignored. It must be followed by another update control statement, or it must be the last item in the update <var>Stringlist</var>.</td></tr>

<tr><th>./ D <var class="term">seq1</var> { <var class="term">seq2</var> } { $ }</th>
<td>This is a deletion control statement that indicates a range of input lines to be deleted. <var class="term">seq1</var> and <var class="term">seq2</var> indicate the range of sequence numbers in the method <var>Stringlist</var> that are to be deleted. If <var class="term">seq2</var> is not specified, it is assumed to equal <var class="term">seq1</var>, so only the single line indicated by <var class="term">seq1</var> will be deleted. This statement must be followed by another update control statement, or it must be the last item in the update <var>Stringlist</var>.</td></tr>

<tr><th>./ I <var class="term">seq1</var> { $ <var class="term">seq2</var> { <var class="term">seq3</var> } }</th>
<td>This is an insertion control statement, and it is followed by lines that are to be inserted in the output <var>Stringlist</var>. <var class="term">seq1</var> indicates the sequence number in the method <var>Stringlist</var> after which the lines are to be inserted. <var class="term">seq2</var> is the sequence number to be assigned to the first inserted line, and <var class="term">seq3</var> indicates the increment to be added to the current sequence number for subsequent inserted lines. The lines to be inserted are terminated by another update control statement.</td></tr>

<tr><th nowrap>./ R <var class="term">seq1</var> {<var class="term">seq2</var>} { $ <var class="term">seq3</var> { <var class="term">seq4</var> } }</th>
<td>This is a replacement control statement, and it is followed by lines that are to replace lines from the method <var>Stringlist</var> in the output <var>Stringlist</var>. <var class="term">seq1</var> and <var class="term">seq2</var> indicate the range of sequence numbers in the input <var>Stringlist</var> that are to be replaced. If <var class="term">seq2</var> is not specified, it is assumed to equal <var class="term">seq1</var>, so only the single line indicated by <var class="term">seq1</var> will be replaced. <var class="term">seq3</var> is the sequence number to be assigned to the first replacement line, and <var class="term">seq4</var> indicates the increment to be added to the current sequence number for subsequent replacement lines. The replacement lines are terminated by another update control statement.</td></tr>

<tr><th>./ S <var class="term">seq1</var> { <var class="term">seq2</var> } { $ }</th>
<td>This is a resequence control statement, and it must be the first non-comment control statement in the update <var>Stringlist</var>. This statement indicates that the output <var>Stringlist</var>, after all subsequent updates have been applied, is to be given sequence numbers starting at <var class="term">seq1</var> and incremented by <var class="term">seq2</var>.</td></tr>
</table>
</ul>

==See also==
{{Template:Stringlist:Update footer}}