The Collection Classes

[]

     +-,-----+
     V       |
>>-[---index-+-]-----------------------------------------------><

This is an abstract method that must be implemented by a subclass if this class.

[]=

     +-,-----+
     V       |
>>-[---index-+-]=value-----------------------------------------><

This is an abstract method that must be implemented by a subclass if this class.

allIndexes

>>-allIndexes---------------------------------------------------><

This is an abstract method which must be implemented by a subclass of this class.

allItems

>>-allItems---------------------------------------------------><

This is an abstract method which must be implemented by a subclass of this class.

at

       +-,-----+
       V       |
>>-at(---index-+-)---------------------------------------------><

Returns the item associated with the specified index or indexes. If the collection has no item associated with the specified index or indexes, this method returns the Nil object.

difference

>>-difference(argument)----------------------------------------><

Returns a new collection (of the same class as the receiver) containing only those items from the receiver whose indexes the argument collection does not contain. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

hasIndex

             +-,-----+
             V       |
>>-hasIndex(---index-+-)---------------------------------------><

Returns 1 (true) if the array contains an item associated with the specified index or indexes. Returns 0 (false) otherwise.

hasItem

>>-hasItem(item)----------------------------------------------><

Returns 1 (true) if the collection contains the specified item at any index location. Returns 0 (false) otherwise.

index

>>-index(item)------------------------------------------------><

This is an abstract method which must be implemented by a subclass of this class.

intersection

>>-intersection(argument)--------------------------------------><

Returns a new collection (of the same class as the receiver) containing only those items from the receiver whose indexes are in both the receiver collection and the argument collection. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

items

>>-items-------------------------------------------------------><

Returns the number of items in the collection.

makeArray

>>-makeArray---------------------------------------------------><

Returns a single-index array with the same number of items as the receiver object. Any index with no associated item is omitted from the new array. Items in the new array will have the same order as the source array.

put

            +--------+
            V        |
>>-put(item---,index-+-)---------------------------------------><

This is an abstract method that must be implemented by a subclass if this class.

subset

>>-subset(argument)--------------------------------------------><

Returns 1 (true) if all indexes in the receiver collection are also contained in the argument collection; returns 0 (false) otherwise. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

supplier

-supplier------------------------------------------------------><

Returns a supplier object for the collection. After you have obtained a supplier, you can send it messages (see The Supplier Class) to enumerate all the items that were in the collection at the time of the supplier's creation.

union

>>-union(argument)---------------------------------------------><

Returns a new collection of the same class as the receiver that contains all the items from the receiver collection and selected items from the argument collection. This method includes an item from argument in the new collection only if there is no item with the same associated index in the receiver collection and the method has not already included an item with the same index. The order in which this method selects items in argument is unspecified (the program should not rely on any order.). The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

xor

>>-xor(argument)-----------------------------------------------><

Returns a new collection of the same class as the receiver that contains all items from the receiver collection and the argument collection; all indexes that appear in both collections are removed. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

Inherited Methods

Methods inherited from the Object class.

Methods inherited from the Collection class.

putAll

>>-putAll(collection)---------------------------------------><

Adds all items collection to the target directory. The collection argument can be any object that supports a supplier method. Items from collection are added using the index values returned by the supplier. The item indexes from the source collection must be strings. The items are added in the order provided by the supplier object. If duplicate indexes exist in collection, the last item provided by the supplier will overwrite previous items with the same index.

makeArray

>>-makeArray---------------------------------------------------><

Returns a single-index array of the index values used by the receiver object. The index objects will not be ordered in any predictable order.

append

>>-append(item)------------------------------------------------><

This is an abstract method that must be implemented by a subclass if this class.

appendAll

>>-appendAll(collection)---------------------------------------><

Appends all items in collection to the end of the target collection. The collection may be any object that implements an allItems method.

difference

>>-difference(argument)----------------------------------------><

Returns a new collection (of the same class as the receiver) containing only those items from the receiver whose indexes the argument collection does not contain. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

intersection

>>-intersection(argument)--------------------------------------><

Returns a new collection (of the same class as the receiver) containing only those items from the receiver whose indexes are in both the receiver collection and the argument collection. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

subset

>>-subset(argument)--------------------------------------------><

Returns 1 (true) if all indexes in the receiver collection are also contained in the argument collection; returns 0 (false) otherwise. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

union

>>-union(argument)---------------------------------------------><

Returns a new collection of the same class as the receiver that contains all the items from the receiver collection and selected items from the argument collection. This method includes an item from argument in the new collection only if there is no item with the same associated index in the receiver collection and the method has not already included an item with the same index. The order in which this method selects items in argument is unspecified (the program should not rely on any order.). The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

xor

>>-xor(argument)-----------------------------------------------><

Returns a new collection of the same class as the receiver that contains all items from the receiver collection and the argument collection; all indexes that appear in both collections are removed. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

Inherited Methods

Methods inherited from the Object class.

Methods inherited from the Collection class.

Inherited Methods

Methods inherited from the Object class.

Methods inherited from the Collection class.

Methods inherited from the OrderedCollection class.

new (Class Method)

>>-new-+----------------+--------------------------------------><
       |    +-,----+    |
       |    V      |    |
       +-(----size-+--)-+

Returns a new empty array. If you specify any size, the size is taken as a hint about how big each dimension should be. The language processor uses this only to allocate the array object initially. For multiple dimension arrays, you can also specify how much space is to be allocated initially for each dimension of the array.

Each size argument must be 0 or a positive whole number. If it is 0, the corresponding dimension is initially empty.

of (Class Method)

>>-of-+----------------+---------------------------------------><
      |    +-,----+    |
      |    V      |    |
      +-(----item-+--)-+

Returns a newly created single-index array containing the specified item objects. The first item has index 1, the second has index 2, and so on.

If you use the OF method and omit any argument items, the returned array does not include the indexes corresponding to those you omitted.

Examples:

   a = .array~of("Fred", "Mike", "David")

   do name over a
      say name  -- displays "Fred", "Mike", and "David"
   end

[]

     +-,-----+
     V       |
>>-[---index-+-]-----------------------------------------------><

Returns the same value as the at method, which follows. See at.

[]=

     +-,-----+
     V       |
>>-[---index-+-]=value-----------------------------------------><

This method is the same as the put method, which follows. See put.

allIndexes

>>-allIndexes---------------------------------------------------><

Returns an array of all index positions in the array containing items.

Examples:

   a = .array~of("Fred", "Mike", "David")

   do name over a~allIndexes
      say name  -- displays "1", "2", and "3"
   end

   a~remove(2)  -- remove second item

   do name over a~allIndexes
      say name  -- displays "1" and "3"
   end

allItems

>>-allItems---------------------------------------------------><

Returns an array of all items contained in the array.

Examples:

   a = .array~of("Fred", "Mike", "David")

   do name over a~allItems
      say name  -- displays "Fred", "Mike", and "David"
   end

   a~remove(2)  -- remove second item

   do name over a~allItems
      say name  -- displays "Fred" and "David"
   end

append

>>-append(item)------------------------------------------------><

