Accessing elements

Unless you plan to iterate over an array to process each element in turn, you will probably use random access protocol to retrieve elements. Figure 1 shows a subset of the protocol used to access array elements.


At

The At member function of TArrayOf takes one argument, an numeric key or index indicating the position of the element to be retrieved. The value returned by At is a pointer to a TCollectibleLong.

Assume an array has been set up to contain four elements at indexes 0 through 3 as follows.

          TArrayOf<TCollectibleLong>* collection =
          new TArrayOf<TCollectibleLong>(NIL, NIL);
  
      collection->Add(new TCollectibleLong(0));
      collection->Add(new TCollectibleLong(1));
      collection->Add(new TCollectibleLong(2));
      collection->Add(new TCollectibleLong(3));
You can retrieve the first element with At. First you must declare a pointer to hold the value returned by At.

        TCollectibleLong *p;
Now you can retrieve a pointer to the first element directly through an integer key given as an argument to At.

        p = collection->At(0);
TCollectibleLong defines a member function, GetValue, which returns the long contained inside the TCollectibleLong object pointed to by p.

        long aLong = p->GetValue();
A useful shortcut for printing the value of a TCollectibleLong avoids the declaration of aLong.

        printf("collection[0]=>%d\n", p->GetValue());

First

The First member function of TArrayOf can also be used retrieve the element at index 0. More accurately, First returns the first element in the array with a value other than NIL. Like At, First returns a pointer to a TCollectibleLong.

        p = collection->First();
A short cut for verifying proper values during tests follows.

        printf("First=>%d\n", p->GetValue());
Last provides functionality similar to First. Last returns a pointer to the last element of the collection.

          p = collection->Last();
      printf("Last=>%d\n", p->GetValue());

Last

Last shows something which First does not. Collections have knowledge of their size. In fact collections have knowledge of a number of conditions that yield advantages to using polymorphic collections not readily available to common data structures such as arrays and linked lists. Some of the protocol dealing with this information internal to collections is presented in the following sections on searching for collection elements and querying collection state.

For the sake of context, here is a complete example program that makes use of the protocol presented so far.

Example program using Add, At, First, Last

      // Copyright (c) 1994 Taligent, Inc. All Rights Reserved.
  
  #ifndef Taligent_COLLECTIONS
  #include <Collections.h>
  #endif
  
  #ifndef _H_STDIO
  #include <stdio.h>
  #endif
  
  int main()
  {
      TArrayOf<TCollectibleLong>* collection =
          new TArrayOf<TCollectibleLong>(NIL, NIL);
  
      collection->Add(new TCollectibleLong(0));
      collection->Add(new TCollectibleLong(1));
      collection->Add(new TCollectibleLong(2));
      collection->Add(new TCollectibleLong(3));
  
      TCollectibleLong *p;
  
      p = collection->At(0);
      printf("collection[0]=>%d\n", p->GetValue());
  
      p = collection->At(3);
      printf("collection[3]=>%d\n", p->GetValue());
  
      p = collection->First();
      printf("First=>%d\n", p->GetValue());
  
      p = collection->Last();
      printf("Last=>%d\n", p->GetValue());
  
      collection->DeleteAll(); // caution, only if you own ALL elements
      delete collection;
      return 0;
  }
This is a stand-alone executable program, complete with a main function. Usually CommonPoint programs are built as libraries or as servers and do not include a main. Normally you would never build an example quite like the one above except to test your understanding of certain aspects of collections or to diagnose bugs in a program. The example does, however provide a suitable test framework which can be used to demonstrate some of the fine points of different types of collections.

Destroying collections

Note that two statements are provided to destroy the collection once you are through with it.

          collection->DeleteAll(); // caution, only if you own ALL elements
      delete collection;
The first iterates over the collection to delete the heap memory associated with each element. Only do this if you are the owner of these elements and you have not placed them in any other collections.

CAUTION Avoid calls to DeleteAll. Unless you are sure no elements in the collection are referenced by other system components, you can cause serious run-time errors by calling DeleteAll. You are safer to explicitly remove elements you have placed in a collection yourself and delete them manually.

The second statement deletes heap memory associated with the collection itself. 

        delete collection;
The sample program shows that in order to use collections you must include Collections.h before any of your collection declarations.

          #ifndef Taligent_COLLECTIONS
      #include <Collections.h>
      #endif
This header provides declarations for sets, dictionaries deques, sorted collections, arrays, and all other collection classes presented in this chapter. It's wise to group this #include directive inside conditional directives to ensure that the header is not included more than once.

The following is the output from the previous program.

          collection[0]=>0
      collection[3]=>3
      First=>0
      Last=>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