Overlay (Stringlist function): Difference between revisions
m (more consistent layout and better tagging) |
m (review and some tags) |
||
| Line 14: | Line 14: | ||
<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>startCol</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>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> | <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> | ||
| Line 33: | Line 33: | ||
</p> | </p> | ||
<var class="term">%rc</var> is set to 1 to indicate that no truncation occurred, and the <var>stringlist</var> item is set to this: | <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' | ||
Revision as of 08:42, 29 January 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 '