Appends an item to the array after the last item (the item with the highest index. The return value is the index of newly added item.

Examples:

   a = .array~of("Mike", "Rick")
   a~append("Fred")  -- a = .array~of("Mike", "Rick", "Fred")

at

       +-,-----+
       V       |
>>-at(---index-+-)---------------------------------------------><

Returns the item associated with the specified index or indexes. If the array has no item associated with the specified index or indexes, this method returns the Nil object.

Examples:

   a = .array~of("Mike", "Rick")
   say a~at(2)  -- says: "Rick"

dimension

>>-dimension-+-----+-------------------------------------------><
             +-(n)-+

Returns the current size (upper bound) of dimension n (a positive whole number). If you omit n, this method returns the dimensionality (number of dimensions) of the array. If the number of dimensions has not been determined, dimension returns 0.

Examples:

   a = .array~of(,"Mike", "Rick")
   say a~dimension     -- says: 1 (number of dimensions in the array)
   say a~dimension(1)  -- says: 3 (upper bound of dimension one)

   a = .array~new~~put("Mike",1,1)~~put("Rick",1,2)
   say a~dimension     -- says: 2 (number of dimensions in the array)
   say a~dimension(1)  -- says: 1 (upper bound of dimension one)
   say a~dimension(2)  -- says: 2 (upper bound of dimension two)

empty

>>-empty-------------------------------------------------------><

Removes all items from the array.

Examples:

   a = .array~of("Mike", "Rick", "Fred", "Rick")
   a~empty  -- a = .array~new

first

>>-first-------------------------------------------------------><

Returns the index of the first item in the array or the Nil object if the array is empty. The first method is valid only for single-index arrays.

Examples:

   a = .array~of("Mike", "Rick", "Fred", "Rick")
   say a~first  -- says: 1
   a = .array~of(,"Mike", "Rick")
   say a~first  -- says: 2

hasIndex

             +-,-----+
             V       |
>>-hasIndex(---index-+-)---------------------------------------><

Returns 1 (true) if the array contains an item associated with the specified index or indexes. Returns 0 (false) otherwise.

Examples:

   a = .array~of("Mike", "Rick", "Fred", "Rick")
   say a~hasIndex(2)  -- says: 1
   say a~hasIndex(5)  -- says: 0

hasItem

>>-hasItem(item)----------------------------------------------><

Returns 1 (true) if the array contains the specified item at any index location. Returns 0 (false) otherwise.

Examples:

   a = .array~of("Mike", "Rick", "Fred", "Rick")
   say a~hasItem("Rick")  -- says: 1
   say a~hasItem("Mark")  -- says: 0

index

>>-index(item)------------------------------------------------><

Returns the index of the specified item within the array. If the target item appears at more than one index, the first located index will be returned. If the array does not contain the specified item, .nil is returned.

Examples:

   a = .array~of("Mike", "Rick", "Fred", "Rick")
   say a~index("Rick")  -- says: 2

isEmpty

>>-isEmpty----------------------------------------------------><

Returns 1 (true) if the array is empty. Returns 0 (false) otherwise.

Examples:

   a = .array~new
   say a~isEmpty  -- says: 1
   a[1] = "1"
   say a~isEmpty  -- says: 0

items

>>-items-------------------------------------------------------><

Returns the number of items in the collection.

Examples:

   a = .array~of("Fred",, "Mike",, "David")
   say a~items  -- says: 3

last

>>-last--------------------------------------------------------><

Returns the index of the last item in the array or the NIL object if the array is empty. The last method is valid only for single-index arrays.

Examples:

   a = .array~of("Fred",, "Mike",, "David")
   say a~last  -- says: 5

makeArray

>>-makeArray---------------------------------------------------><

Returns a single-index array with the same number of items as the receiver object. Any index with no associated item is omitted from the new array. Items in the new array will have the same order as the source array.

Examples:

   a = .array~of("Fred",, "Mike",, "David")
   b = a~makeArray  -- b = .array~of("Fred", "Mike", "David")

makeString

                         +-,separator-+
               +-(LINE)--+------------+-+
>>-makeString(-+---------+--------------+-)------------------------><
               +-(CHAR)--+

Returns a string that contains the data of an array (one to n dimensional). The elements of the array are treated either in line or character format, starting at the first element in the array. The line format is the default. If the line format is use, a separator string can be specified. The separator will be used between concatenated elements instead of the default line end separator.

Examples:

See toString for examples.

next

>>-next(index)-------------------------------------------------><

Returns the index of the item that follows the array item having index index or returns the Nil object if the item having that index is last in the array. The next method is valid only for single-index arrays.

Examples:

   a = .array~of("Fred",, "Mike",, "David")
   say a~next(3)  -- says: 5

previous

>>-previous(index)---------------------------------------------><

Returns the index of the item that precedes the array item having index index or the Nil object if the item having that index is first in the array. The previous method is valid only for single-index arrays.

Examples:

   a = .array~of("Fred",, "Mike",, "David")
   say a~previous(3)  -- says: 1

put

            +--------+
            V        |
>>-put(item---,index-+-)---------------------------------------><

Makes the object item a member item of the array and associates it with the specified index or indexes. This replaces any existing item associated with the specified index or indexes with the new item. If the index for a particular dimension is greater than the current size of that dimension, the array is expanded to the new dimension size.

Examples:

   a = .array~new
   a~put(1, "Fred")  -- a = .array~of("Fred")
   a~put(2, "Mike")  -- a = .array~of("Fred", "Mike")
   a~put(1, "Mike")  -- a = .array~of("Mike", "Mike")

remove

           +-,-----+
           V       |
>>-remove(---index-+-)-----------------------------------------><

Returns and removes the member item with the specified index or indexes from the array. If there is no item with the specified index or indexes, the Nil object is returned and no item is removed.

Examples:

   a = .array~of("Fred", "Mike", "Mike", "David")
   a~remove(2)  -- removes "Mike"

removeItem

>>-removeItem(item)--------------------------------------------><

Removes an item from the array. If the target item exists at more than one index, the first located item is removed. The return value is the removed item.

Examples:

   a = .array~of("Fred", "Mike", "Mike", "David")
   a~removeItem("Mike")  -- removes the item at index "2"

section

>>-section(start-+--------+-)----------------------------------><
                 +-,items-+

Returns a new array (of the same class as the receiver) containing selected items from the receiver array. The first item in the new array is the item corresponding to index start in the receiver array. Subsequent items in the new array correspond to those in the receiver array (in the same sequence). If you specify the whole number items, the new array contains only this number of items (or the number of subsequent items in the receiver array, if this is less than items). If you do not specify items, the new array contains all subsequent items of the receiver array. The receiver array remains unchanged. The section method is valid only for single-index arrays.

Examples:

   a = .array~of(1,2,3,4)  -- Loads the array

   b = a~section(2)   -- b = .array~of(2,3,4)
   c = a~section(2,2) -- c = .array~of(2,3)
   d = a~section(2,0) -- d = .array~new

size

>>-size--------------------------------------------------------><

Returns the number of items that can be placed in the array before it needs to be extended. This value is the same as the product of the sizes of the dimensions in the array.

sort

>>-sort--------------------------------------------------------><

Sorts an array of Comparable items into ascending order using an unstable Quicksort algorithm. See Sorting Arrays for details.

sortWith

>>-sortWith(comparator)---------------------------------------------><

Sorts an array of items into ascending order using an unstable Quicksort algorithm. Ordering of elements is determined using the comparator argument. See Sorting Arrays for details.

stableSort

>>-stableSort--------------------------------------------------------><

Sorts an array of Comparable items into ascending order using a stable Mergesort algorithm. See Sorting Arrays for details.

stableSortWith

>>-stableSortWith(comparator)---------------------------------------------><

Sorts an array of items into ascending order using a stable Mergesort algorithm. Ordering of elements is determined using the comparator argument. See Sorting Arrays for details.

supplier

-supplier------------------------------------------------------><

Returns a supplier object for the collection. After you have obtained a supplier, you can send it messages (see The Supplier Class) to enumerate all the items that were in the array at the time of the supplier's creation. The supplier enumerates the array items in their sequenced order. For multi-dimensional arrays, the supplier index method will return the index values as an array of index numbers.

toString

                       +-,separator-+
             +-(LINE)--+------------+-+
>>-toString(-+---------+--------------+-)------------------------><
             +-(CHAR)--+

Returns a string that contains the data of an array (one to n dimensional). The elements of the array are treated either in line or character format, starting at the first element in the array. The line format is the default. If the line format is use, a separator string can be specified. The separator will be used between concatenated elements instead of the default line end separator.

Examples:

   a = .array~of(1,2,3,4)  -- Loads the array

   say a~toString  -- Produces: 1
                   --           2
                   --           3
                   --           4

   say a~toString("c")  -- Produces: 1234

   say a~toString(, ", ")  -- Produces: 1, 2, 3, 4

Examples

array1=.array~of(1,2,3,4)  /* Loads the array */

/* Alternative way to create and load an array */
array2=.array~new(4)  /* Creates array2, containing 4 items */
do i=1 to 4                   /* Loads the array */
  array2[i]=i
end

You can produce the elements loaded into an array, for example:

do i=1 to 4
  say array1[i]
end

If you omit any argument values before arguments you supply, the corresponding indexes are skipped in the returned array:

directions=.array~of("North","South", ,"West")
do i=1 to 4                                  /* Produces: North          */
  say directions[i]                          /*           South          */
                                             /*           The NIL object */
end                                          /*           West           */

Here is an example using the ~~:

z=.array~of(1,2,3)~~put(4,4)
do i = 1 to z~size
  say z[i]              /* Produces:  1 2 3 4 */
end

Inherited Methods

Methods inherited from the Object class.

Methods inherited from the Collection class.

Methods inherited from the MapCollection class.

Methods inherited from the Relation class.

[]=

>>-[index]=item------------------------------------------------><

This method is the same as the put method. See put.

of (Class Method)

       +-,----+
       V      |
>>-of(---item-+-)----------------------------------------------><

Returns a newly created bag containing the specified item objects.

difference

This method overrides the difference method from the Relation class.

>>-difference(argument)----------------------------------------><

Returns a new collection (of the same class as the receiver) containing only those items from the receiver whose indexes the argument collection does not contain. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

hasIndex

>>-hasIndex(index)---------------------------------------------><

Returns 1 (true) if the collection contains any item associated with index index, or 0 (false).

intersection

This method overrides the intersection method from the Relation class.

>>-intersection(argument)--------------------------------------><

Returns a new collection (of the same class as the receiver) containing only those items from the receiver whose indexes are in both the receiver collection and the argument collection. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

put

>>-put(item,index)---------------------------------------------><

Makes the object item a member item of the bag and associates it with index index. If the relation already contains any items with index index, this method adds a new member item item with the same index, without removing any existing member items.

putAll

This method overrides the putAll method from the Map Collection class.

>>-putAll(collection)---------------------------------------><

Adds all items collection to the target bag. The collection argument can be any object that supports a supplier method. Items from collection are added using the index values returned by the supplier.

subset

This method overrides the subset method from the Relation class.

>>-subset(argument)--------------------------------------------><

Returns 1 (true) if all indexes in the receiver collection are also contained in the argument collection; returns 0 (false) otherwise. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

union

This method overrides the union method from the Relation class.

>>-union(argument)---------------------------------------------><

Returns a new collection of the same class as the receiver that contains all the items from the receiver collection and selected items from the argument collection. This method includes an item from argument in the new collection only if there is no item with the same associated index in the receiver collection and the method has not already included an item with the same index. The order in which this method selects items in argument is unspecified. (The program should not rely on any order.) See also the union method of the Collection (union) and Relation (union) classes. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

xor

This method overrides the xor method from the Relation class.

>>-xor(argument)-----------------------------------------------><

Returns a new collection of the same class as the receiver that contains all items from the receiver collection and the argument collection; all indexes that appear in both collections are removed. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

Examples

/* Create a bag of fruit */
fruit = .bag~of("Apple", "Orange", "Apple", "Pear")
say fruit~items          /* How many pieces? (4)      */
say fruit~items("Apple") /* How many apples? (2)      */
fruit~remove("Apple")    /* Remove one of the apples. */
fruit~~put("Banana")~put("Orange") /* Add a couple.   */
say fruit~items          /* How many pieces? (5)      */

Inherited Methods

Methods inherited from the Object class.

Methods inherited from the Collection class.

Methods inherited from the OrderedCollection class.

Methods inherited from the Queue class.

of (Class Method)

>>-of-+----------------+---------------------------------------><
      |    +-,----+    |
      |    V      |    |
      +-(----item-+--)-+

This method overrides the of method from the Queue class.

Returns a newly created circular queue containing the specified item objects. The first item has index 1, the second has index 2, and so on. The number of item objects determines the size of the circular queue.

init

>>-init--------------------------------------------------------><

Performs initialization of the circular queue.

makeArray

              +-Fifo----+
>>-makeArray(-+---------+-)------------------------------------><
              +--order--+

This method overrides the makeArray method from the Queue class.

Returns a single-index array containing the items of the circular queue in the specified order.

The following order can be used. (Only the capitalized letter is needed; all characters following it are ignored.)

push

>>-push(item)--------------------------------------------------><

This method overrides the push method from the Queue class.

Makes the object item a member item of the circular queue, inserting the item object in front of the first item in the queue. The pushed item object will be the new first item in the circular queue.

If the circular queue is full, than the last item stored in the circular queue will be deleted, before the insertion takes place. In this case the deleted item will be returned, otherwise .nil.

queue

>>-queue(item)-------------------------------------------------><

This method overrides the queue method from the Queue class.

Makes the object item a member item of the circular queue, inserting the item at the end of the circular queue.

If the circular queue is full, than the first item will be deleted, before the insertion takes place. In this case the deleted item will be returned, otherwise .nil.

resize

                   +--,Fifo---+
>>-resize(-newSize-+----------+-)------------------------------><
                   +--,order--+

Resizes the circular queue object to be able to contain newSize items. If the previous size was larger than newSize, then the now superfluous items are removed in the specified order.

The following order can be used. (Only the capitalized letter is needed; all characters following it are ignored.)

size

>>-size--------------------------------------------------------><

Returns the maximum number of objects that can be stored in the circular queue.

string

           +--","------+  +-,-Fifo--+
>>-string(-+-----------+--+---------+-)------------------------><
           +-delimiter-+  +-,-order-+

Returns a string object that concatenates the string values of the collected item objects, using the delimiter string to delimit them, in the specified order. The default delimiter is a single comma.

If the delimiter string argument is omitted the comma character (",") is used as the default delimiter string.

The following order can be used. (Only the capitalized letter is needed; all characters following it are ignored.)

supplier

             +--Fifo----+
>>-supplier(-+----------+-)------------------------------------><
             +--order---+

This method overrides the supplier method from the Queue class.

Returns a supplier object for the collection. After you have obtained a supplier, you can send it messages (see The Supplier Class) to enumerate all the items that were in the queue at the time of the supplier's creation.

The supplier will enumerate the items in the specified order. (Only the capitalized letter is needed; all characters following it are ignored.)

Example

  -- create a circular buffer with five items
u=.circularQueue~of("a", "b", "c", "d", "e")
say "content: ["u"]," "content (LIFO): ["u~string("->","L")"]"
say

u~resize(4, "FIFO")     -- resize fifo-style (keep newest)
say "after resizing to 4 items in FIFO style (keeping the newest):"
say "content: ["u"]," "content (LIFO): ["u~string("->","L")"]"
say

u~resize(2, "LILO")     -- resize lifo-style (keep oldest)
say "after resizing to 2 items in LIFO style (keeping the oldest):"
say "content: ["u"]," "content (LIFO): ["u~string("->","L")"]"
say

u~resize(0)             -- resize lifo-style (keep oldest)
say "after resizing to 0 items, thereby deleting all items:"
say "content: ["u"]," "content (LIFO): ["u~string("->","L")"]"
say

u~resize(2)             -- resize lifo-style (keep oldest)
say "after resizing to 2, size="u~size "and items="u~items
u~~queue('x')~~queue('y')~~queue('z')
say "after queuing the three items 'x', 'y', 'z':"
say "content: ["u"]," "content (LIFO): ["u~string("->","L")"]"
say

u~~push('1')~~push('2')~~push('3')
say "after pushing the three items '1', '2', '3':"
say "content: ["u"]," "content (LIFO): ["u~string("->","L")"]"
say

Output:

content: [a,b,c,d,e], content (LIFO): [e->d->c->b->a]

after resizing to 4 items in FIFO style (keeping the newest):
content: [b,c,d,e], content (LIFO): [e->d->c->b]

after resizing to 2 items in LIFO style (keeping the oldest):
content: [b,c], content (LIFO): [c->b]

after resizing to 0 items, thereby deleting all items:
content: [], content (LIFO): []

after resizing to 2, size=2 and items=0
after queuing the three items 'x', 'y', 'z':
content: [y,z], content (LIFO): [z->y]

after pushing the three items '1', '2', '3':
content: [3,2], content (LIFO): [2->3]

Inherited Methods

Methods inherited from the Object class.

Methods inherited from the Collection class.

Methods inherited from the MapCollection class.

new (Class Method)

>>-new---------------------------------------------------------><

Returns an empty Directory object.

[]

>>-[name]------------------------------------------------------><

Returns the same item as the at method, which follows. See at.

[]=

>>-[name]=item-------------------------------------------------><

This method is the same as the put method. See put.

allIndexes

>>-allIndexes---------------------------------------------------><

Returns an array of all the directory indices, including those of all the setMethod methods.

allItems

>>-allItems---------------------------------------------------><

Returns an array of all items contained in the directory.

at

>>-at(name)----------------------------------------------------><

Returns the item associated with index name. If a method that setMethod supplies is associated with index name, the result of running this method is returned. If the collection has no item or method associated with index name, this method returns the Nil object.

Example:

say .environment~at("OBJECT")   /* Produces: "The Object class" */

empty

>>-empty-------------------------------------------------------><

Removes all items from the directory.

entry

>>-entry(name)-------------------------------------------------><

Returns the directory entry with name name (translated to uppercase). If there is no such entry, name returns the item for any method that setMethod supplied. If there is neither an entry nor a method for name or for unknown, the language processor raises an error.

hasEntry

>>-hasEntry(name)----------------------------------------------><

Returns 1 (true) if the directory has an entry or a method for name name (translated to uppercase), or 0 (false).

hasIndex

>>-hasIndex(name)----------------------------------------------><

Returns 1 (true) if the collection contains any item associated with index name, or 0 (false).

hasItem

>>-hasItem(value)----------------------------------------------><

Returns 1 (true) if the collection contains the value at any index position or otherwise returns 0 (false).

index

>>-index(item)------------------------------------------------><

Returns the index of the specified item within the directory. If the target item appears at more than one index, the first located index will be returned. If the directory does not contain the specified item, .nil is returned.

isEmpty

>>-isEmpty----------------------------------------------------><

Returns 1 (true) if the directory is empty. Returns 0 (false) otherwise.

items

>>-items-------------------------------------------------------><

Returns the number of items in the collection.

makeArray

>>-makeArray---------------------------------------------------><

Returns a single-index array containing the index objects. The array indexes range from 1 to the number of items. The collection items appear in the array in an unspecified order. (The program should not rely on any order.)

put

>>-put(item,name)----------------------------------------------><

Makes the object item a member item of the collection and associates it with index name. The new item replaces any existing item or method associated with index name.

remove

>>-remove(name)------------------------------------------------><

Returns and removes the member item with index name from a collection. If a method is associated with setMethod for index name, remove removes the method and returns the result of running it. If there is no item or method with index name, the unknown method returns the Nil object and removes nothing.

removeItem

>>-removeItem(item)--------------------------------------------><

Removes an item from the directory. If the target item exists at more than one index, the first located item is removed. The return value is the removed item.

setEntry

>>-setEntry(name-+--------+-)----------------------------------><
                 +-,entry-+

Sets the directory entry with name name (translated to uppercase) to the object entry, replacing any existing entry or method for name. If you omit entry, this method removes any entry or method with this name.

setMethod

>>-setMethod(name-+---------+-)--------------------------------><
                  +-,method-+

Associates entry name name (translated to uppercase) with method method. Thus, the language processor returns the result of running method when you access this entry. This occurs when you specify name on the at, entry, or remove method. This method replaces any existing item or method for name.

You can specify the name unknown as name. Doing so supplies a method to run whenever an at or entry message specifies a name for which no item or method exists in the collection. This method's first argument is the specified directory index. This method has no effect on the action of any hasEntry, hasIndex, items, remove, or supplier message sent to the collection.

The method can be a string containing a method source line instead of a method object. Alternatively, an array of strings containing individual method lines can be passed. In either case, setMethod creates an equivalent method object.

If you omit method, setMethod removes the entry with the specified name.

supplier

>>-supplier----------------------------------------------------><

Returns a supplier object for the collection. After you have obtained a supplier, you can send it messages (see The Supplier Class) to enumerate all the items that were in the collection at the time of the supplier's creation. The supplier enumerates the items in an unspecified order. (The program should not rely on any order.)

unknown

>>-unknown(messagename,messageargs)----------------------------><

Runs either the entry or setEntry method, depending on whether messagename ends with an equal sign. If messagename does not end with an equal sign, this method runs the entry method, passing messagename as its argument. The language processor ignores any arguments specified in the array messageargs. In this case, unknown returns the result of the entry method.

If messagename does end with an equal sign, this method runs the setEntry method, passing the first part of messagename (up to, but not including, the final equal sign) as its first argument, and the first item in the array messageargs as its second argument. In this case, unknown returns no result.

unsetMethod

>>-unsetMethod(name)--------------------------------><

Removes the association between entry name name (translated to uppercase) and a method.

xor

>>-xor(argument)-----------------------------------------------><

Returns a new collection of the same class as the receiver that contains all items from the receiver collection and the argument collection; all indexes that appear in both collections are removed. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

Examples

/******************************************************************************/
/*  A Phone Book Directory program                                            */
/*  This program demonstrates use of the directory class.                     */
/******************************************************************************/

/* Define an UNKNOWN method that adds an abbreviation lookup feature.         */
/* Directories do not have to have an UNKNOWN method.                         */
book = .directory~new~~setMethod("UNKNOWN", .methods["UNKNOWN"])

book["ANN" ] = "Ann B. ....... 555-6220"
book["ann" ] = "Little annie . 555-1234"
book["JEFF"] = "Jeff G. ...... 555-5115"
book["MARK"] = "Mark C. ...... 555-5017"
book["MIKE"] = "Mike H. ...... 555-6123"
book~Rick    = "Rick M. ...... 555-5110"  /* Same as book["RICK"] = ...       */

Do i over book                 /* Iterate over the collection                 */
  Say book[i]
end i

Say ""                         /* Index lookup is case sensitive...           */
Say book~entry("Mike")         /* ENTRY method uppercases before lookup       */
Say book["ANN"]                /* Exact match                                 */
Say book~ann                   /* Message sends uppercase before lookup       */
Say book["ann"]                /* Exact match with lowercase index            */

Say ""
Say book["M"]                  /* Uses UNKNOWN method for lookup              */
Say book["Z"]
Exit

/* Define an unknown method to handle indexes not found.                      */
/* Check for abbreviations or indicate listing not found                      */
::Method unknown
  Parse arg at_index
  value = ""
  Do i over self
    If abbrev(i, at_index) then do
      If value <> "" then value = value", "
      value = value || self~at(i)
    end
  end i
  If value = "" then value = "No listing found for" at_index
  Return value

Inherited Methods

Methods inherited from the Object class.

Methods inherited from the Collection class.

Methods inherited from the OrderedCollection class.

new (Class Method)

>>-new---------------------------------------------------------><

Returns a new empty List object.

of (Class Method)

       +-,----+
       V      |
>>-of(---item-+-)----------------------------------------------><

Returns a newly created list containing the specified item objects in the order specified.

[]

>>-[index]-----------------------------------------------------><

Returns the same item as the at method. See at.

[]=

>>-[index]=item------------------------------------------------><

This method is the same as the put method. See put.

allIndexes

>>-allIndexes---------------------------------------------------><

Returns an array of all element contained in the list in sorted order.

allItems

>>-allItems---------------------------------------------------><

Returns an array of all items contained in the list.

append

>>-append(item)---------------------------------------------------><

Appends item to the end of the list.

at

>>-at(index)---------------------------------------------------><

Returns the item associated with index index. If the collection has no item associated with index, this method returns the Nil object.

empty

>>-empty-------------------------------------------------------><

Removes all items from the list.

first

>>-first-------------------------------------------------------><

Returns the index of the first item in the list or the NIL object if the list is empty. The example for insert (see insert) includes first.

firstItem

>>-firstItem---------------------------------------------------><

Returns the first item in the list or the Nil object if the list is empty.

Example:

musketeers=.list~of(Porthos,Athos,Aramis) /* Creates list MUSKETEERS      */
item=musketeers~firstItem                 /* Gives first item in list     */
                                          /* (Assigns "Porthos" to item)  */

hasIndex

>>-hasIndex(index)---------------------------------------------><

Returns 1 (true) if the collection contains any item associated with index index, or 0 (false).

hasItem

>>-hasItem(value)----------------------------------------------><

Returns 1 (true) if the collection contains the value at any index position or otherwise returns 0 (false).

index

>>-index(item)------------------------------------------------><

Returns the index of the specified item within the list. If the target item appears at more than one index, the first located index will be returned. If the list does not contain the specified item, .nil is returned.

insert

>>-insert(item-+--------+-)------------------------------------><
               +-,index-+

Returns a list-supplied index for a new item item, which is added to the list. The new item follows the existing item with index index in the list ordering. If index is the Nil object, the new item becomes the first item in the list. If you omit index, the new item becomes the last item in the list.

Inserting an item in the list at position index will cause the items in the list after position index to have their relative positions shifted by the list object. The index values for any items in the list are not modified by the insertion.

musketeers=.list~of(Porthos,Athos,Aramis) /* Creates list MUSKETEERS        */
                                          /* consisting of: Porthos         */
                                          /*                Athos           */
                                          /*                Aramis          */
index=musketeers~first                    /* Gives index of first item      */
musketeers~insert("D'Artagnan",index) /* Adds D'Artagnan after Porthos  */
                                          /* List is now: Porthos           */
                                          /*              D'Artagnan   */
                                          /*              Athos             */
                                          /*              Aramis            */
/* Alternately, you could use */
musketeers~insert("D'Artagnan",.nil) /* Adds D'Artagnan before Porthos */
                                          /* List is now:  D'Artagnan  */
                                          /*               Porthos          */
                                          /*               Athos            */
                                          /*               Aramis           */
/* Alternately, you could use */
musketeers~insert("D'Artagnan")      /* Adds D'Artagnan after Aramis   */
                                          /* List is now:  Porthos          */
                                          /*               Athos            */
                                          /*               Aramis           */
                                          /*               D'Artagnan  */

isEmpty

>>-isEmpty----------------------------------------------------><

Returns 1 (true) if the list is empty. Returns 0 (false) otherwise.

items

>>-items-------------------------------------------------------><

Returns the number of items in the collection.

last

>>-last--------------------------------------------------------><

Returns the index of the last item in the list or the Nil object if the list is empty.

lastItem

>>-lastItem----------------------------------------------------><

Returns the last item in the list or the NIL object if the list is empty.

makeArray

>>-makeArray---------------------------------------------------><

Returns a single-index array containing the receiver collection items. The array indexes range from 1 to the number of items. The order in which the collection items appear in the array is the same as their sequence in the list collection.

next

>>-next(index)-------------------------------------------------><

Returns the index of the item that follows the list item having index index or returns the Nil object if the item having that index is last in the list.

previous

>>-previous(index)---------------------------------------------><

Returns the index of the item that precedes the list item having index index or the Nil object if the item having that index is first in the list.

put

>>-put(item,index)---------------------------------------------><

Replaces any existing item associated with the specified index with the new item item. If the index does not exist in the list, an error is raised.

remove

>>-remove(index)-----------------------------------------------><

Returns and removes from a collection the member item with index index. If no item has index index, this method returns the Nil object and removes no item.

Removinf an item from the list at position index will cause the items in the list after position index to have their indexes modified by the list object.

removeItem

>>-removeItem(item)--------------------------------------------><

Removes an item from the list. If the target item exists at more than one index, the first located item is removed. The return value is the removed item.

section

>>-section(start-+--------+-)----------------------------------><
                 +-,items-+

Returns a new list (of the same class as the receiver) containing selected items from the receiver list. The first item in the new list is the item corresponding to index start in the receiver list. Subsequent items in the new list correspond to those in the receiver list (in the same sequence). If you specify the whole number items, the new list contains only this number of items (or the number of subsequent items in the receiver list, if this is less than items). If you do not specify items, the new list contains all subsequent items from the receiver list. The receiver list remains unchanged.

supplier

>>-supplier----------------------------------------------------><

Returns a supplier object for the list. If you send appropriate messages to the supplier (see The Supplier Class), the supplier enumerates all the items in the list at the time of the supplier's creation. The supplier enumerates the items in their sequenced order.

Inherited Methods

Methods inherited from the Object class.

Methods inherited from the Collection class.

Methods inherited from the MapCollection class.

Methods inherited from the Directory class.

load (Class method)

>>-load(source)-----------------------------------------------><

Loads a set of properties from source and returns them as a new Properties object. The load source can be either the string name of a file or a stream object. Properties are read from the source as individual lines using linein. Blank lines and lines with a Rexx line comment ("--") as the first non-blank characters are ignored. Otherwise, the lines are assumed to be of the form "name=value" and are added to the receiver Properties value using name as the index for the value.

new (Class method)

>>-new---------------------------------------------------------><

Returns an empty Properties object.

[]=

This method overrides the []= method from the Directory class.

>>-[name]=item-------------------------------------------------><

This method is the same as the put method. See put.

getLogical

>>-getLogical(name-+----------+-)------------------------------------><
                   +-,default-+

Returns the value of name as either .true or .false. The raw value of the name may be either the numeric values "0" or "1" or the string values "true" or "false". Any other value will raise a syntax error. If the property name does not exist and default has been specified, the default value will be returned. If default has not been specified, a syntax error is raised for missing values.

getProperty

>>-getProperty(name-+----------+-)------------------------------------><
                    +-,default-+

Returns the value of name. If property name does not exist and default has been specified, the default value will be returned. If default has not been specified, .nil is returned for the property value.

getWhole

>>-getWhole(name-+----------+-)-----------------------------------><
                 +-,default-+

Returns the value of name, validated as being a Rexx whole number. If property name does not exist and default has been specified, the default value will be returned. If default has not been specified, a syntax error is raised for missing values.

load

>>-load(source)-----------------------------------------------><

Loads a set of properties into the receiving Properties object from source. The load source can be either the string name of a file or a stream object. Properties are read from the source as individual lines using linein. Blank lines and lines with a Rexx line comment ("--") as the first non-blank characters are ignored. Otherwise, the lines are assumed to be of the form "name=value" and are added to the receiver Properties value using name as the index for the value. Properties loaded from source that have the same names as existing items will replace the current entries.

put

This method overrides the put method from the Directory class.

>>-put(item,name)----------------------------------------------><

Makes the object item a member item of the collection and associates it with index name. The item value must be a character string. The new item replaces any existing item or method associated with index name.

save

>>-save(target)-----------------------------------------------><

Saves a set of properties into target. The save target can be either the string name of a file or a stream object. Properties are stored as individual lines using lineout. The lines are written in the form "name=value". A saved Properties file can be reloaded using the Properties load method.

setLogical

>>-setLogical(name,value)--------------------------------------------><

Sets a logical value in the property bundle. The value argument must be either the numbers "0" or "1", or the logical values .true or .false. The property value will be added with value converted in to the appropriate "true" or "false" string value.

setProperty

>>-setProperty(name,value)--------------------------------------------><

Sets a named property the property bundle. The value argument must be a character string value.

setWhole

>>-setWhole(name,value)--------------------------------------------><

Sets a whole number value in the property bundle. The value argument must be a valid Rexx whole number.

Inherited Methods

Methods inherited from the Object class.

Methods inherited from the Collection class.

Methods inherited from the OrderedCollection class.

new (Class Method)

>>-new---------------------------------------------------------><

Returns a new empty Queue object.

of (Class Method)

       +-,----+
       V      |
>>-of(---item-+-)----------------------------------------------><

Returns a newly created queue containing the specified item objects in the order specified.

[]

>>-[index]-----------------------------------------------------><

Returns the same value as the at method. See at.

The order in which the queue items appear in the array is the same as their queuing order, with the head of the queue as index 1.

[]=

>>-[index]=item------------------------------------------------><

This method is the same as the put method. See put.

allIndexes

>>-allIndexes---------------------------------------------------><

Returns an array of all element containing all the index values for the queue. For the Queue class, the indices are integers 1 - items.

allItems

>>-allItems---------------------------------------------------><

Returns an array of all items contained in the queue.

append

>>-append(item)---------------------------------------------------><

Appends item to the end of the queue.

at

>>-at(index)---------------------------------------------------><

Returns the item associated with index index. If the collection has no item associated with index, this method returns the Nil object.

empty

>>-empty-------------------------------------------------------><

Removes all items from the queue.

first

>>-first-------------------------------------------------------><

Returns the index of the first item in the queue or the Nil object if the queue is empty.

hasIndex

>>-hasIndex(index)---------------------------------------------><

Returns 1 (true) if the collection contains any item associated with index index, or 0 (false).

hasItem

>>-hasItem(value)----------------------------------------------><

Returns 1 (true) if the collection contains the value at any index position or otherwise returns 0 (false).

index

>>-index(item)------------------------------------------------><

Returns the index of the specified item within the queue. If the target item appears at more than one index, the first located index will be returned. If the queue does not contain the specified item, .nil is returned.

insert

>>-insert(item-+--------+-)------------------------------------><
               +-,index-+

Returns a queue-supplied index for a new item item, which is added to the queue. The new item follows the existing item with index index in the queue ordering. If index is the Nil object, the new item becomes the first item in the queue. If you omit index, the new item becomes the last item in the queue.

Inserting an item in the queue at position index will cause the items in the queue after position index to have their indexes modified by the queue object.

musketeers=.queue~of(Porthos,Athos,Aramis) /* Creates queue MUSKETEERS       */
                                           /* consisting of: Porthos         */
                                           /*                Athos           */
                                           /*                Aramis          */
index=musketeers~first                     /* Gives index of first item      */
musketeers~insert("D'Artagnan",index) /* Adds D'Artagnan after Porthos  */
                                           /* List is now: Porthos           */
                                           /*              D'Artagnan   */
                                           /*              Athos             */
                                           /*              Aramis            */
/* Alternately, you could use */
musketeers~insert("D'Artagnan",.nil)  /* Adds D'Artagnan before Porthos */
                                           /* List is now:  D'Artagnan  */
                                           /*               Porthos          */
                                           /*               Athos            */
                                           /*               Aramis           */
/* Alternately, you could use */
musketeers~insert("D'Artagnan")       /* Adds D'Artagnan after Aramis   */
                                           /* List is now:  Porthos          */
                                           /*               Athos            */
                                           /*               Aramis           */
                                           /*               D'Artagnan  */

isEmpty

>>-isEmpty----------------------------------------------------><

Returns 1 (true) if the queue is empty. Returns 0 (false) otherwise.

items

>>-items-------------------------------------------------------><

Returns the number of items in the collection.

last

>>-last--------------------------------------------------------><

Returns the index of the last item in the queue or the Nil object if the queue is empty.

makeArray

>>-makeArray---------------------------------------------------><

Returns a single-index array containing the receiver queue items. The array indexes range from 1 to the number of items. The order in which the queue items appear in the array is the same as their queuing order, with the head of the queue as index 1.

next

>>-next(index)-------------------------------------------------><

Returns the index of the item that follows the queue item having index index or returns the Nil object if the item having that index is last in the queue.

peek

>>-peek--------------------------------------------------------><

Returns the item at the head of the queue. If the queue is empty then the method returns the .Nil object. The collection remains unchanged.

previous

>>-previous(index)---------------------------------------------><

Returns the index of the item that precedes the queue item having index index or the Nil object if the item having that index is first in the queue.

pull

>>-pull--------------------------------------------------------><

Returns and removes the item at the head of the queue. If the queue is empty then the method returns the .Nil object

push

>>-push(item)--------------------------------------------------><

Adds the object item to the head of the queue.

put

>>-put(item,index)---------------------------------------------><

Replaces any existing item associated with the specified index with the new item. If the index does not exist in the queue, an error is raised.

queue

>>-queue(item)-------------------------------------------------><

Adds the object item to the tail of the queue.

remove

>>-remove(index)-----------------------------------------------><

Returns and removes from a collection the member item with index index. If no item has index index, this method returns the Nil object and removes no item.

removeItem

>>-removeItem(item)--------------------------------------------><

Removes an item from the queue. If the target item exists at more than one index, the first located item is removed. The return value is the removed item.

supplier

>>-supplier----------------------------------------------------><

Returns a supplier object for the collection. After you have obtained a supplier, you can send it messages (see The Supplier Class) to enumerate all the items that were in the queue at the time of the supplier's creation. The supplier enumerates the items in their queuing order, with the head of the queue first.

Inherited Methods

Methods inherited from the Object class.

Methods inherited from the Collection class.

Methods inherited from the MapCollection class.

new (Class Method)

>>-new---------------------------------------------------------><

This method overrides the new class method from the Object class.

Returns an empty Relation object.

[]

>>-[index]-----------------------------------------------------><

Returns the same item as the at method. See at.

[]=

>>-[index]=item------------------------------------------------><

This method is the same as the put method. See put.

allAt

>>-allAt(index)------------------------------------------------><

Returns a single-index array containing all the items associated with index index. The indexes of the returned array range from 1 to the number of items. Items in the array appear in an unspecified order.

allIndex

>>-allIndex(item)----------------------------------------------><

Returns a single-index array containing all indexes for item item, in an unspecified order (the program should not rely on any order).

allIndexes

>>-allIndexes---------------------------------------------------><

Returns an array of all indices contained in the Relation. If the Relation contains multiple indices of the same value the duplicates will be eliminated from the returned array.

allItems

>>-allItems---------------------------------------------------><

Returns an array of all items contained in the relation.

at

>>-at(index)---------------------------------------------------><

Returns the item associated with index index. If the relation contains more than one item associated with index index, the item returned is unspecified. (The program should not rely on any particular item being returned.) If the relation has no item associated with index index, this method returns the Nil object.

difference

>>-difference(argument)----------------------------------------><

Returns a new collection (of the same class as the receiver) containing only those items that the argument collection does not contain (with the same associated index). The argument can be any collection class object.

empty

>>-empty-------------------------------------------------------><

Removes all items from the relation.

hasIndex

>>-hasIndex(index)---------------------------------------------><

Returns 1 (true) if the collection contains any item associated with index index, or 0 (false).

hasItem

>>-hasItem(item,index)-----------------------------------------><

Returns 1 (true) if the relation contains the member item item (associated with index index, or 0 (false).

index

>>-index(item)-------------------------------------------------><

Returns the index for item item. If there is more than one index associated with item item, the one this method returns is not defined.

intersection

>>-intersection(argument)--------------------------------------><

Returns a new collection (of the same class as the receiver) containing only those items that are in both the receiver collection and the argument collection with the same associated index. The argument can be any collection class object.

isEmpty

>>-isEmpty----------------------------------------------------><

Returns 1 (true) if the relation is empty. Returns 0 (false) otherwise.

items

>>-items-+---------+-------------------------------------------><
         +-(index)-+

Returns the number of relation items with index index. If you specify no index, this method returns the total number of items associated with all indexes in the relation.

makeArray

>>-makeArray---------------------------------------------------><

Returns a single-index array containing the index objects. The array indexes range from 1 to the number of items. The collection items appear in the array in an unspecified order. (The program should not rely on any order.)

put

>>-put(item,index)---------------------------------------------><

Makes the object item a member item of the relation and associates it with index index. If the relation already contains any items with index index, this method adds a new member item item with the same index, without removing any existing member items.

remove

>>-remove(index)-----------------------------------------------><

Returns and removes from a relation the member item with index index. If the relation contains more than one item associated with index index, the item returned and removed is unspecified. If no item has index index, this method returns the NIL object and removes nothing.

removeItem

>>-removeItem(item,index)--------------------------------------><

Returns and removes from a relation the member item item (associated with index index). If value is not a member item associated with index index, this method returns the Nil object and removes no item. If item is the only member with index) then the index) is also removed from the Relation.

