$List Add Ordered: Difference between revisions
m (1 revision) |
mNo edit summary |
||
| Line 2: | Line 2: | ||
<span class="pageSubtitle"><section begin="desc" />Add an item to an ordered $list<section end="desc" /></span> | <span class="pageSubtitle"><section begin="desc" />Add an item to an ordered $list<section end="desc" /></span> | ||
<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $List_Add_Ordered function is [[ | <p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $List_Add_Ordered function is the [[AddOrdered (Stringlist function)]].</p> | ||
This function adds an item to a (presumably) ordered $list, inserting the item at the proper position to maintain the $list's order. | This function adds an item to a (presumably) ordered $list, inserting the item at the proper position to maintain the $list's order. | ||
$List_Add_Ordered accepts two arguments and returns the item number of the inserted string. It is a callable $function ( | $List_Add_Ordered accepts two arguments and returns the item number of the inserted string. It is a callable $function (see [[Calling Sirius Mods $functions]]). | ||
The first argument is the $list identifier of the $list to which the string is to be added. This is a required argument. | The first argument is the $list identifier of the $list to which the string is to be added. This is a required argument. | ||
The second argument is the string to add to the $list. This is a required argument. | The second argument is the string to add to the $list. This is a required argument. | ||
==Syntax== | ==Syntax== | ||
<p class="syntax"><section begin="syntax" /> [%RC =] $List_Add_Ordered(list, string) | <p class="syntax"><section begin="syntax" /> [%RC =] $List_Add_Ordered(list, string) | ||
| Line 17: | Line 18: | ||
</p> | </p> | ||
<p class="caption">%RC is the item number of the added string.</p> | <p class="caption">%RC is the item number of the added string.</p> | ||
All errors in $List_Add_Ordered result in request cancellation. | All errors in $List_Add_Ordered result in request cancellation. | ||
| Line 23: | Line 23: | ||
$List_Add_Ordered always adds the indicated string even if that string already exists on the $list but the new item is inserted so that the $list is in EBCDIC order. $List_Add_Ordered assumes that the $list is in EBCDIC order so it does a pseudo binary search to locate the correct insertion point. $List_Add_Ordered does not validate that the $list is in order and, it it isn't, the insertion point is unpredictable. | $List_Add_Ordered always adds the indicated string even if that string already exists on the $list but the new item is inserted so that the $list is in EBCDIC order. $List_Add_Ordered assumes that the $list is in EBCDIC order so it does a pseudo binary search to locate the correct insertion point. $List_Add_Ordered does not validate that the $list is in order and, it it isn't, the insertion point is unpredictable. | ||
The following code builds a sorted output $list from an input $list. | |||
<p class="code"> FOR %I FROM 1 TO $ListCnt(%INLIST) | <p class="code"> FOR %I FROM 1 TO $ListCnt(%INLIST) | ||
%STRING = $ListInf(%INLIST, %I) | %STRING = $ListInf(%INLIST, %I) | ||
| Line 30: | Line 30: | ||
END FOR | END FOR | ||
</p> | </p> | ||
While in general it would be more efficient to simply copy and sort (via $ListSort) the input $list such a technique might be useful if the target $list already as a large number of items. | While in general it would be more efficient to simply copy and sort (via $ListSort) the input $list such a technique might be useful if the target $list already as a large number of items. | ||
Because $List_Add_Ordered will insert items into the middle of a $list it will be susceptible to the same page-splitting, sparse $list leaf page issues as $ListIns | Because $List_Add_Ordered will insert items into the middle of a $list it will be susceptible to the same page-splitting, sparse $list leaf page issues as [[$ListIns]]. | ||
This $function is new in Version 6.3.<p> | This $function is new in Version 6.3.<p> | ||
Revision as of 19:11, 10 February 2011
<section begin="desc" />Add an item to an ordered $list<section end="desc" />
Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $List_Add_Ordered function is the AddOrdered (Stringlist function).
This function adds an item to a (presumably) ordered $list, inserting the item at the proper position to maintain the $list's order.
$List_Add_Ordered accepts two arguments and returns the item number of the inserted string. It is a callable $function (see Calling Sirius Mods $functions).
The first argument is the $list identifier of the $list to which the string is to be added. This is a required argument.
The second argument is the string to add to the $list. This is a required argument.
Syntax
<section begin="syntax" /> [%RC =] $List_Add_Ordered(list, string) <section end="syntax" />
$List_Add_Ordered Function
%RC is the item number of the added string.
All errors in $List_Add_Ordered result in request cancellation.
$List_Add_Ordered always adds the indicated string even if that string already exists on the $list but the new item is inserted so that the $list is in EBCDIC order. $List_Add_Ordered assumes that the $list is in EBCDIC order so it does a pseudo binary search to locate the correct insertion point. $List_Add_Ordered does not validate that the $list is in order and, it it isn't, the insertion point is unpredictable.
The following code builds a sorted output $list from an input $list.
FOR %I FROM 1 TO $ListCnt(%INLIST) %STRING = $ListInf(%INLIST, %I) %RC = $List_Add_Ordered(%OUTLIST, %STRING) END FOR
While in general it would be more efficient to simply copy and sort (via $ListSort) the input $list such a technique might be useful if the target $list already as a large number of items.
Because $List_Add_Ordered will insert items into the middle of a $list it will be susceptible to the same page-splitting, sparse $list leaf page issues as $ListIns.
This $function is new in Version 6.3.
- Sirius functions
- Fast/Unload User Language Interface
- Janus Open Client
- Janus Open Server
- Janus Sockets
- Janus Web Server
- Japanese functions
- Sir2000 Field Migration Facility
Products authorizing $List_Add_Ordered