1 Class Templates

• A template is a “pattern” for a class or function in which certain type names and constants are left as general template parameters.

• These template parameters are specified in a template header at the start of the class declaration. This template header consists of the keyword “template” followed by the list of replaceable names inside <...>.

• We instantiate a class template when we are ready to use it by supplying the parameter value:

  classTemplateName<myFavoriteType> myVariable;
  

• the resulting class is an instance of the template.

You’ve probably used some class templates before. In CS250/333 you would have made good use of std::vector as a kind of expandable array:

vector<string> names;
// Read names from a file.
ifstream input ("names.txt");
string oneName;
while (input >> oneName) {
   names.push_back (oneName);
}
int numberOfNamesRead = names.size();

But you may or may not have written your own class templates yet.

2 Developing and Using Class Templates

2.1 Templates as a Pattern for Data

Here’s some basic code declaring a typical sequence of strings, together with a function that inserts a data value into the sequence in a specific position.

struct Sequence {
   string* data;
   int numStrings;
};

void add (Sequence& toSequence, string newValue, int position)
{
  for (int i = toSequence.numStrings-1; i >= position; --i)
     toSequence.data[i+1] = toSequence.data[i];
  toSequence.data[position] = newValue;  
  ++toSequence.numStrings;
}

Notice that the code to insert something into this sequence would be the same if it were a sequence of int instead of string, or a sequence of double, or a sequence of PayrollRecords. That’s a sign that this structure might be a good candidate for being turned into a template.

2.1.1 Adding a Template Header

2.2 Instantiating Class Templates

Instantiating class templates is a little different from instantiating function templates. When we have a function template like:

template <class T>
inline const T& min(const T& a, const T& b) {
    return b < a ? b : a;
}

we instantiate it simply by using it:

int i, j, k;
double x, y, z;
  ⋮
k = min(i, j);  // instantiated with T => int
z = min(x, y);  // instantiated with T => double

and the compiler would infer the appropriate replacements for the template parameters by examining the data types of the actual parameters.

But with a class template, we supply the replacements ourselves when we use the class as a type name:

Sequence<PayrollRecord> peopleGettingRaises;

2.3 Templates with Function Members

The example we’ve looked at was pretty simple. In particular, the class we used had no member functions.

Now, let’s start over, this time with some member functions.

struct Sequence {
   string* data;
   int numStrings;

   Sequence (int maxSize);

   void add (string newValue, int position);
};


Sequence::Sequence (int maxSize)
  : numStrings(0)
{
  data = new string[maxSize];
}

void Sequence::add (string newValue, int position)
{
  for (int i = numStrings-1; i >= position; --i)
     data[i+1] = data[i];
  data[position] = newValue;  
  ++numStrings;
}

In this case, I’ve added a constructor that initializes the data fields of the sequence and turned the add function into a member function.

Now, we start by “templatizing” the class declaration and the sequentialInsert function just as we did with sequentialSearch earlier …

2.3.1 Add the Header and Update the Date Type References

2.3.2 Member Functions Become Member Function Templates

Member functions of a template class are, implicitly, templates and so when we supply their bodies, we have to add a template header to indicate what names we are using for the placeholders.

2.4 Tips for Implementing Templates

For more complicated classes, I recommend the following approach to implementing class templates:

1. Start with a working non-template class in which you have used the template parameter names but employed typedef’s to supply replacements for the parameter names.

   (Strictly speaking, this step isn’t necessary. But compilers are able to do more checking for you this way, and often will issue much clearer error messages.)

2. Combine everything from the class’s .h and .cpp files into the .h file.

3. Get rid of the phony typedefs, and replace by a template header at the start of the class, declaring the template parameters. Add a similar template header to each member definition.

4. Change all uses of the class name, except for constructor and destructor names, to theClassName<templateParams>.

5. Check all closely related, nested, and friend classes to see if they need to be converted to templates as well.

3 Example – Matrix

Arrays in C++ may seem like familiar old friends to you. Certainly, you should be comfortable with singly-dimensioned arrays. But many problems require a two-dimensional array.