subset

>>-subset(argument)--------------------------------------------><

Returns 1 (true) if all items in the receiver collection are also contained in the argument collection with the same associated index; returns 0 (false) otherwise. The argument can be any collection class object.

supplier

>>-supplier--+---------+---------------------------------------><
             +-(index)-+

Returns a supplier object for the collection. After you have obtained a supplier, you can send it messages (see The Supplier Class) to enumerate all the items that were in the collection at the time of the supplier's creation. The supplier enumerates the items in an unspecified order. (The program should not rely on any order.) If you specify index, the supplier enumerates all of the items in the relation with the specified index.

union

>>-union(argument)---------------------------------------------><

Returns a new collection containing all items from the receiver collection and the argument collection. The argument can be any collection class object.

xor

>>-xor(argument)-----------------------------------------------><

Returns a new collection of the same class as the receiver that contains all items from the receiver collection and the argument collection. All index-item pairs that appear in both collections are removed. The argument can be any collection class object.

Examples

/* Use a relation to express parent-child relationships */
family = .relation~new
family["Henry"] = "Peter"    /* Peter is Henry's child   */
family["Peter"] = "Bridget"  /* Bridget is Peter's child */
family["Henry"] = "Jane"     /* Jane is Henry's child    */

/* Show all children of Henry recorded in the family relation */
henrys_kids = family~allAt("Henry")
Say "Here are all the listed children of Henry:"
Do kid Over henrys_kids
  Say " "kid
