Writing Generic Code with Templates
Class Templates
Class templates are useful primarily for containers, or data structures, that store objects. This section uses a running example of a Grid container. In order to keep the examples reasonable in length and simple enough to illustrate specific points, different sections of the chapter will add features to the Grid container that are not used in subsequent sections.
Writing a Class Template
Suppose that you want a generic game board class that you can use as a chessboard, checkers board, Tic- Tac-Toe board, or any other two-dimensional game board. In order to make it general-purpose, you should be able to store chess pieces, checkers pieces, Tic-Tac-Toe pieces, or any type of game piece.
Coding without Templates
Without templates, the best approach to build a generic game board is to employ polymorphism to store generic GamePiece objects. Then, you could subclass the pieces for each game from the GamePiece class. For example, in the chess game, the ChessPiece would be a subclass of GamePiece. Through polymorphism, the GameBoard, written to store GamePieces, can also store ChessPieces. Your class definition might look like similar to the Spreadsheet class from Chapter 9, which used a dynamically allocated two-dimensional array as the underlying grid structure:
// GameBoard.h
class GameBoard
{
public:
// The general-purpose GameBoard allows the user to specify its dimensions GameBoard(int inWidth = kDefaultWidth, int inHeight = kDefaultHeight); GameBoard(const GameBoard& src); // Copy constructor
~GameBoard();
GameBoard &operator=(const GameBoard& rhs); // Assignment operator
void setPieceAt(int x, int y, const GamePiece& inPiece); GamePiece& getPieceAt(int x, int y);
const GamePiece& getPieceAt(int x, int y) const;
int getHeight() const { return mHeight; } int getWidth() const { return mWidth; } static const int kDefaultWidth = 10; static const int kDefaultHeight = 10;
protected:
void copyFrom(const GameBoard& src);
// Objects dynamically allocate space for the game pieces. GamePiece** mCells;
int mWidth, mHeight;
};
getPieceAt() returns a reference to the piece at a specified spot instead of a copy of the piece. The GameBoard serves as an abstraction of a two-dimensional array, so it should provide array access semantics by giving the actual object at an index, not a copy of the object.
273
Chapter 11
This implementation of the class provides two versions of getPieceAt(), one of which returns a reference and one of which returns a const reference. Chapter 16 explains how this overload works.
Here are the method and static member definitions. The implementation is almost identical to the Spreadsheet class from Chapter 9. Production code would, of course, perform bounds checking in setPieceAt() and getPieceAt(). That code is omitted because it is not the point of this chapter.
// GameBoard.cpp #include “GameBoard.h”
const int GameBoard::kDefaultWidth; const int GameBoard::kDefaultHeight;
GameBoard::GameBoard(int inWidth, int inHeight) : mWidth(inWidth), mHeight(inHeight)
{
mCells = new GamePiece* [mWidth]; for (int i = 0; i < mWidth; i++) {
mCells[i] = new GamePiece[mHeight];
}
}
GameBoard::GameBoard(const GameBoard& src)
{
copyFrom(src);
}
GameBoard::~GameBoard()
{
// Free the old memory
for (int i = 0; i < mWidth; i++) { delete[] mCells[i];
}
delete[] mCells;
}
void GameBoard::copyFrom(const GameBoard& src)
{
int i, j;
mWidth = src.mWidth; mHeight = src.mHeight;
mCells = new GamePiece* [mWidth]; for (i = 0; i < mWidth; i++) {
mCells[i] = new GamePiece[mHeight];
}
for (i = 0; i < mWidth; i++) {
for (j = 0; j < mHeight; j++) { mCells[i][j] = src.mCells[i][j];
}
}
}
274
Writing Generic Code with Templates
GameBoard& GameBoard::operator=(const GameBoard& rhs)
{
//Check for self-assignment if (this == &rhs) {
return (*this);
}
//Free the old memory
for (int i = 0; i < mWidth; i++) { delete[] mCells[i];
}
delete[] mCells;
// Copy the new memory copyFrom(rhs);
return (*this);
}
void GameBoard::setPieceAt(int x, int y, const GamePiece& inElem)
{
mCells[x][y] = inElem;
}
GamePiece& GameBoard::getPieceAt(int x, int y)
{
return (mCells[x][y]);
}
const GamePiece& GameBoard::getPieceAt(int x, int y) const
{
return (mCells[x][y]);
}
This GameBoard class works pretty well. Assuming that you wrote a ChessPiece class, you can create GameBoard objects and use them like this:
GameBoard chessBoard(10, 10);
ChessPiece pawn;
chessBoard.setPieceAt(0, 0, pawn);
A Template Grid Class
The GameBoard class in the previous section is nice, but insufficient. For example, it’s quite similar to the Spreadsheet class from chapter 9, but the only way you could use it as a spreadsheet would be to make the SpreadsheetCell class a subclass of GamePiece. That doesn’t make sense because it doesn’t fulfill the is-a principle of inheritance: a SpreadsheetCell is not a GamePiece. It would be nice if you could write a generic grid class that you could use for purposes as diverse as a Spreadsheet or a ChessBoard. In C++, you can do this by writing a class template, which allows you to write a class without specifying one or more types. Clients then instantiate the template by specifying the types they want to use.
275
Chapter 11
The Grid Class Definition
In order to understand class templates, it is helpful to examine the syntax. The following example shows how you can tweak your GameBoard class slightly to make a templatized Grid class. Don’t let the syntax scare you — it’s all explained following the code. Note that the class name has changed from
GameBoard to Grid, and setPieceAt() and getPieceAt() have changed to setElementAt() and getElementAt() to reflect the class’ more generic nature.
// Grid.h
template <typename T> class Grid
{
public:
Grid(int inWidth = kDefaultWidth, int inHeight = kDefaultHeight); Grid(const Grid<T>& src);
~Grid();
Grid<T>& operator=(const Grid<T>& rhs);
void setElementAt(int x, int y, const T& inElem); T& getElementAt(int x, int y);
const T& getElementAt(int x, int y) const; int getHeight() const { return mHeight; } int getWidth() const { return mWidth; } static const int kDefaultWidth = 10; static const int kDefaultHeight = 10;
protected:
void copyFrom(const Grid<T>& src);
T** mCells;
int mWidth, mHeight;
};
Now that you’ve seen the full class definition, take another look at it, one line at a time:
template <typename T>
This first line says that the following class definition is a template on one type. Both template and typename are keywords in C++. As discussed earlier, templates “parameterize” types the same way that functions “parameterize” values. Just as you use parameter names in functions to represent the arguments that the caller will pass, you use type names (such as T) in templates to represent the types that the caller will specify. There’s nothing special about the name T — you can use whatever name you want.
For historical reasons, you can use the keyword class instead of typename to specify template type parameters. Thus, many books and existing programs use syntax like this: template <class T>. However, the use of the word “class” in this context is confusing because it implies that the type must be a class, which is not true. Thus, this book uses typename exclusively.
276
Writing Generic Code with Templates
The template specifier holds for the entire statement, which in this case is the class definition.
Several lines further, the copy constructor looks like this:
Grid(const Grid<T>& src);
As you can see, the type of the src parameter is no longer a const Grid&, but a const Grid<T>&. When you write a class template, what you used to think of as the class name (Grid) is actually the template name. When you want to talk about actual Grid classes or types, you discuss them as instantiations of the Grid class template for a certain type, such as int, SpreadsheetCell, or ChessPiece. You haven’t specified the real type yet, so you must use a stand-in template parameter, T, for whatever type might be used later. Thus, when you need to refer to a type for a Grid object as a parameter to, or return value from, a method you must use Grid<T>. You can see this change with the parameter to, and return value from, the assignment operator, and the parameter to the copyFrom() method.
Within a class definition, the compiler will interpret Grid as Grid<T> where needed. However, it’s best to get in the habit of specifying Grid<T> explicitly because that’s the syntax you use outside the class to refer to types generated from the template.
The final change to the class is that methods such as setElementAt() and getElementAt() now take and return parameters and values of type T instead of type GamePiece:
void setElementAt(int x, int y, const T& inElem); T& getElementAt(int x, int y);
const T& getElementAt(int x, int y) const;
This type T is a placeholder for whatever type the user specifies. mCells is now a T** instead of a GameBoard** because it will point to a dynamically allocated two-dimensional array of Ts, for whatever type T the user specifies.
Template classes can contain inline methods such as getHeight() and getWidth().
The Grid Class Method Definitions
The template <typename T> specifier must precede each method definition for the Grid template. The constructor looks like this:
template <typename T>
Grid<T>::Grid(int inWidth, int inHeight) : mWidth(inWidth), mHeight(inHeight)
{
mCells = new T* [mWidth];
for (int i = 0; i < mWidth; i++) { mCells[i] = new T[mHeight];
}
}
Note that the class name before the :: is Grid<T>, not Grid. You must specify Grid<T> as the class name in all your methods and static data member definitions. The body of the constructor is identical to the GameBoard constructor except that the placeholder type T replaces the GamePiece type.
277
Chapter 11
The rest of the method and static member definitions are also similar to their equivalents in the GameBoard class with the exception of the appropriate template and Grid<T> syntax changes:
template <typename T>
const int Grid<T>::kDefaultWidth;
template <typename T>
const int Grid<T>::kDefaultHeight;
template <typename T> Grid<T>::Grid(const Grid<T>& src)
{
copyFrom(src);
}
template <typename T>
Grid<T>::~Grid()
{
// Free the old memory.
for (int i = 0; i < mWidth; i++) { delete [] mCells[i];
}
delete [] mCells;
}
template <typename T>
void Grid<T>::copyFrom(const Grid<T>& src)
{
int i, j;
mWidth = src.mWidth; mHeight = src.mHeight;
mCells = new T* [mWidth];
for (i = 0; i < mWidth; i++) { mCells[i] = new T[mHeight];
}
for (i = 0; i < mWidth; i++) {
for (j = 0; j < mHeight; j++) { mCells[i][j] = src.mCells[i][j];
}
}
}
template <typename T>
Grid<T>& Grid<T>::operator=(const Grid<T>& rhs)
{
//Check for self-assignment. if (this == &rhs) {
return (*this);
}
//Free the old memory.
for (int i = 0; i < mWidth; i++) { delete [] mCells[i];
}
delete [] mCells;
278
Writing Generic Code with Templates
// Copy the new memory. copyFrom(rhs);
return (*this);
}
template <typename T>
void Grid<T>::setElementAt(int x, int y, const T& inElem)
{
mCells[x][y] = inElem;
}
template <typename T>
T& Grid<T>::getElementAt(int x, int y)
{
return (mCells[x][y]);
}
template <typename T>
const T& Grid<T>::getElementAt(int x, int y) const
{
return (mCells[x][y]);
}
Using the Grid Template
When you want to create grid objects, you cannot use Grid alone as a type; you must specify the type that will be stored in that Grid. Creating an object of a template class for a specific type is called instantiating the template. Here is an example:
#include “Grid.h”
int main(int argc, char** argv)
{
Grid<int> myIntGrid; // Declares a grid that stores ints myIntGrid.setElementAt(0, 0, 10);
int x = myIntGrid.getElementAt(0, 0);
Grid<int> grid2(myIntGrid);
Grid<int> anotherIntGrid = grid2;
return (0);
}
Note that the type of mIntGrid, grid2, and anotherIntGrid is Grid<int>. You cannot store SpreadsheetCells or ChessPieces in these grids; the compiler will generate an error if you try to do so.
The type specification is important: neither of the following two lines compiles:
Grid test; // WILL NOT COMPILE
Grid<> test; // WILL NOT COMPILE
The first causes your compiler to complain with something like, “use of class template requires template argument list.” The second causes it to say something like, “wrong number of template arguments.”
279