Click on the banner to return to the user guide home page.

©Copyright 1996 Rogue Wave Software

Template Overview

To gain some perspective, let's begin with a general example that shows how templates work. We'll explain concepts from the example throughout the section, though you'll probably follow this without difficulty now:

#include <iostream.h>
#include <rw/cstring.h>
#include <rw/regexp.h>
#include <rw/tvdlist.h>

int main()
{
  // Declare a linked-list of strings:
  RWTValDlist<RWCString> stringList;
  RWTValDlist<RWCString>::iterator iter;
  RWCString sentence;

  // Add words to the list:
  stringList.insert("Templates");
  stringList.insert("are");
  stringList.insert("fun");

  // Now use standard iterators to build a sentence:
  iter = stringList.begin();
  while (iter != stringList.end()) {
    sentence += (*iter++ + " ");
  }
  // Replace trailing blank with some oomph!
  sentence(RWCRegexp(" $")) = "!"
  
  // Display the result:
  cout << sentence << endl;
  return 0;
}
 
Output:
  Templates are fun!

The preceding example demonstrates the basic operation of templates. Using the collection class template RWTValDList, we instantiate the object stringList, simply by specifying type RWCString. The template gives us complete flexibility in specifying the type of the list; we don't write code for the object, and Tools.h++ doesn't complicate its design with a separate class RWTValDListofRWCString. Without the template, we would be limited to types provided by the program, or forced to write the code ourselves.

You'll notice that the collection class template RWTValDlist in the example follows a unique format. In Tools.h++, all templates have class names starting with RWT, for Rogue Wave Template, followed by a three letter code:

Isv -- Intrusive lists

Val -- Value-based

Ptr -- Pointer-based

Hence, RWTValOrderedVector<T> is a value-based template for an ordered vector of type-name T. RWTPtrMultiMap<Key,T,C> is a pointer-based template based on the Standard C++ Library multimap class. Special characteristics may also modify the name, as in RWTValSortedDlist<T,C>, a value-based doubly-linked template list that automatically maintains its elements in sorted order.

Tools.h++ collection class templates can be either value-based or pointer-based. Value-based collections use value semantics, maintaining copies of inserted objects and returning copies of retrieved objects. In contrast, pointer-based collections use reference semantics, dealing with pointers to objects as opposed to the objects themselves. See Chapter 10 (Storage Methods of Collection Classes) for other examples of value and reference semantics.

Templates offer you a choice between value and reference semantics. In fact, in most cases, you must choose between a value-based or a pointer-based class; for example, either RWOrderedVectorVal, or RWOrderedVectorPtr.

Your choice depends on the requirements of your application. Pointer-based templates are a good choice for maximizing efficiency for large objects, or if you need to have the same group of objects referred to in several ways, requiring that each collection class point to the target objects, rather than wholly contain them.

An Important Distinction

There is a big difference between a value-based collection of pointers, and a pointer-based collection class. You can save yourself difficulty by understanding the distinction. For example, declaring:

// value-based list of RWDate pointers:
RWTValDlist<RWDate*> myBirthdayV;

gives you a value-based list, where the values are of type pointer to RWDate. The collection class will concern itself only with the pointers, never worrying about the actual RWDate objects they refer to. Now consider:

RWDate* d1 = new RWDate(29,12,55);  // December 29, 1955
myBirthdayV.insert(d1);
RWDate* d2 = new RWDate(29,12,55);  // Different object, same date
cout << myBirthdayV.occurrencesOf(d2);    // Prints 0

The above code prints 0 because the memory locations of the two date objects are different, and the collection class is comparing only the values of the pointers themselves (their addresses) when determining the number of occurrences.

Contrast that with the following:

RWTPtrDlist<RWDate> myBirthdayP;   // pointer-based list of RWDates
RWDate* d1 = new RWDate(29,12,55); // December 29,1955
myBirthdayP.insert(d1);
RWDate* d2 = new RWDate(29,12,55); // Different object, same date
cout << myBirthdayP.occurrencesOf(d2);    // Prints 1

Here the collection class is parameterized by RWDate, not RWDate*, showing that only RWDate objects, not pointers, are of interest to the list. But because it is a pointer-based collection class, communicating objects of interest is done via pointers to those objects. The collection class knows it must dereference these pointers, as well as those stored in the collection class, before comparing for equality.

For a collection class of type-name T, intrusive lists are lists where type T inherits directly from the link type itself[13]. The results are optimal in space and time, but require you to honor the inheritance hierarchy. The disadvantage is that the inheritance hierarchy is inflexible, making it slightly more difficult to use with an existing class. For each intrusive list class, Tools.h++ offers templatized value lists as alternative non-intrusive linked lists.

Note that when you insert an item into an intrusive list, the actual item , not a copy, is inserted. Because each item carries only one link field, the same item cannot be inserted into more than one list, nor can it be inserted into the same list more than once.