End

/* Show all parents of Bridget recorded in the family relation */
bridgets_parents = family~allIndex("Bridget")
Say "Here are all the listed parents of Bridget:"
Do parent Over bridgets_parents
  Say " "parent
End

/* Display all the grandparent relationships we know about. */
checked_for_grandkids = .set~new         /* Records those we have checked      */
Do grandparent Over family               /* Iterate for each index in family   */
  If checked_for_grandkids~hasIndex(grandparent)
    Then Iterate                         /* Already checked this one           */
  kids = family~allat(grandparent)       /* Current grandparent's children     */
  Do kid Over kids                       /* Iterate for each item in kids      */
    grandkids = family~allAt(kid)        /* Current kid's children             */
    Do grandkid Over grandkids           /* Iterate for each item in grandkids */
      Say grandparent "has a grandchild named" grandkid"."
    End
  End
  checked_for_grandkids~put(grandparent) /* Add to already-checked set         */
End

Inherited Methods

Methods inherited from the Object class.

Methods inherited from the Collection class.

Methods inherited from the MapCollection class.

Methods inherited from the Table class.

[]=

>>-[index]=item------------------------------------------------><

This method is the same as the put method. See put.

of (Class Method)

       +-,----+
       V      |
>>-of(---item-+-)----------------------------------------------><

