NamedArraylist class

NamedArraylists can be thought of as traditional arrays with no bounds but with identifying subscripts that can be arbitrary strings rather than numbers.

The NamedArraylist class extends the system GenericNamedArraylist, class, so many of the methods available in the NamedArraylist class are documented as belonging to the GenericNamedArraylist class. Any method available in the GenericNamedArraylist class is also available in the NamedArraylist class.

For background information about collections and NamedArraylists and about declaring NamedArraylist object variables, see Collections. See also Coding considerations for collections.

The following code illustrates some of the NamedArraylist methods:

    %narl  is collection NamedArraylist of longstring
    %i      is float
 
    %narl = new
    %narl:useDefault = true
    %narl('Idle') = 'Eric'
    %narl('Cleese') = 'John'
    %narl('Gilliam') = 'Terry'
    %narl('Pallin')  = 'Michael'
    %narl('Chapman') = 'Graham'
 
    Print 'The American''s first name is ' %narl('Gilliam')
 
    print '*** Completely different:'
    for %i from 1 to %narl:count
      print %narl:itemByNumber(%i) and %narl:nameByNumber(%i)
    end for

This code prints:

    The American's first name is Terry
    *** Completely different:
    Graham Chapman
    John Cleese
    Terry Gilliam
    Eric Idle
    Michael Pallin

Note.

The items are kept in EBCDIC order by their name. This is always the case for NamedArraylist items.

For another example, suppose there is a recordSet (?? refid=filobj.) in a file where field ProductId has a product ID and field Quantity has the number of items with that ID. The product IDs are ten-character alphanumeric IDs, so they cannot be used as numeric subscripts. Some records may have the same ProductId as others.

NamedArraylists provide an ideal way of getting the total quantity of each item in the recordSet:

    %quantity   is collection NamedArraylist of float
     ...
    %quantity = new
    %quantity:useDefault = true
 
    for each record in %recset
       %quantity(productId) = %quantity(productId) + quantity
    end for
 
    for %i from 1 to %quantity:count
       print %quantity:nameByNumber(%i) and -
             %quantity:itemByNumber(%i)
    end for

Because UseDefault is set to True, the first reference to a %quantity item for a given Productid will return the default value of 0. The value of the Quantity field is added to this 0, and the total is stored under the product ID. Subsequent requests for the same product ID will return the current running total for that product.

Looking up an item in a NamedArraylist by its name is only slightly (possibly immeasurably) more CPU intensive than looking up the item by number, either in a NamedArraylist or in an Arraylist. NamedArraylist items will also take up a bit more space in CCATEMP than Arraylist items — the extra space required to hold the names. Usually, this overhead should be minor.

Because of their relatively low extra overhead, NamedArraylists should be used wherever their functionality may prove useful, without concern for performance (which will be quite good).

The individual NamedArraylist methods are described in the following subsections. In the method templates, %namrayl is used to represent the object to which the method is being applied, sometimes called the “method object” or the “method NamedArraylist.” Additional conventions are described in Notation conventions for methods.