This can be done working directly with C++ arrays (by having an array of arrays) but initializing and cleaning up after such structures can be awkward and error-prone. As with many data structures, it may be worth putting in the effort to develop a class that provides this capability so that, having put in the effort once to get it working, we can use it with confidence many times in the future.

#ifndef MATRIX_H
#define MATRIX_H

#include <algorithm>
#include <cassert>


class Matrix
//
// Provides a "2-dimensional" rectangular
// array-like structure for indexing using
// a pair of indices.
{
public:
  Matrix();

  Matrix (unsigned theLength1, unsigned theLength2);

  Matrix (const Matrix&);

  ~Matrix();

  const Matrix& operator= (const Matrix&);


  // Indexing into the matrix: What we would like to do is allow
  // myMatrix[i,j]. But C++ allows operator[] only to take a single
  // parameter. But operator() can take whatever parameters we like.
  // So we can write myMatrix(i,j).
  double& operator() (int i1, int i2);
  const double& operator() (int i1, int i2) const;

  unsigned length1() const;
  unsigned length2() const;


  bool operator== (const Matrix&) const;
  
  
private:
  double* data;
  unsigned _length1;
  unsigned _length2;
  
};
#endif

The class itself is pretty straightforward except for the declaration of an operator() function taking two integer parameters. It may seem a bit strange to think of () as an operator, but C++ treats it that way. So we can use this class like this:

Matrix m(4,3);
for (int i = 0; i < 4; ++i)
  {
   m(i,0) = (double)i;
   for (int j = 1; j < 3; ++j)
      m(i,j) = m(i,j-1) + j;
  }
  

The expressions m(i,0), m(i,j), etc., are actually invoking that odd-looking operator. It’s very much like working with an array, except for the use of () rather than [].

Here is the implementation of the matrix class:

#include "matrix.h"

Matrix::Matrix()
  : data(0), _length1(0), _length2(0)
{}


Matrix::Matrix(unsigned theLength1, unsigned theLength2)
  : _length1(theLength1), _length2(theLength2)
{
  data = new double[theLength1*theLength2];
}


Matrix::Matrix(const Matrix& m)
  : _length1(m._length1), _length2(m._length2)
{
  data = new double[theLength1*theLength2];
  copy (m.data, m.data+theLength1*theLength2, data);
}


Matrix::~Matrix()
{
  delete [] data;
}


const Matrix& Matrix::operator= (const Matrix& m)
{
  if (this != &m)
    {
      if (_length1*_length2 < m._length1*m._length2)
        {
          delete [] data;
          data = new double[m._length1*m._length2];
        }
      _length1 = m._length1;
      _length2 = m._length2;
      copy (m.data, m.data+_length1*_length2, data);
    }
  return *this;
}



// Indexing into the matrix: What we would like to do is allow
// myMatrix[i,j]. But C++ allows operator[] only to take a single
// parameter. But operator() can take whatever parameters we like.
// So we can write myMatrix(i,j).
double& Matrix::operator() (int i1, int i2)
{
  assert ((i1 >= 0) && (i1 < _length1));
  assert ((i2 >= 0) && (i2 < _length2));
  return data[i1 + _length1*i2];
}


const double& Matrix::operator() (int i1, int i2) const
{
  assert ((i1 >= 0) && (i1 < _length1));
  assert ((i2 >= 0) && (i2 < _length2));
  return data[i1 + _length1*i2];
}


inline
unsigned Matrix::length1() const
{
  return _length1;
}



inline
unsigned Matrix::length2() const
{
  return _length2;
}


bool Matrix::operator== (const Matrix& m) const
{
  return (_length1 == m._length1)
    && (_length2 == m._length2)
    && equal (data, data+_length1*_length2, m.data);
}

The implementation file for this class is pretty straightforward once you grasp the key idea that a two-dimensional array can be mapped onto a one-dimensional array be taking advantage of the formula $i + j*n_{i}$, which maps each possible (i,j) pair onto a unique integer position, if $n_{i}$ is the number of values in each “row” (i.e., the number of possible values of i). For example, the matrix m declared as

Matrix m(4,3);

would store element (0,0) in position 0, (1,0) in position 1, (0,1) in position 4, (1,1) in position 5, etc.