Returns a newly created set containing the specified item objects.

intersection

This method overrides the intersection method from the Collection class.

>>-intersection(argument)--------------------------------------><

Returns a new collection (of the same class as the receiver) containing only those items from the receiver whose indexes are in both the receiver collection and the argument collection. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

put

>>-put(item,index)---------------------------------------------><

Makes the object item a member item of the collection and associates it with index index. The new item replaces any existing items associated with index index.

putAll

This method overrides the putAll method from the Map Collection class.

>>-putAll(collection)---------------------------------------><

Adds all items collection to the target set. The collection argument can be any object that supports a supplier method. Items from collection are added using the index values returned by the supplier. The items are added in the order provided by the supplier object. If duplicate indexes exist in collection, the last item provided by the supplier will overwrite previous items with the same index.

subset

This method overrides the subset method from the Collection class.

>>-subset(argument)--------------------------------------------><

Returns 1 (true) if all indexes in the receiver collection are also contained in the argument collection; returns 0 (false) otherwise. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

union

This method overrides the union method from the Collection class.

>>-union(argument)---------------------------------------------><

Returns a new collection of the same class as the receiver that contains all the items from the receiver collection and selected items from the argument collection. This method includes an item from argument in the new collection only if there is no item with the same associated index in the receiver collection and the method has not already included an item with the same index. The order in which this method selects items in argument is unspecified. (The program should not rely on any order.) See also the union method of the Collection (union) and Relation (union) classes. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

