Insert (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:Stringlist:Insert subtitle}}
{{Template:Stringlist:Insert subtitle}}


This [[Notation conventions for methods#Callable methods|callable]] method inserts one or more strings into a <var>Stringlist</var> at a specific location.
This [[Notation conventions for methods#Callable functions|callable]] method inserts one or more strings into a <var>Stringlist</var> at a specific location.


==Syntax==
==Syntax==
{{Template:Stringlist:Insert syntax}}
{{Template:Stringlist:Insert syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%count</th>
<tr><th>%count</th>
<td>A numeric variable to contain the number of items in <var class="term">sl</var> after the strings have been inserted. </td></tr>
<td>A numeric variable to contain the number of items in <var class="term">sl</var> after the strings have been inserted. </td></tr>
<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>itemNum</th>
<tr><th>itemNum</th>
<td>The item number before which the strings are to be inserted. If <var class="term">itemNum</var> is equal to the number of items in the <var>Stringlist</var> plus one, the strings are added to the end of the <var>Stringlist</var> (the same effect as an <var>[[Add (Stringlist function)|Add]]</var> invocation). Because the strings are inserted before the indicated item number, <var class="term">itemNum</var> is also the item number of the first new <var>Stringlist</var> item after <var>Insert</var> returns. </td></tr>
<td>The item number before which the strings are to be inserted. If <var class="term">itemNum</var> is equal to the number of items in the <var>Stringlist</var> plus one, the strings are added to the end of the <var>Stringlist</var> (the same effect as an <var>[[Add (Stringlist function)|Add]]</var> invocation). Because the strings are inserted before the indicated item number, <var class="term">itemNum</var> is also the item number of the first new <var>Stringlist</var> item after <var>Insert</var> returns. </td></tr>
<tr><th>itemList</th>
<tr><th>itemList</th>
<td>Under <var class="product">Sirius Mods</var> 7.9 and later, this is a comma-delimited set of strings, each of which, from left to right, is inserted into the method object <var>Stringlist</var>. The items in the list could themselves be <var>Stringlists</var>, in which case each item in the input <var>Stringlist</var> is inserted into the target<var>Stringlist</var>.
<td>Under <var class="product">Sirius Mods</var> 7.9 and later, this is a comma-delimited set of strings, each of which, from left to right, is inserted into the method object <var>Stringlist</var>. The items in the list could themselves be <var>Stringlists</var>, in which case each item in the input <var>Stringlist</var> is inserted into the target <var>Stringlist</var>.


Under <var class="product">Sirius Mods</var> 7.8 and earlier, <var class="term">itemList</var> could only be a single string that is to be inserted into the <var>Stringlist</var>.</td></tr>
Under <var class="product">Sirius Mods</var> 7.8 and earlier, <var class="term">itemList</var> could only be a single string that is to be inserted into the <var>Stringlist</var>.</td></tr>
Line 22: Line 26:
<ul>
<ul>
<li>All errors in <var>Insert</var> result in request cancellation.
<li>All errors in <var>Insert</var> result in request cancellation.
<li>An <var>Insert</var> can result in the splitting of a <var>stringlist</var> leaf page. Once a leaf page is split, it will not be merged back together again, even if subsequent <var>[[RemoveItem (Stringlist function)|RemoveItem]]</var> invocations make this possible. Because of this splitting, heavy use of <var>Insert</var> and <var>[[RemoveItem (Stringlist function)|RemoveItem]]</var> can result in "sparse" <var>stringlists</var> which place an unnecessary burden on the buffer pool and CCATEMP. To make matters worse, <var>[[Copy (Stringlist function)|Copy]]</var> does a page-for-page copy of a <var>stringlist</var>, so it does not result in any compression of the resultant <var>stringlist</var>. <var>stringlist</var> compression can be achieved using the <var>[[CopyItems (Stringlist function)|CopyItems]]</var>.</ul>
 
<li>An <var>Insert</var> can result in the splitting of a <var>stringlist</var> leaf page. Once a leaf page is split, it will not be merged back together again, even if subsequent <var>[[RemoveItem (Stringlist function)|RemoveItem]]</var> invocations make this possible. Because of this splitting, heavy use of <var>Insert</var> and <var>RemoveItem</var> can result in "sparse" <var>stringlists</var> which place an unnecessary burden on the buffer pool and CCATEMP. To make matters worse, <var>[[Copy (Stringlist function)|Copy]]</var> does a page-for-page copy of a <var>stringlist</var>, so it does not result in any compression of the resultant <var>stringlist</var>. <var>stringlist</var> compression can be achieved using the <var>[[CopyItems (Stringlist function)|CopyItems]]</var>.</ul>
 
==Examples==
==Examples==


===Inserting a single item to a Stringlist===
====Inserting a single item to a Stringlist====
In the following example, four comma-delimited field values are inserted into the start of a <var>Stringlist</var> for each record in a <var>Recordset</var>:
In the following example, four comma-delimited field values are inserted into the start of a <var>Stringlist</var> for each record in a <var>Recordset</var>:
<p class="code">%list is object stringList
<p class="code">%list is object stringList
Line 37: Line 43:
</p>
</p>


===Adding multiple items to a Stringlist===
====Inserting multiple items to a Stringlist====


In the following example, a string literal, the contents of a variable, and the contents of another<var>Stringlist</var> are added to a <var>Stringlist</var>:
In the following example, a string literal, the contents of a variable, and the contents of another<var>Stringlist</var> are inserted into a <var>Stringlist</var>:
<p class="code">b
<p class="code">b
%sl      is object stringlist
%sl      is object stringlist
Line 49: Line 55:
%python = 'Graham'
%python = 'Graham'


%sl:add('Terry', %python, %stooges)
%sl:insert(3, 'Terry', %python, %stooges)


%sl:print
%sl:print
Line 59: Line 65:
<p class="output">John
<p class="output">John
Michael
Michael
Eric
Terry
Terry
Graham
Graham
Line 65: Line 70:
Larry
Larry
Curly
Curly
Eric
</p>
</p>


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

Latest revision as of 15:34, 31 October 2012

Insert strings into a Stringlist (Stringlist class)


This callable method inserts one or more strings into a Stringlist at a specific location.

Syntax

[%count =] sl:Insert( itemNum, itemList)

Syntax terms

%count A numeric variable to contain the number of items in sl after the strings have been inserted.
sl A Stringlist object.
itemNum The item number before which the strings are to be inserted. If itemNum is equal to the number of items in the Stringlist plus one, the strings are added to the end of the Stringlist (the same effect as an Add invocation). Because the strings are inserted before the indicated item number, itemNum is also the item number of the first new Stringlist item after Insert returns.
itemList Under Sirius Mods 7.9 and later, this is a comma-delimited set of strings, each of which, from left to right, is inserted into the method object Stringlist. The items in the list could themselves be Stringlists, in which case each item in the input Stringlist is inserted into the target Stringlist. Under Sirius Mods 7.8 and earlier, itemList could only be a single string that is to be inserted into the Stringlist.

Usage notes

  • All errors in Insert result in request cancellation.
  • An Insert can result in the splitting of a stringlist leaf page. Once a leaf page is split, it will not be merged back together again, even if subsequent RemoveItem invocations make this possible. Because of this splitting, heavy use of Insert and RemoveItem can result in "sparse" stringlists which place an unnecessary burden on the buffer pool and CCATEMP. To make matters worse, Copy does a page-for-page copy of a stringlist, so it does not result in any compression of the resultant stringlist. stringlist compression can be achieved using the CopyItems.

Examples

Inserting a single item to a Stringlist

In the following example, four comma-delimited field values are inserted into the start of a Stringlist for each record in a Recordset:

%list is object stringList ... %list = new for each record in %recset %data = ssn with ',' with lname with ',' - fname with ',' with mi %list:insert(1, %data) end for

Inserting multiple items to a Stringlist

In the following example, a string literal, the contents of a variable, and the contents of anotherStringlist are inserted into a Stringlist:

b %sl is object stringlist %python is string len 32 %stooges is object stringlist %stooges = list('Moe', 'Larry', 'Curly') %sl = list('John', 'Michael', 'Eric') %python = 'Graham' %sl:insert(3, 'Terry', %python, %stooges) %sl:print end

This outputs:

John Michael Terry Graham Moe Larry Curly Eric

See also