$List_Add_Ordered

From m204wiki
Jump to navigation Jump to search

Add an item to an ordered $list

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $List_Add_Ordered function is AddOrdered.

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.


Syntax

[%rc =] $List_Add_Ordered(list, string)

Where:

  • %rc is the item number of the added string.
  • list is the $list identifier of the $list to which the string is to be added. This is a required argument.
  • string is the string to add to the $list. This is a required argument.

Usage notes

  • 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.
  • 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 has 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.

Example

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

Products authorizing $List_Add_Ordered