xor

This method overrides the xor method from the Collection class.

>>-xor(argument)-----------------------------------------------><

Returns a new collection of the same class as the receiver that contains all items from the receiver collection and the argument collection; all indexes that appear in both collections are removed. The argument can be any collection class object. The argument must also allow all of the index values in the receiver collection.

Inherited Methods

Methods inherited from the Object class.

Methods inherited from the Collection class.

Methods inherited from the MapCollection class.

new (Class Method)

>>-new-+--------+----------------------------------------------><
       +-(name)-+

This method overrides the new class method from the Object class.

Returns a new stem object. If you specify a string name, this value is used to create the derived name of compound variables. The default stem name is a null string.

[]

     +-,---------+
     V           |
>>-[---+-------+-+-]-------------------------------------------><
       +-index-+

Returns the item associated with the specified indexes. Each index is an expression; use commas to separate the expressions. The language processor concatenates the index expression string values, separating them with a period (.), to create a derived index. A null string ("") is used for any omitted expressions. The resulting string references the stem item. If the stem has no item associated with the specified final index, the stem default value is returned. If a default value has not been set, the stem name concatenated with the final index string is returned.

If you do not specify index, the stem default value is returned. If no default value has been assigned, the stem name is returned.

[]=

     +-,---------+
     V           |