So we would visualize this matrix as

but implement it as

Now, how to convert this to a more general matrix-of-anything template? To do that, we would take the matrix-of-double code and

1. Start with a working non-template class using template parameter names but employing typedefs to supply replacements for the parameter names.

2. Combine everything from the class’s .h and .cpp files into the .h file.

3. Get rid of the phony typedefs, and replace by a template header at the start of the class, declaring the template parameters. Add a similar template header to each member definition.

4. Change all uses of the class name, except for constructor and destructor names, to the ClassName<templateParams>’.

5. Check all closely related, nested, and friend classes to see if they need to be converted to templates as well.

We’ll take it in steps.

3.1 Start with a working class…

3.2 Combine into .h File

3.3 Add Template Parameters

3.4 Rewrite Class Names

3.5 Check Related Classes

There are no such closely related classes, so we are done.

We can use this class like this:

Matrix<int> m(4,3);
for (int i = 0; i < 4; ++i)
  {
   m(i,0) = i;
   for (int j = 1; j < 3; ++j)
      m(i,j) = m(i,j-1) + j;
  }  

4 Second Example – the pair class

There are times when the template form of a class is more useful than the original class might have been. For example, sometimes we need to “pair up” two different data items just so we can insert them together inside a container.

For example, suppose that we were writing a spellchecker.

A natural ADT in a spell checker would be the notion of a Replacement - a misspelled word and the correct spelling to put in its place.

Now, Replacement is really little more than a pair of strings. Because it’s a fairly basic concept in spell-checker-land, we could give it a descriptive name and give descriptive names to its component pieces, as shown here.

class Replacement 
{
public:
  Replacement () {}
  Replacement (const std::string& missp, 
               const std::string& repl);

  void setMisspelledWord (const std::string& mw);
  std::string getMisspelledWord() const;
  
  void setReplacement (const std::string& r);
  std::string getReplacement() const;
  
  void put (ostream&) const;
  
private:
  std::string _misspelledWord;
  std::string _replacement;
};

Another idea that arises in the spell checker is that of a “word occurrence”, a combination of a word and the location in a document where that word was found.

class WordOccurrence 
{
public:
  typedef std::streampos Location;
  
  WordOccurrence();
  //post: getLexeme()=="" && getLocation()==0

  WordOccurrence (const std::string& lexeme,
                  Location location);

  // A "lexeme" is the string of characters that has been identified
  // as constituting a token.
  std::string getLexeme() const          {return _lexeme;}
  void putLexeme (const std::string& lex) {_lexeme = lex;}

  // The location indicates where in the original file the first character of
  // a token's lexeme was found.
  Location getLocation() const;
  void putLocation (const Location&);


  // Output (mainly for debugging purposes)
  void put (std::ostream&) const;
  
private:
  std::string _lexeme;
  Location _location;
};

This ADT follows much the same pattern as the previous one. It’s really just a container of two items. Unlike Replacement, the two items aren’t of the same type. But we’re basically looking at a simple pair of items, what a mathematician would call a “tuple”.

4.1 Thinking in Terms of Tuples

What’s to stop us from just writing these classes like this?

class Replacement {
public:
  string first;
  string second;

  Replacement () {}
  Replacement (string f, string s):
    first(f), second(s)   {}
};

class WordOccurrence {
public:
  string first;
  Location second;

  WordOccurrence () {}
  WordOccurrence (string f, Location s):
    first(f), second(s)   {}
};

Not much. The names aren’t as nice as our originals, we generally would prefer that all member variables should be private.

So there’s no good reason to really do this …

4.2 The pair Template

… until we consider maybe turning this pattern for containers-of-two-things into a template. Then it becomes one of those little things that’s not earth-shattering, but is still nice to have around.

// from std header file <utility>

template <class T1, class T2>
class pair {
public:
  T1 first;
  T2 second;

  pair () {}
  pair (T1 f, T2 s):
    first(f), second(s)   {}
};

In fact, this pair template is part of the C++ std library, in the header <utility>. (<utility> also defines operators < and == for pairs.)

