Querying collection state

You'll frequently need to answer questions about the state of a given collection. For example you may want to know how many elements are in the collection, or you may want to know how many elements matching a particular value may be found in a given collection. You can also query an array about the high and low index values which can legally be used to access array elements. This basic protocol for such queries is shown in Figure 1.


Count

Counting the total number of elements in a collection is easy. Given a collection simply use Count which takes no arguments and returns a long.

        collection->Count()
A value of 0 is returned if the collection is empty.

NOTE Depending on the type and size of a collection, ::Count may be an expensive operation. Use ::IsEmpty to efficiently determine if a collection contains no elements.

OccurrencesOf

To see how many elements matching a specific object are contained inside a collection, use OccurrencesOf. OccurrencesOf takes a reference to an object of the type the collection is declared to hold, again an instance of TCollectibleLong in this example.

        collection->OccurrencesOf(TCollectibleLong(1))
Two things are worth noting in this expression. First of all, this expression will only match occurrences of TCollectibleLong with a value of 1 if the proper comparator has been defined. This is explained in the previous section. Second, the subexpression TCollectibleLong(1) creates a temporary instance of TCollectibleLong with a value of 1. This temporary instance goes out of scope as soon as the above expression is through evaluating. You can do this because the argument to OccurrencesOf is a reference and not a pointer. Using a temporary avoids having to create and explicitly destroy heap memory when you wish to query a collection for occurrences or search for particular elements. OccurrencesOf returns an integer indicating the number of elements that compare equal (using IsEqual). If no elements match, 0 is returned.

LowBound and HighBound

The member functions LowBound, and HighBound can be used to determine the index value of the first and last array elements respectively. Such values could be used in a for statement to iterate over the elements of a sequenced collection.

          for(int i = collection->LowBound();
          i < collection->HighBound();
          i++) {
              ...
      }
Note that the LowBound need not be 0. This is convenient for arrays which need to start at index 1, or other values. Be aware also that iterators for collections provide a better way to process collection elements, but the focus for now is on use of LowBound and HighBound.

The following program puts all the pieces together and shows calls to member functions which query collection state: Count, OccurrencesOf, LowBound, and HighBound.

Sample program using Count, OccurrencesOf, LowBound, HighBound

      // Copyright (c) 1994 Taligent, Inc. All Rights Reserved.
  
  #ifndef Taligent_COLLECTIONS
  #include <Collections.h>
  #endif
  
  #ifndef _H_STDIO
  #include <stdio.h>
  #endif
  
  int main()
  {
      TMCollectibleComparator<TCollectibleLong> *comparator =
          new TMCollectibleComparator<TCollectibleLong>;
      TArrayOf<TCollectibleLong>* collection =
          new TArrayOf<TCollectibleLong>(comparator, NIL);
  
      collection->Add(new TCollectibleLong(0));
      collection->Add(new TCollectibleLong(1));
      collection->Add(new TCollectibleLong(2));
      collection->Add(new TCollectibleLong(3));
  
      collection->Add(new TCollectibleLong(1));
      collection->Add(new TCollectibleLong(2));
      collection->Add(new TCollectibleLong(1));
  
      printf("Count =>%d\n", collection->Count());
  
      printf("OccurrencesOf 1=>%d\n",
             collection->OccurrencesOf(TCollectibleLong(1)));
      printf("OccurrencesOf 4=>%d\n",
             collection->OccurrencesOf(TCollectibleLong(4)));
  
      TCollectibleLong *p;
      for(int i = collection->LowBound(); i < collection->HighBound(); i++) {
          p = collection->At(i);
          printf("OccurrencesOf collection[%d] (%d) =>%d\n",
                 i,
                 p->GetValue(),
                 collection->OccurrencesOf(*p));
      }
  
      collection->DeleteAll();
      delete collection;
      return 0;
  }
The output follows. The for loop iterates over each of the seven items in the collection. Duplicates are defined by the provided comparator as TCollectibleLong::IsEqual. Thus there are three occurrences of 1, two occurrences of 2, and one occurrence each of 0 and 3. The printf statement inside the loop prints the index number, the contents of the collection at that index, and the occurrences of the item at the current index within the rest of
the collection.

      Count =>7
  OccurrencesOf 1=>3
  OccurrencesOf 4=>0
  OccurrencesOf collection[0] (0) =>1
  OccurrencesOf collection[1] (1) =>3
  OccurrencesOf collection[2] (2) =>2
  OccurrencesOf collection[3] (3) =>1
  OccurrencesOf collection[4] (1) =>3
  OccurrencesOf collection[5] (2) =>2
  OccurrencesOf collection[6] (1) =>3
[Contents] [Previous] [Next]
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.

Generated with WebMaker