>>-[---+-------+-+-]=value-------------------------------------><
       +-index-+

Makes the value a member item of the stem collection and associates it with the specified index. If you specify no index expressions, a new default stem value is assigned. Assigning a new default value will re-initialize the stem and remove all existing assigned indexes.

allIndexes

>>-allIndexes---------------------------------------------------><

Returns an array of all the stem tail names used in the stem.

allItems

>>-allItems---------------------------------------------------><

Returns an array of all items contained in the stem.

at

>>-at(tail)----------------------------------------------------><

Returns the item associated with the specified tail. If the stem has no item associated with the specified tail this method returns the Nil object.

empty

>>-empty-------------------------------------------------------><

Removes all items from the stem.

hasIndex

>>-hasIndex(tail)----------------------------------------------><

Returns 1 (true) if the collection contains any item associated with a stem tail tail, or 0 (false).

hasItem

>>-hasItem(value)----------------------------------------------><

Returns 1 (true) if the collection contains the value at any tail position or otherwise returns 0 (false).

index

>>-index(item)------------------------------------------------><

Returns the index of the specified item within the stem. If the stem does not contain the specified item, .nil is returned.

isEmpty

>>-isEmpty----------------------------------------------------><

Returns 1 (true) if the stem is empty. Returns 0 (false) otherwise.

items

>>-items-------------------------------------------------------><

Returns the number of items in the collection.

makeArray

>>-makeArray---------------------------------------------------><

Returns an array of all stem indexes that currently have an associated value. The items appear in the array in an unspecified order. (The program should not rely on any order.)

put

>>-put(item,tail)----------------------------------------------><

Replaces any existing item associated with the specified tail with the new item item. If the tail does not exist in the stem, an error is raised.

remove

>>-remove(tail)------------------------------------------------><

Returns and removes from the stem the member item with index tail. If no item has index tail, this method returns the Nil object and removes no item.

removeItem

>>-removeItem(item)--------------------------------------------><

Removes an item from the stem. If the target item exists at more than one tail, the first located item is removed. The return value is the removed item.

request

>>-request(classid)--------------------------------------------><

Returns the result of the Stem class makeArray method, if the requested class is Array. For all other classes, request forwards the message to the default value of the stem and returns this result. This method requests conversion to a specific class. All conversion requests except Array are forwarded to the current stem default value.

supplier

>>-supplier----------------------------------------------------><

Returns a supplier object for the stem. After you have obtained a supplier, you can send it messages (see The Supplier Class) to enumerate all the items that were in the stem at the time of the supplier's creation. The supplier enumerates the items in an unspecified order. (The program should not rely on any order.)

