NamedArraylist class: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
m (typo)
 
(9 intermediate revisions by 4 users not shown)
Line 1: Line 1:
<!-- NamedArraylist class -->
<!-- NamedArraylist class -->
<var>NamedArraylists</var> can be thought of as traditional arrays with no bounds but
A <var>NamedArraylist</var> can be thought of as a traditional array with no bounds but
with identifying subscripts that can be arbitrary strings rather than numbers.
with identifying subscripts that can be arbitrary strings rather than numbers.


The <var>NamedArraylist</var> class extends the system <var>[[GenericNamedArraylist class|GenericNamedArraylist]]</var>, class, so many of the methods available in the <var>NamedArraylist</var> class are documented as belonging to the <var>GenericNamedArraylist</var> class. Any method available in the <var>GenericNamedArraylist</var> class is also available in the <var>NamedArraylist</var> class.
==About the GenericNamedArraylist class==
The <var>NamedArraylist</var> class extends the system <var>[[GenericNamedArraylist class|GenericNamedArraylist]]</var> class, so many of the methods available in the <var>NamedArraylist</var> class are documented as belonging to the <var>GenericNamedArraylist</var> class. Any method available in the <var>GenericNamedArraylist</var> class is also available in the <var>NamedArraylist</var> class. The other classes that extend the <var>GenericNamedArraylist</var> class are the <var>[[FloatNamedArraylist class|FloatNamedArraylist]]</var> class and the <var>[[UnicodeNamedArraylist class|UnicodeNamedArraylist]]</var> class.  


For background information about collections and NamedArraylists and about
Looking up an item in a <var>NamedArraylist</var> by its name is only slightly
declaring NamedArraylist object variables,
(possibly immeasurably) more CPU intensive than looking up the
see [[Collections]].
item by number, either in a <var>NamedArraylist</var> or in an <var>Arraylist</var>.
See also [[Collections#Coding considerations for collections|Coding
<var>NamedArraylist</var> items will also take up a bit more space in CCATEMP
considerations for collections]].
than <var>Arraylist</var> items &mdash; the extra space required to hold the names.
Usually, this overhead should be minor.
   
   
The following code illustrates some of the NamedArraylist methods:
Because of their relatively low extra overhead, <var>NamedArraylists</var>
<pre style="xmp">
should be used wherever their functionality may
    %narl  is collection NamedArraylist of longstring
prove useful, without concern for performance (which will be quite good).
    %i      is float
 
<div id="NamedArraylist examples"><!--in case references to old section name-->
==Examples==
<ul>
<li>The following code shows some of the <var>NamedArraylist</var> methods:
<p class="code">%narl  is collection NamedArraylist of longstring
%i      is float
   
   
    %narl = new
%narl = new
    %narl:useDefault = true
%narl:useDefault = true
    %narl('Idle') = 'Eric'
%narl('Idle') = 'Eric'
    %narl('Cleese') = 'John'
%narl('Cleese') = 'John'
    %narl('Gilliam') = 'Terry'
%narl('Gilliam') = 'Terry'
    %narl('Pallin')  = 'Michael'
%narl('Pallin')  = 'Michael'
    %narl('Chapman') = 'Graham'
%narl('Chapman') = 'Graham'
   
   
    Print 'The American''s first name is ' %narl('Gilliam')
Print 'The American&apos;&apos;s first name is ' %narl('Gilliam')
   
   
    print '*** Completely different:'
print '*** Completely different:'
    for %i from 1 to %narl:count
for %i from 1 to %narl:count
      print %narl:itemByNumber(%i) and %narl:nameByNumber(%i)
  print %narl:itemByNumber(%i) and %narl:nameByNumber(%i)
    end for
end for
</pre>
</p>
   
   
This code prints:
This code prints:
<pre style="xmp">
<p class="output">The American's first name is Terry
    The American's first name is Terry
&#42;** Completely different:
    *** Completely different:
Graham Chapman
    Graham Chapman
John Cleese
    John Cleese
Terry Gilliam
    Terry Gilliam
Eric Idle
    Eric Idle
Michael Pallin
    Michael Pallin
</p>
</pre>
 