Using pair, we could, if we wished, redefine Replacement and WordOccurrence as follows

  typedef pair<std::string, std::string> Replacement;
  typedef pair<std::string, std::streampos> WordOccurrence;

Whether or not this is a wise choice is a judgment call. Personally, I would probably not do so, reasoning that these two abstractions are so pervasive in a typical spell checker that the documentation value obtained by accessing their components as “getMisspelledWord()” and “getReplacement()” is greatly preferred to simply “.first” and “.second”.

4.3 Applications of pair<…>

pair gets used in situations where we need to construct a simple container-of-two-things without a lot of fuss.

For example, suppose we wanted to modify our seqSearch template

4.3.1 Returning the element that was found

That’s not too hard when we actually find the value we were looking for. But if we don’t find it (return -1), then what do we do?

We need to return, not just the reference, but also a boolean value indicating whether or not we found it. If we return false, then the calling program will know not to actually look at the reference.

But wait. How can we return the reference and the boolean flag? Isn’t it true that a function can only return one value?

Of course it is. So we have two choices. The simplest choice is to turn one of those would-be return values into a simple output parameter:

template <typename T>
bool seqSearch(const T list[], int listLength, T searchItem, T&  foundValue)
{
  ⋮

4.3.2 Returning Two Things at Once

There are times, though, when we really want that information passed out as a returned value. In those cases, we can use pair.

template <typename T>
pair<bool, const T&> seqSearch(const T list[], int listLength,
                               T searchItem)
{
    int loc;

    for (loc = 0; loc < listLength; loc++)
        if (list[loc] == searchItem)
            return pair<bool, const T&>(true, list[loc]);

    return pair<bool, const T&>(false, list[0]);
}

The rather hefty looking return expressions are, if you look closely, actually invoking the constructor for the data type pair<bool, const T&>, which was declared as the functions return type. That constructor takes two parameters, hence the two expressions inside the ( ).

So we really are returning only one value from our function, but it just so happens that that one value is a pair.

Application code to use this would look something like:

pair<bool, string&> p = sequentialSearch(a, n, x);
if (p.first) 
  cout << "Found "
       << p.second
       << endl;
else
  cout << "Not found"
       << endl;

although, thanks to C++11, we can simplify that first statement:

auto p = sequentialSearch(a, n, x);
if (p.first) 
  cout << "Found "
       << p.second
       << endl;
else
  cout << "Not found"
       << endl;

5 Third Example: array

Wait…“array”? Don’t we already have that?

Yes, but C++ has always had a kind of love-hate relationship with its arrays. It inherited from its parent language, C, the idea that an array is just a pointer that points to repeated instances of its elements instead of just to a single one.

This has some interesting implications, both positive and negative:

• Array declarations can be hard to read. It’s OK for static arrays. If we write

  int c[3];
  

  it’s clear that we want an array. But things get muddier for dynamically allocated arrays. When you see

  int* a;
  

  there’s no way to tell just from looking at it whether a is intended to hold a pointer to a single integer or to an entire array of them. We have to hunt through the code for the place where the memory is actually allocated to find out whether we see

  a = new int;
  

  or

  a = new int[N];
  

• Arrays don’t copy naturally. If I write

  array1 = array2;
  

  that does not copy the array, but copies the address of the array (and if we aren’t careful, losing the old address in array1 and leaving ourselves with a memory leak).

  This has both good and bad points.

  • Copying large arrays can take a lot of time and memory, and it’s not something we want to do indiscriminately.

  • On the other hand, sometimes we really do want to make a copy, and it’s annoying to have to write out an entire loop for an operations that is a simple assignment for almost all other data types in C++.

• Arrays can’t be directly compared for equality.

• Arrays don’t have the same parameter passing options in function calls that other data types have. With other data types, we can pass by copy, giving the function its own copy to examine, modify, and even destroy without affecting our original. When we want an output from the function, or want to avoid the time and memory cost of a copy, we can pass by reference instead.

  For normal C++ arrays, we don’t have the option. We will only send an address – there is no “pass a copy” mechanism.

So, the trend in C++ is to move away from use of ordinary arrays. What we replace them with depends on the main question we always have to ask when working with arrays: do we know the size of the array we want at compilation time, or is the size computed at run time?