|
|
| Line 1: |
Line 1: |
| <span style="font-size:120%; color:black"><b><section begin=dpl_desc/>Find matching list item<section end=dpl_desc/></b></span>
| | #REDIRECT [[FindNextItem (GenericNamedArraylist function)]] |
| [[Category:UnicodeNamedArraylist methods|FindNextItem function]] | |
| <!--DPL?? Category:UnicodeNamedArraylist methods|FindNextItem function: Find matching list item-->
| |
| <p>
| |
| FindNextItem is a member of the [[UnicodeNamedArraylist class]]. | |
| </p>
| |
| | |
| This function searches “forward” in the UnicodeNamedArraylist to find and
| |
| return the next item that matches a specified criterion.
| |
| The criterion is supplied by the [[SelectionCriterion class|SelectionCriterion]] object
| |
| that is a required FindNextItem parameter.
| |
| If no item satisfies the criterion,
| |
| the request is cancelled and an ItemNotFound exception ([[??]] refid=itemnfe.)
| |
| is thrown.
| |
| ==Syntax==
| |
| %item = %unamrayl:FindNextItem(criterion -
| |
| [, Start=itemnum])
| |
| ===Syntax Terms===
| |
| <dl>
| |
| <dt><i>%item</i>
| |
| <dd>A variable of the type of the items in the UnicodeNamedArraylist to contain
| |
| the item that is located by the search.
| |
| <dt><i>%unamrayl</i>
| |
| <dd>A UnicodeNamedArraylist object.
| |
| <dt><i>criterion</i>
| |
| <dd>A SelectionCriterion object, which is a relational expression that is
| |
| applied to a ''%unamrayl'' item value to determine
| |
| whether the value satisfies the expression.
| |
| The expression consists of a function, an operator, and a User Language intrinsic type
| |
| (numeric, string, or Unicode) value.
| |
| | |
| For example, <tt>GT(this, 1)</tt> is the
| |
| criterion <tt>this</tt> <tt>></tt> <tt>1</tt>, where
| |
| <tt>this</tt> is an identity function that simply returns the item's value.
| |
| The first item tested by FindNextItem that satisfies this expression is
| |
| the method's return value.
| |
| | |
| The function in the criterion is
| |
| a method value (a method or class member name literal, or a method variable)
| |
| for a method
| |
| that operates on items of the type specified on the ''%unamrayl''
| |
| declaration and that returns an intrinsic value.
| |
| This is described further in "[[SelectionCriterion class#Specifying a SelectionCriterion's parameters|Specifying a SelectionCriterion's parameters]]".
| |
| <dt><b>Start=</b><i> itemnum</i>
| |
| <dd>The number of the item ''after'' which to begin the search.
| |
| If the ''itemnum'' value of Start is 2, item 3 is the first item considered.
| |
| The value of Start may be 0 through the number of items in
| |
| the UnicodeNamedArraylist.
| |
| For a UnicodeNamedArraylist of three items, ''itemnum'' may be 0, 1, 2,
| |
| or 3.
| |
| | |
| This is an optional argument, and it defaults to 0.
| |
| If you specify a value, the parameter name <tt>Start</tt> is required.
| |
| | |
| </dl>
| |
| ==Usage Notes==
| |
| <ul>
| |
| <li>If the value of Start is greater than the number of items in the
| |
| UnicodeNamedArraylist, the request is cancelled.
| |
| If the value of Start is equal to the number of items,
| |
| the request is cancelled, but an ItemNotFound exception is thrown.
| |
| <li>[[FindPreviousItem (UnicodeNamedArraylist function)|FindPreviousItem]]
| |
| is identical to FindNextItem except that it searches backward in the
| |
| UnicodeNamedArraylist.
| |
| </ul>
| |
| ==Examples==
| |
| | |
| The following request contains one FindNextItem call and one FindPreviousItem
| |
| call.
| |
| The FindPreviousItem call finds no matching item:
| |
| <pre style="xmp">
| |
| Begin
| |
| | |
| %k is unicodeNamedArraylist of longstring
| |
| %k = new
| |
| %k('§Jan':u) = 'Orion'
| |
| %k('§Apr':u) = 'Leo'
| |
| %k('§Mar':u) = 'Cancer'
| |
| %k('§Jun':u) = 'Ursa Minor'
| |
| %k('§Nov':u) = 'Andromeda'
| |
| %k('§Dec':u) = 'Aries'
| |
| %k('§Feb':u) = 'Canis Major'
| |
| | |
| %sel is object selectionCriterion for longstring
| |
| %sel2 is object selectionCriterion for longstring
| |
| %sel = OR(LT(this, 'C'), EQ(this, 'Taurus'))
| |
| %sel2 = EQ(this, 'Taurus')
| |
| | |
| Print %k:findNextitem(%sel)
| |
| Print %k:findPreviousitem(%sel2)
| |
| | |
| End
| |
| </pre>
| |
| | |
| The result is:
| |
| <pre style="xmp">
| |
| Aries
| |
| CANCELLING REQUEST: MSIR.0750: Class UNICODENAMEDARRAYLIST,
| |
| function FINDNEXTITEM: ITEMNOTFOUND exception: no items match
| |
| SelectionCriterion in line 31
| |
| </pre>
| |