Insert (Stringlist function) - Revision history

JAL at 15:34, 31 October 2012

2012-10-31T15:34:57Z

← Older revision		Revision as of 15:34, 31 October 2012
Line 5:		Line 5:
	==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>.
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>

	===Inserting 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 inserted into 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>:

JAL2: /* Syntax terms */

2012-07-20T21:01:20Z

Syntax terms

← Older revision		Revision as of 21:01, 20 July 2012
Line 14:		Line 14:
	<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>

JALWiccan: 1 revision

2011-07-14T19:40:24Z

1 revision

← Older revision	Revision as of 19:40, 14 July 2011
(No difference)

Alex: /* Adding multiple items to a Stringlist */

2011-07-14T19:40:22Z

Adding multiple items to a Stringlist

← Older revision		Revision as of 19:40, 14 July 2011
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==

Alex: /* Adding multiple items to a Stringlist */

2011-03-14T03:26:52Z

Adding multiple items to a Stringlist

← Older revision		Revision as of 03:26, 14 March 2011
Line 37:		Line 37:
	</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 49:
	%python = 'Graham'		%python = 'Graham'

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

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

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

Alex: /* Inserting a single item to a Stringlist */

2011-03-14T03:25:04Z

Inserting a single item to a Stringlist

← Older revision		Revision as of 03:25, 14 March 2011
Line 26:		Line 26:

	===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 33:		Line 33:
	%data = ssn with ',' with lname with ',' -		%data = ssn with ',' with lname with ',' -
	fname with ',' with mi		fname with ',' with mi
	%list:insert(1,%data)		%list:insert(1, %data)
	end for		end for
	</p>		</p>

Alex: /* Adding a single item to a Stringlist */

2011-03-14T03:24:35Z

Adding a single item to a Stringlist

← Older revision		Revision as of 03:24, 14 March 2011
Line 25:		Line 25:
	==Examples==		==Examples==

	===~~Adding~~ a single item to a Stringlist===		===Inserting a single item to a Stringlist===
	In the following example, four comma-delimited field values are ~~added to~~ 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 33:		Line 33:
	%data = ssn with ',' with lname with ',' -		%data = ssn with ',' with lname with ',' -
	fname with ',' with mi		fname with ',' with mi
	%list:~~add~~(%data)		%list:insert(1,%data)
	end for		end for
	</p>		</p>

Alex: /* Usage notes */

2011-03-14T03:23:17Z

Usage notes

@@ Line 23: / Line 23: @@
 <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>
 ==See also==
 {{Template:Stringlist:Insert footer}}

Alex at 03:22, 14 March 2011

2011-03-14T03:22:24Z

← Older revision		Revision as of 03:22, 14 March 2011
Line 1:		Line 1:
	{{Template:Stringlist:Insert subtitle}}		{{Template:Stringlist:Insert subtitle}}

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

	==Syntax==		==Syntax==
Line 8:		Line 8:
	<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 ~~string has~~ 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 ~~string is~~ to be inserted. If <var class="term">itemNum</var> is equal to the number of items in the <var>Stringlist</var> plus one, ~~<var class="term">string</var> is~~ added to the end of the <var>Stringlist</var> (the same effect as an <var>[[Add (Stringlist function)\|Add]]</var> invocation). Because the ~~string is~~ inserted before the indicated item number, <var class="term">itemNum</var> is also the item number of the 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>~~string~~</th>		<tr><th>itemList</th>
	<td>A <var class="~~term~~">~~string~~</var> ~~that~~ is to be inserted into the <var class="term">sl</var> <var>Stringlist</var>.</td></tr>		<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>
	</table>		</table>

Line 20:		Line 22:
	<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>Before <var class="product">Sirius Mods</var> Version 6.6, it was a request canceling error to try to insert a string longer than the size limit of a <var>Stringlist</var> item: 6124 bytes. This limitation was eliminated in <var class="product">Sirius Mods</var> Version 6.6.
	<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 (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>

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

JAL at 02:05, 9 March 2011

2011-03-09T02:05:10Z

← Older revision		Revision as of 02:05, 9 March 2011
Line 1:		Line 1:
	{{Template:Stringlist:Insert subtitle}}		{{Template:Stringlist:Insert subtitle}}

	This callable method inserts a string into a <var>Stringlist</var> at a specific location.		This [[Notation conventions for methods#Callable methods\|callable]] method inserts a string into a <var>Stringlist</var> at a specific location.

	==Syntax==		==Syntax==