ChangeItemLength (Stringlist function) - Revision history

JAL at 16:38, 3 September 2014

2014-09-03T16:38:59Z

← Older revision		Revision as of 16:38, 3 September 2014
Line 1:		Line 1:
	{{Template:Stringlist:ChangeItemLength subtitle}}		{{Template:Stringlist:ChangeItemLength subtitle}}

	This [[Notation conventions for methods#Callable functions\|callable]] method changes the length of a <var>Stringlist</var> item. <var>ChangeItemLength</var> is provided mainly for compatibility with <var>[[$ListAdj]]</var> in the ~~<var>~~[[$list]]~~</var>~~ API. Except when migrating existing applications that use $lists to use <var>Stringlists</var>, it is probably best to avoid using <var>ChangeItemLength</var>.		This [[Notation conventions for methods#Callable functions\|callable]] method changes the length of a <var>Stringlist</var> item. <var>ChangeItemLength</var> is provided mainly for compatibility with <var>[[$ListAdj]]</var> in the [[$lists\|$list]] API. Except when migrating existing applications that use $lists to use <var>Stringlists</var>, it is probably best to avoid using <var>ChangeItemLength</var>.

	==Syntax==		==Syntax==

JAL at 22:29, 30 October 2012

2012-10-30T22:29:48Z

← Older revision		Revision as of 22:29, 30 October 2012
Line 1:		Line 1:
	{{Template:Stringlist:ChangeItemLength subtitle}}		{{Template:Stringlist:ChangeItemLength subtitle}}

	This [[Notation conventions for methods#Callable functions\|callable]] method changes the length of a <var>Stringlist</var> item. <var>ChangeItemLength</var> is provided mainly for compatibility with <var>[[$ListAdj]]</var> in the <var>[[$list]]</var> API ~~(described in the <var class="product">[["Sirius Functions Reference Manual"]]</var>)~~. Except when migrating existing applications that use ~~<var>[[~~$lists~~]]</var>~~ to use <var>Stringlists</var>, it is probably best to avoid ~~use of~~ <var>ChangeItemLength</var>.		This [[Notation conventions for methods#Callable functions\|callable]] method changes the length of a <var>Stringlist</var> item. <var>ChangeItemLength</var> is provided mainly for compatibility with <var>[[$ListAdj]]</var> in the <var>[[$list]]</var> API. Except when migrating existing applications that use $lists to use <var>Stringlists</var>, it is probably best to avoid using <var>ChangeItemLength</var>.

	==Syntax==		==Syntax==
	{{Template:Stringlist:ChangeItemLength syntax}}		{{Template:Stringlist:ChangeItemLength syntax}}

	===Syntax terms===		===Syntax terms===
	<table class="syntaxTable">		<table class="syntaxTable">
Line 18:		Line 19:

	==Usage notes==		==Usage notes==
	<ul><li>All errors in <var>ChangeItemLength</var> result in request cancellation.		<ul>
	<li><var>ChangeItemLength</var> is extremely efficient if the <var>Stringlist</var> item size is not being changed (return value for <var>ChangeItemLength</var> of 0), fairly efficient when a <var>Stringlist</var> item is being shortened (return value of 1), and can be fairly expensive when a <var>Stringlist</var> item is being lengthened (return value of 2). Increasing the length of a <var>Stringlist</var> item can be expensive, because such a <var>ChangeItemLength</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, even if subsequent <var>[[RemoveItem (Stringlist function)\|RemoveItem]]</var> (or <var>ChangeItemLength</var>) make this possible. Because of this splitting, heavy use of <var>ChangeItemLength</var> invocations (and <var>[[Insert (Stringlist function)\|Insert]]</var> and <var>[[RemoveItem (Stringlist function)\|RemoveItem]]</var>) that increase <var>Stringlist</var> item size has two potentially adverse consequences:<ul><li>It can result in "sparse" <var>Stringlist</var>s which place an unnecessary burden on the buffer pool and CCATEMP.		<li>All errors in <var>ChangeItemLength</var> result in request cancellation.
	<li>It can also result in an inability to add an item to the end of the <var>Stringlist</var> (via <var>[[Add (Stringlist function)\|Add]]</var>) because of a full pointer page, even though the <var>Stringlist</var> is nowhere near the theoretical capacity for a <var>Stringlist</var>.</ul>
	<li><var>Stringlist</var> compression can be achieved using the <var>[[CopyItems (Stringlist function)\|CopyItems]]</var>.</ul>		<li><var>ChangeItemLength</var> is extremely efficient if the <var>Stringlist</var> item size is not being changed (return value for <var>ChangeItemLength</var> of 0), fairly efficient when a <var>Stringlist</var> item is being shortened (return value of 1), and can be fairly expensive when a <var>Stringlist</var> item is being lengthened (return value of 2).
			<p>
			Increasing the length of a <var>Stringlist</var> item can be expensive, because such a <var>ChangeItemLength</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, even if subsequent <var>[[RemoveItem (Stringlist function)\|RemoveItem]]</var> (or <var>ChangeItemLength</var>) make this possible. Because of this splitting, heavy use of <var>ChangeItemLength</var> invocations (and <var>[[Insert (Stringlist function)\|Insert]]</var> and <var>[[RemoveItem (Stringlist function)\|RemoveItem]]</var>) that increase <var>Stringlist</var> item size has two potentially adverse consequences:</p>
			<ul>
			<li>It can result in "sparse" <var>Stringlist</var>s which place an unnecessary burden on the buffer pool and CCATEMP.

			<li>It can also result in an inability to add an item to the end of the <var>Stringlist</var> (via <var>[[Add (Stringlist function)\|Add]]</var>) because of a full pointer page, even though the <var>Stringlist</var> is nowhere near the theoretical capacity for a <var>Stringlist</var>.
			</ul>

			<li><var>Stringlist</var> compression can be achieved using the <var>[[CopyItems (Stringlist function)\|CopyItems]]</var>.
			</ul>

	==Examples==		==Examples==
	~~<ol><li>~~The following example illustrates how <var>ChangeItemLength</var> (and Overlay) can be used to add an asterisk to the end of a <var>Stringlist</var> item.		The following example illustrates how <var>ChangeItemLength</var> (and Overlay) can be used to add an asterisk to the end of a <var>Stringlist</var> item.
	<p class="code">%len = %list:ItemLength(%num)		<p class="code">%len = %list:ItemLength(%num)
	%list:ChangeItemLength(%num, %len + 1)		%list:ChangeItemLength(%num, %len + 1)
Line 30:		Line 41:
	</p>		</p>

	Of course, this same end can be accomplished with the <var>[[Item (Stringlist function)\|Item]]</var> and <var>[[Replace (Stringlist function)\|Replace]]</var>.~~</ol>~~		Of course, this same end can be accomplished with the <var>[[Item (Stringlist function)\|Item]]</var> and <var>[[Replace (Stringlist function)\|Replace]]</var>.

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

JALWiccan: 1 revision

2011-07-14T19:40:24Z

1 revision

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

JAL at 19:40, 14 July 2011

2011-07-14T19:40:22Z

← Older revision		Revision as of 19:40, 14 July 2011
Line 1:		Line 1:
	{{Template:Stringlist:ChangeItemLength subtitle}}		{{Template:Stringlist:ChangeItemLength subtitle}}

	This [[Notation conventions for methods#Callable ~~methods~~\|callable]] method changes the length of a <var>Stringlist</var> item. <var>ChangeItemLength</var> is provided mainly for compatibility with <var>[[$ListAdj]]</var> in the <var>[[$list]]</var> API (described in the <var class="product">[["Sirius Functions Reference Manual"]]</var>). Except when migrating existing applications that use <var>[[$lists]]</var> to use <var>Stringlists</var>, it is probably best to avoid use of <var>ChangeItemLength</var>.		This [[Notation conventions for methods#Callable functions\|callable]] method changes the length of a <var>Stringlist</var> item. <var>ChangeItemLength</var> is provided mainly for compatibility with <var>[[$ListAdj]]</var> in the <var>[[$list]]</var> API (described in the <var class="product">[["Sirius Functions Reference Manual"]]</var>). Except when migrating existing applications that use <var>[[$lists]]</var> to use <var>Stringlists</var>, it is probably best to avoid use of <var>ChangeItemLength</var>.

	==Syntax==		==Syntax==

JAL at 00:44, 9 March 2011

2011-03-09T00:44:47Z

← Older revision		Revision as of 00:44, 9 March 2011
Line 1:		Line 1:
	{{Template:Stringlist:ChangeItemLength subtitle}}		{{Template:Stringlist:ChangeItemLength subtitle}}

	This callable method changes the length of a <var>Stringlist</var> item. <var>ChangeItemLength</var> is provided mainly for compatibility with <var>[[$ListAdj]]</var> in the <var>[[$list]]</var> API (described in the <var class="product">[["Sirius Functions Reference Manual"]]</var>). Except when migrating existing applications that use <var>[[$lists]]</var> to use <var>Stringlists</var>, it is probably best to avoid use of <var>ChangeItemLength</var>.		This [[Notation conventions for methods#Callable methods\|callable]] method changes the length of a <var>Stringlist</var> item. <var>ChangeItemLength</var> is provided mainly for compatibility with <var>[[$ListAdj]]</var> in the <var>[[$list]]</var> API (described in the <var class="product">[["Sirius Functions Reference Manual"]]</var>). Except when migrating existing applications that use <var>[[$lists]]</var> to use <var>Stringlists</var>, it is probably best to avoid use of <var>ChangeItemLength</var>.

	==Syntax==		==Syntax==

Goff: more consistent layout and better tagging

2011-01-29T00:34:47Z

more consistent layout and better tagging

← Older revision		Revision as of 00:34, 29 January 2011
Line 1:		Line 1:
	{{Template:Stringlist:ChangeItemLength subtitle}}		{{Template:Stringlist:ChangeItemLength subtitle}}

	This callable method changes the length of a <var>Stringlist</var> item. <var>ChangeItemLength</var> is provided mainly for compatibility with <var>$~~listAdj~~</var> in the <var>$list</var> API (described in the <var class="product">"Sirius Functions Reference Manual"</var>). Except when migrating existing applications that use <var>$lists</var> to use <var>Stringlists</var>, it is probably best to avoid use of <var>ChangeItemLength</var>.		This callable method changes the length of a <var>Stringlist</var> item. <var>ChangeItemLength</var> is provided mainly for compatibility with <var>[[$ListAdj]]</var> in the <var>[[$list]]</var> API (described in the <var class="product">[["Sirius Functions Reference Manual"]]</var>). Except when migrating existing applications that use <var>[[$lists]]</var> to use <var>Stringlists</var>, it is probably best to avoid use of <var>ChangeItemLength</var>.

	==Syntax==		==Syntax==
Line 18:		Line 18:

	==Usage notes==		==Usage notes==
	<ul><li>All errors in <var>ChangeItemLength</var> result in request cancellation.<li><var>ChangeItemLength</var> is extremely efficient if the <var>Stringlist</var> item size is not being changed (return value for <var>ChangeItemLength</var> of 0), fairly efficient when a <var>Stringlist</var> item is being shortened (return value of 1), and can be fairly expensive when a <var>Stringlist</var> item is being lengthened (return value of 2). Increasing the length of a <var>Stringlist</var> item can be expensive, because such a <var>ChangeItemLength</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, even if subsequent <var>[[RemoveItem (Stringlist function)\|RemoveItem]]</var> (or <var>ChangeItemLength</var>) make this possible. Because of this splitting, heavy use of <var>ChangeItemLength</var> invocations (and <var>[[Insert (Stringlist function)\|Insert]]</var> and <var>[[RemoveItem (Stringlist function)\|RemoveItem]]</var>) that increase <var>Stringlist</var> item size has two potentially adverse consequences:<ul><li>It can result in "sparse" <var>Stringlist</var>s which place an unnecessary burden on the buffer pool and CCATEMP.<li>It can also result in an inability to add an item to the end of the <var>Stringlist</var> (via <var>[[Add (Stringlist function)\|Add]]</var>) because of a full pointer page, even though the <var>Stringlist</var> is nowhere near the theoretical capacity for a <var>Stringlist</var>.</ul><li><var>Stringlist</var> compression can be achieved using the <var>[[CopyItems (Stringlist function)\|CopyItems]]</var>.</ul>		<ul><li>All errors in <var>ChangeItemLength</var> result in request cancellation.
			<li><var>ChangeItemLength</var> is extremely efficient if the <var>Stringlist</var> item size is not being changed (return value for <var>ChangeItemLength</var> of 0), fairly efficient when a <var>Stringlist</var> item is being shortened (return value of 1), and can be fairly expensive when a <var>Stringlist</var> item is being lengthened (return value of 2). Increasing the length of a <var>Stringlist</var> item can be expensive, because such a <var>ChangeItemLength</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, even if subsequent <var>[[RemoveItem (Stringlist function)\|RemoveItem]]</var> (or <var>ChangeItemLength</var>) make this possible. Because of this splitting, heavy use of <var>ChangeItemLength</var> invocations (and <var>[[Insert (Stringlist function)\|Insert]]</var> and <var>[[RemoveItem (Stringlist function)\|RemoveItem]]</var>) that increase <var>Stringlist</var> item size has two potentially adverse consequences:<ul><li>It can result in "sparse" <var>Stringlist</var>s which place an unnecessary burden on the buffer pool and CCATEMP.
			<li>It can also result in an inability to add an item to the end of the <var>Stringlist</var> (via <var>[[Add (Stringlist function)\|Add]]</var>) because of a full pointer page, even though the <var>Stringlist</var> is nowhere near the theoretical capacity for a <var>Stringlist</var>.</ul>
			<li><var>Stringlist</var> compression can be achieved using the <var>[[CopyItems (Stringlist function)\|CopyItems]]</var>.</ul>

	==Examples==		==Examples==
	The following example illustrates how <var>ChangeItemLength</var> (and Overlay) can be used to add an asterisk to the end of a <var>Stringlist</var> item.		<ol><li>The following example illustrates how <var>ChangeItemLength</var> (and Overlay) can be used to add an asterisk to the end of a <var>Stringlist</var> item.
	<p class="code">%len = %list:ItemLength(%num)		<p class="code">%len = %list:ItemLength(%num)
	%list:ChangeItemLength(%num, %len + 1)		%list:ChangeItemLength(%num, %len + 1)
Line 27:		Line 30:
	</p>		</p>

	Of course, this same end can be accomplished with the <var>[[Item (Stringlist function)\|Item]]</var> and <var>[[Replace (Stringlist function)\|Replace]]</var>.		Of course, this same end can be accomplished with the <var>[[Item (Stringlist function)\|Item]]</var> and <var>[[Replace (Stringlist function)\|Replace]]</var>.</ol>

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

Goff: no tags in example

2011-01-27T01:10:49Z

no tags in example

← Older revision		Revision as of 01:10, 27 January 2011
Line 23:		Line 23:
	The following example illustrates how <var>ChangeItemLength</var> (and Overlay) can be used to add an asterisk to the end of a <var>Stringlist</var> item.		The following example illustrates how <var>ChangeItemLength</var> (and Overlay) can be used to add an asterisk to the end of a <var>Stringlist</var> item.
	<p class="code">%len = %list:ItemLength(%num)		<p class="code">%len = %list:ItemLength(%num)
	%list:~~<var>~~ChangeItemLength~~</var>~~(%num, %len + 1)		%list:ChangeItemLength(%num, %len + 1)
	%list:Overlay(%num, %len + 1, '*')		%list:Overlay(%num, %len + 1, '*')
	</p>		</p>

Goff: camelCase

2011-01-27T00:06:22Z

camelCase

← Older revision		Revision as of 00:06, 27 January 2011
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>~~itemnum~~</th>		<tr><th>itemNum</th>
	<td>A <var>Stringlist</var> item number.</td></tr>		<td>A <var>Stringlist</var> item number.</td></tr>
	<tr><th>length</th>		<tr><th>length</th>

Wiccan: 1 revision

2011-01-26T18:56:21Z

1 revision

← Older revision	Revision as of 18:56, 26 January 2011
(No difference)

Dme: /* Syntax terms */

2011-01-26T18:56:18Z

Syntax terms

← Older revision		Revision as of 18:56, 26 January 2011
Line 29:		Line 29:
	Of course, this same end can be accomplished with the <var>[[Item (Stringlist function)\|Item]]</var> and <var>[[Replace (Stringlist function)\|Replace]]</var>.		Of course, this same end can be accomplished with the <var>[[Item (Stringlist function)\|Item]]</var> and <var>[[Replace (Stringlist function)\|Replace]]</var>.

	~~[[Category~~:Stringlist ~~methods\|~~ChangeItemLength ~~function]]~~		==See also==
			{{Template:Stringlist:ChangeItemLength footer}}