:Note.
<p class="note">'''Note:''' The items are kept in EBCDIC order by their name.
The items are kept in EBCDIC order by their name.
This is always the case for <var>NamedArraylist</var> items. </p></li>
This is always the case for NamedArraylist items.
   
   
For another example, suppose there is a recordSet ([[??]] refid=filobj.)
<li>For another example, suppose there is a <var>[[Recordset class|Recordset]]</var> object
in a file where
in a file where field <code>ProductId</code> has a product ID and field <code>Quantity</code> has the number of items with that ID.
field ProductId has a product ID and field Quantity has the number
The product IDs are ten-character alphanumeric IDs, so they cannot be used as numeric subscripts.
of items with that ID.
Some records may have the same <code>ProductId</code> as others.
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
<var>NamedArraylists</var> provide an ideal way of getting the total quantity
of each item in the recordSet:
of each item in the <var>Recordset</var>:
<pre style="xmp">
<p class="code">%quantity  is collection NamedArraylist of float
    %quantity  is collection NamedArraylist of float
...
    ...
%quantity = new
    %quantity = new
%quantity:useDefault = true
    %quantity:useDefault = true
   
   
    for each record in %recset
for each record in %recset
      %quantity(productId) = %quantity(productId) + quantity
  %quantity(productId) = %quantity(productId) + quantity
    end for
end for
   
   
    for %i from 1 to %quantity:count
for %i from 1 to %quantity:count
      print %quantity:nameByNumber(%i) and -
  print %quantity:nameByNumber(%i) and -
            %quantity:itemByNumber(%i)
        %quantity:itemByNumber(%i)
    end for
end for
</pre>
</p>
Because UseDefault is set to <tt>True</tt>, the first reference to
 
a %quantity item for a given Productid will return the default
Because <var>UseDefault</var> is set to <code>True</code>, the first reference to
value of <tt>0</tt>.
a <code>%quantity</code> item for a given <code>ProductId</code> will return the default
The value of the Quantity field is added to this 0, and the
value of <code>0</code>.
The value of the <code>Quantity</code> field is added to this 0, and the
total is stored under the product ID.
total is stored under the product ID.
Subsequent requests for the same product ID will return the
Subsequent requests for the same product ID will return the current running total for that product.</li>
current running total for that product.
</ul>
 
Looking up an item in a NamedArraylist by its name is only slightly
==List of NamedArraylist methods==
(possibly immeasurably) more CPU intensive than looking up the
The [[List of NamedArraylist methods]] shows all the class methods, with a brief description of each.
item by number, either in a NamedArraylist or in an Arraylist.
 
NamedArraylist items will also take up a bit more space in CCATEMP
==See also==
than Arraylist items &mdash; the extra space required to hold
<table>
the names.
<tr><td>[[List of FloatNamedArraylist methods]]</td>
Usually, this overhead should be minor.
<td>For a list of all methods in the <var>FloatNamedArraylist</var> class, with a brief description of each.</td></tr>
 
Because of their relatively low extra overhead, NamedArraylists
<tr><td nowrap>[[List of UnicodeNamedArraylist methods]]</td>
should be used wherever their functionality may
<td>For a list of all methods in the <var>UnicodeNamedArraylist</var> class, with a brief description of each.</td></tr>
prove useful, without concern for performance (which will be quite good).
 
<tr><td>[[Collections]]</td>
The individual NamedArraylist methods are described in the following subsections.
<td>For background information about collections and <var>Arraylist</var>s and about
In the method templates, <tt>%namrayl</tt> is used to represent the object
declaring <var>Arraylist</var> object variables.</td></tr>
to which the method is being applied, sometimes called the &ldquo;method
 
object&rdquo;
<tr><td>[[Collections#Coding considerations for collections|Coding
or the &ldquo;method NamedArraylist.&rdquo;
considerations for collections]]</td>
Additional conventions are described in [[Notation conventions for methods]].
<td>For tips on using collections.</td></tr>
</table>
 
[[Category:System classes]]
[[Category:System classes]]

Latest revision as of 22:43, 11 November 2014

A NamedArraylist can be thought of as a traditional array with no bounds but with identifying subscripts that can be arbitrary strings rather than numbers.

About the GenericNamedArraylist class

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. The other classes that extend the GenericNamedArraylist class are the FloatNamedArraylist class and the UnicodeNamedArraylist class.

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).

Examples

  • The following code shows 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 object 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.

List of NamedArraylist methods

The List of NamedArraylist methods shows all the class methods, with a brief description of each.

See also

List of FloatNamedArraylist methods For a list of all methods in the FloatNamedArraylist class, with a brief description of each.
List of UnicodeNamedArraylist methods For a list of all methods in the UnicodeNamedArraylist class, with a brief description of each.
Collections For background information about collections and Arraylists and about declaring Arraylist object variables.
Coding considerations for collections For tips on using collections.