Overlay (Stringlist function): Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
m (1 revision) |
||
| (12 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Stringlist:Overlay subtitle}} | {{Template:Stringlist:Overlay subtitle}} | ||
This callable method is used to overlay a <var> | This [[Notation conventions for methods#Callable functions|callable]] method is used to overlay a <var>stringlist</var> item with a string. <var>Overlay</var> returns an integer that indicates whether or not the operation was successful. | ||
==Syntax== | ==Syntax== | ||
| Line 11: | Line 11: | ||
<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> | <tr><th>itemNum</th> | ||
<td>The number of the item that is to be updated. </td></tr> | <td>The number of the item that is to be updated. </td></tr> | ||
<tr><th> | <tr><th>startCol</th> | ||
<td>The column number | <td>The starting column number from which data is to be overlayed in the method <var>Stringlist</var> item. If this argument is not specified, data is overlayed starting at the first character in the <var>Stringlist</var> item.</td></tr> | ||
<tr><th>string</th> | <tr><th>string</th> | ||
<td>The string that is to overlay the current contents of the <var> | <td>The string that is to overlay the current contents of the <var>stringlist</var> item indicated by <var class="term">itemNum</var>. This is a required argument, and it must not be more than 255 bytes.</td></tr> | ||
</table> | </table> | ||
==Usage notes== | ==Usage notes== | ||
<ul> | <ul><li>All errors in <var>overlay</var> result in request cancellation.<li>An <var>Overlay</var> invocation does not change the length of a <var>stringlist</var> item. If the overlay string does not completely overlay a <var>stringlist</var> item, those characters in the original <var>stringlist</var> after the overlay string remain unchanged.</ul> | ||
<li>All errors in <var> | |||
<li>An <var>Overlay</var> invocation does not change the length of a <var> | ==Examples== | ||
For example, if this is the original <var> | <ol><li>For example, if this is the original <var>stringlist</var> item: | ||
<p class="code">'It was the best of times, it was the first time' | <p class="code">'It was the best of times, it was the first time' | ||
</p> | </p> | ||
And if this is the | And if this is the <var>overLay</var> invocation: | ||
<p class="code">%rc = %list:overlay(%item, 38, 'worst') | <p class="code">%rc = %list:overlay(%item, 38, 'worst') | ||
</p> | </p> | ||
< | <var class="term">%rc</var> is set to <code>1</code> to indicate that no truncation occurred, and the <var>stringlist</var> item is set to this: | ||
<p class="code">'It was the best of times, it was the worst time' | <p class="code">'It was the best of times, it was the worst time' | ||
</p> | </p> | ||
If the start column plus the length of the overlay string is greater than the current length of the <var> | <li>If the start column plus the length of the overlay string is greater than the current length of the <var>stringlist</var> item, the overlay string is truncated. For example, if this is the original <var>stringlist</var> item: | ||
<p class="code">'Tis a far better thing I do than you ever did' | <p class="code">'Tis a far better thing I do than you ever did' | ||
</p> | </p> | ||
And if this is the | And if this is the <var>overLay</var> invocation: | ||
<p class="code">%rc = %list:overlay(%item, 39, - | <p class="code">%rc = %list:overlay(%item, 39, - | ||
'I have ever done before') | 'I have ever done before') | ||
</p> | </p> | ||
< | <var class="term">%rc</var> is set to 0 to indicate that the overlay string is truncated, and the <var>stringlist</var> item is set to this: | ||
<p class="code">'Tis a far better thing I do than I have ever ' | <p class="code">'Tis a far better thing I do than I have ever ' | ||
</p> | </p></ol> | ||
</ | |||
==See also== | ==See also== | ||
{{Template:Stringlist:Overlay footer}} | {{Template:Stringlist:Overlay footer}} | ||
Latest revision as of 19:40, 14 July 2011
Overlay part of Stringlist item with string (Stringlist class)
This callable method is used to overlay a stringlist item with a string. Overlay returns an integer that indicates whether or not the operation was successful.
Syntax
[%rc =] sl:Overlay( itemNum, [startCol], string)
Syntax terms
| %rc | A numeric variable that is set to 1 if the string is overlayed without truncation, and it is set to 0 if it is overlayed with truncation. |
|---|---|
| sl | A Stringlist object. |
| itemNum | The number of the item that is to be updated. |
| startCol | The starting column number from which data is to be overlayed in the method Stringlist item. If this argument is not specified, data is overlayed starting at the first character in the Stringlist item. |
| string | The string that is to overlay the current contents of the stringlist item indicated by itemNum. This is a required argument, and it must not be more than 255 bytes. |
Usage notes
- All errors in overlay result in request cancellation.
- An Overlay invocation does not change the length of a stringlist item. If the overlay string does not completely overlay a stringlist item, those characters in the original stringlist after the overlay string remain unchanged.
Examples
- For example, if this is the original stringlist item:
'It was the best of times, it was the first time'
And if this is the overLay invocation:
%rc = %list:overlay(%item, 38, 'worst')
%rc is set to
1to indicate that no truncation occurred, and the stringlist item is set to this:'It was the best of times, it was the worst time'
- If the start column plus the length of the overlay string is greater than the current length of the stringlist item, the overlay string is truncated. For example, if this is the original stringlist item:
'Tis a far better thing I do than you ever did'
And if this is the overLay invocation:
%rc = %list:overlay(%item, 39, - 'I have ever done before')
%rc is set to 0 to indicate that the overlay string is truncated, and the stringlist item is set to this:
'Tis a far better thing I do than I have ever '