unknown

>>-unknown-(messagename,messageargs)---------------------------><

Reissues or forwards to the current stem default value all unknown messages sent to a stem collection. For additional information, see Defining an unknown Method.

Inherited Methods

Methods inherited from the Object class.

Methods inherited from the Collection class.

Methods inherited from the MapCollection class.

new (Class Method)

>>-new---------------------------------------------------------><

This method overrides the new class method from the Object class.

Returns an empty Table object.

[]

>>-[index]-----------------------------------------------------><

Returns the same item as the at method. See at.

[]=

>>-[index]=item------------------------------------------------><

This method is the same as the put method. See put.

allIndexes

>>-allIndexes---------------------------------------------------><

Returns an array of all indices contained in the table.

allItems

>>-allItems---------------------------------------------------><

Returns an array of all items contained in the table.

at

>>-at(index)---------------------------------------------------><

Returns the item associated with index index. If the collection has no item associated with index, this method returns the Nil object.

empty

>>-empty-------------------------------------------------------><

Removes all items from the table.

hasIndex

>>-hasIndex(index)---------------------------------------------><

Returns 1 (true) if the collection contains any item associated with index index, or 0 (false).

hasItem

>>-hasItem(value)----------------------------------------------><

Returns 1 (true) if the collection contains the value at any index position or otherwise returns 0 (false).

index

>>-index(item)------------------------------------------------><

Returns the index of the specified item within the table. If the target item appears at more than one index, the first located index will be returned. If the table does not contain the specified item, .nil is returned.

isEmpty

>>-isEmpty----------------------------------------------------><

Returns 1 (true) if the table is empty. Returns 0 (false) otherwise.

items

>>-items-------------------------------------------------------><

Returns the number of items in the collection.

makeArray

>>-makeArray---------------------------------------------------><

Returns a single-index array containing the index objects. The array indexes range from 1 to the number of items. The collection items appear in the array in an unspecified order. (The program should not rely on any order.)

put

>>-put(item,index)---------------------------------------------><

Makes the object item a member item of the collection and associates it with index index. The new item replaces any existing items associated with index index.

remove

>>-remove(index)-----------------------------------------------><

Returns and removes from a collection the member item with index index. If no item has index index, this method returns the Nil object and removes no item.

removeItem

>>-removeItem(item)--------------------------------------------><

Removes an item from the table. If the target item exists at more than one index, the first located item is removed. The return value is the removed item.

supplier

>>-supplier----------------------------------------------------><

Returns a supplier object for the collection. After you have obtained a supplier, you can send it messages (see The Supplier Class) to enumerate all the items that were in the collection at the time of the supplier's creation. The supplier enumerates the items in an unspecified order. (The program should not rely on any order.)

Sorting non-strings

Sorting is not limited to string value. Any object that inherits the Comparable mixin class and implements a compareTo method can be sorted. For example, consider the following simple class:

    ::class Employee inherit Comparable
    ::method init
      expose id name
      use arg id, name
    ::method id attribute
    ::method name attribute
    ::method compareTo
      expose id
      use arg other
      return id~compareTo(other~id)  -- comparison performed using employee id
    ::method string
      expose name
      use arg name
      return "Employee" name

The Employee class implements its sort order using the employee identification number. When the sort method needs to compare two Employee instances, it will call the compareTo method on one of the instances, passing the second instance as an argument. The compareTo method tells the sort method which of the two instances should be first.

    a = .array~new
    a[1] = .Employee~new(654321, "Fred")
    a[2] = .Employee~new(123456, "George")
    a[3] = .Employee~new(333333, "William")

    a~sort

    do employee over a
       say employee    -- sorted order is "George", "William", "Fred"
    end

Sorting with more than one order

The String class compareTo method only implements a sort ordering for an ascending sort using a strict comparison. Frequently it's desirable to override a class-defined sort order or even to sort items that do not implement a compareTo method. To change the sorting criteria, use the Array sortWith method. The sortWith method takes a single argument, which is a Comparator that implements a compare method. The compare method performs comparisons between pairs of items. Different comparators can be customized for different comparison purposes. For example, the Rexx language provides a DescendingComparator class that will sort items into descending order:

::CLASS 'DescendingComparator' MIXINCLASS Comparator
::METHOD compare
use strict arg left, right
return -left~compareTo(right)

The DescendingComparator merely inverts the result returned by the item compareTo method. Our previous example

myArray = .array~of("Zoe", "Fred", "Xavier", "Andy")
myArray~sortWith(.DescendingComparator~new)

do name over myArray
   say name
end

now displays in the order "Zoe", "Xavier", "Fred", "Andy".

Custom Comparators are simple to create for any sorting purpose. The only requirement is a compare method that knows how to compare pairs of items in some particular manner. For example, to sort our Employee class by name rather employee id, we can use the following simple comparator class:

::CLASS EmployeeNameSorter MIXINCLASS Comparator
::METHOD compare
  use strict arg left, right
  return left~name~compareTo(right~name)  -- do the comparison using the names

Builtin Comparators

ooRexx includes a number of builtin Comparators for common sorting operations.

Stable and Unstable Sorts

The default sorting algorithm is a Quicksort. A Quicksort is a very efficient sorting algorithm that does not require any additional memory to implement. Unfortunately, a Quicksort is also an unstable sort. In an unstable sort, items are not guaranteed to maintain their original positions if they compare equal during the sort. Consider the following simple example:

a = .array~of("Fred", "George", "FRED", "Mike", "fred")
a~sortwith(.caselesscomparator~new)
do name over a
  say name
end

This example displays the 3 occurrences of Fred in the order "Fred", "fred", "FRED", even though they compare equal using a caseless comparison.

ooRexx implements a second sort algorithm that is available using the stableSort and stableSortWith methods. These methods implement a Mergesort algorithm, which is less efficient than the default Quicksort, and requires additional memory to perform the sort. The Mergesort is a stable sort algorithm that will maintain the original relative ordering of equivalent items. Our example above, sorted with stableSortWith, would display "Fred", "FRED", "fred".

The Principles of Operation

A set operation is performed by iterating over the elements of the receiver collection to compare each element of the receiver with each element of the argument collection. The element is defined as the tuple < index,item> (see Determining the Identity of an Item). Depending on the set-operator method and the result of the comparison, an element of the receiver collection is, or is not, included in the resulting collection. A receiver collection that allows for duplicate elements can, depending on the set-operator method, also accept elements of the argument collection after they have been coerced to the type of the receiver collection.

The following examples are to help you understand the semantics of set operations. The collections are represented as a list of elements enclosed in curly brackets. The list elements are separated by a comma.

Set Operations on Collections without Duplicates

Assume that the example sets are A={a,b} and B={b,c,d}. The result of a set operation is another set. The only exception is a subset resulting in a Boolean .true or .false. Using the collection A and B, the different set operators produce the following:

Set-Like Operations on Collections with Duplicates

Assume that the example bags are A={a,b,b} and B={b,b,c,c,d}. The result of any set-like operation is a collection, in this case a bag. The only exception is subset resulting in a Boolean .true or .false. Using the collections A and B, the different set-like operators produce the following:

Determining the Identity of an Item

Set operations require the definition of the identity of an element to determine whether a certain element exists in the receiver collection. The element of a collection is conceived as the tuple <index,item>. The index is used as the identification tag associated with the item. Depending on the collection class, the index is an instance of a particular class, for example, the string class for a directory element, an integer for an array, or any arbitrary class for a relation. The Array class is an exception because it can be multidimensional having more than one index. However, as a collection, it is conceptionally linearized by the set operator.

For collection classes that require unique indexes, namely the Set, Table, Directory, and Stem, an item is identified by its index. For collections of collection classes that allow several items to have the same index, namely the Relation class, an item is identified by both its index and its item. For the Bag and the Set subclasses, where several items can have the same index but index and item must be identical, the item is identified by its index. For Array, List, and Queue classes, the index is derived from an object's position within the collection's order. Items are identified using only item. According to this concept, an item of a collection is identified for the different receiver categories as follows: