API Design for C++

explicit Array(int size) :

int Get(int index) const;

void Set(int index, int value);

This class allocates memory, but does not define either a copy constructor or an assignment operator. As a result, the following code will crash when the two variables go out of scope because the destructor of each will try to free the same memory.

Array y = x; // y now shares the same mData pointer as x

Array x(100);

When creating a value object, it is therefore essential that you follow the rule of “The Big Three.” This term was introduced by Marshall Cline in the early nineties and essentially states that there are three member functions that always go together: the destructor, the copy constructor, and the assignment operator (Cline et al., 1998). If you define one of these, you normally need to define the other two as well (declaring an empty virtual destructor is one exception, as it does not perform any actual deallocation). James Coplien referred to this same concept as the orthodox canonical class form (Coplien, 1991).

Tip

If your class allocates resources, you should follow the rule of The Big Three and define a destructor, copy constructor, and assignment operator.

6.2.1 Controlling Compiler-Generated Functions

In the C++98 standard, you have little control over the compiler’s behavior of automatically generating these special functions. For example, as already noted earlier, if you do not declare a copy constructor, the compiler will always generate one for you. However, in the new C++11 specification, you have explicit control over whether the compiler generates, or does not generate, these functions. For instance, the following example specifically tells the compiler to create a private default constructor and a virtual destructor, using the compiler-generated version of these in both cases.

class MyClass

virtual ~MyClass() = default;

MyClass() = default;

You can also tell the compiler to disable certain functions that would otherwise be generated for you. For example, this can be used as another way to make a class be non-copyable as an alternative to the technique described earlier of declaring a private copy constructor and assignment operator.

class NonCopyable

NonCopyable() = default;

NonCopyable(const NonCopyable&) = delete;

NonCopyable & operator=(const NonCopyable&) = delete;

// non-default constructor

Of course, these are C++11-only features. However, some compilers already provide experimental support for this functionality, such as the GNU C++ 4.4 compiler.

6.2.2 Defining Constructors and Assignment

Because writing constructors and operators can be a tricky business, here’s an example that demonstrates the various combinations. It builds on the previous array example and presents a class for storing an array of strings. Because the array is allocated dynamically, you must define a copy constructor and assignment operator, otherwise the memory will be freed twice on destruction if you copy the array. Here’s the declaration of the Array class in the header file:

// default constructor

Array();

explicit Array(int size);

// destructor

~Array();

// copy constructor

Array(const Array &in_array);

// assignment operator

Array &operator = (const Array &in_array);

std::string Get(int index) const;

bool Set(int index, const std::string &str);

and here are sample definitions for the constructors and assignment operator:

#include "array.h"

#include <algorithm>

// default constructor

// non-default constructor

Array::Array(int size) :

mSize(size),

mArray(new std::string[size])

Array::Array(const Array &in_array) :

mSize(in_array.mSize),

mArray(new std::string[in_array.mSize])

std::copy(in_array.mArray, in_array.mArray + mSize, mArray);

Array &Array::operator = (const Array &in_array)

// assignment operator

if (this != &in_array) // check for self assignment

delete [] mArray; // delete current array first

mSize = in_array.mSize;

mArray = new std::string[in_array.mSize];

std::copy(in_array.mArray, in_array.mArray + mSize, mArray);

return *this;

Array a; // default constructor

Given the aforementioned Array class, the following code demonstrates when the various methods will be called.

Array a(10); // non-default constructor

Array b(a); // copy constructor

Array c = a; // copy constructor (because c does not exist yet)

b = c; // assignment operator

Note that there are certain cases where your compiler may elide the call to your copy constructor, for example, if it performs some form of Return Value Optimization (Meyers, 1998).

6.2.3 The Explicit Keyword

You may have noticed use of the explicit keyword before the declaration of the non-default constructor in the Array example I just presented. Adding explicit is a good general practice for any constructor that accepts a single argument. It is used to prevent a specific constructor from being called implicitly when constructing an object. For example, without the explicit keyword, the following code is valid C++:

Array a = 10;

This will call the Array single-argument constructor with the integer argument of 10. However, this type of implicit behavior can be confusing, unintuitive, and, in most cases, unintended. As a further example of this kind of undesired implicit conversion, consider the following function signature:

void CheckArraySize(const Array &array, int size);

Without declaring the single-argument constructor of Array as explicit, you could call this function as

CheckArraySize(10, 10);

This weakens the type safety of your API because now the compiler will not enforce the type of the first argument to be an explicit Array object. As a result, there’s the potential for the user to forget the correct order of arguments and pass them in the wrong order. This is why you should always use the explicit keyword for any single-argument constructors unless you know that you want to support implicit conversion.

You can also declare your copy constructor to be explicit too. This will prevent implicit invocations of the copy constructor, such as passing an object to a function by value or returning an object by value. However, you will still be able to explicitly call the copy constructor using the “Array a = b” or “Array a(b)” syntax.

Tip

Consider using the explicit keyword before the declaration of any constructor with a single argument.

As a side note, the new C++11 specification lets you use the explicit keyword in front of conversion operators as well as constructors. Doing so will prevent those conversion functions from being used for implicit conversions.

6.3 Const Correctness

Const correctness refers to use of the C++ const keyword to declare a variable or method as immutable. It is a compile-time construct that can be used to maintain the correctness of code that shouldn’t modify certain variables. In C++, you can define variables as const, to mean that they should not be modified, and you can also define methods as const, to mean that they should not modify any member variables of the class. Using const correctness is simply good programming practice. However, it can also provide documentation on the intent of your methods, and hence make them easier to use.

Tip

Ensure that your API is const correct.

6.3.1 Method Const Correctness

A const method cannot modify any member variables of the class. In essence, all member variables are treated as const variables inside of a const method. This form of const correctness is indicated by appending the const keyword after the method’s parameter list. There are two principal benefits of declaring a method as const:

1. To advertise the fact that the method will not change the state of the object. As just discussed, this is helpful documentation for users of your API.

2. To allow the method to be used on const versions of an object. A non-const method cannot be called on a const version of an object.

Scott Meyers describes two camps of philosophy about what a const method represents. There’s the bitwise constness camp, which believes that a const method should not change any member variables of a class, and then there’s the logical constness camp, which says that a const method may change a member variable if that change cannot be detected by the user (Meyers, 2005). Your C++ compiler conforms to the bitwise approach. However, there are times when you really want it to behave in the logical constness manner. A classic example is if you want to cache some property of a class because it takes too long to compute. For example, consider a HashTable class that needs to return the number of elements in the hash table very efficiently. As a result, you decide to cache its size and compute this value lazily, on demand. Given the following class declaration:

class HashTable

void Insert(const std::string &str);

int Remove(const std::string &str);

bool Has(const std::string &str) const;

you may want to implement the GetSize() const method as follows:

int HashTable::GetSize() const

if (mSizeIsDirty)

mCachedSize = CalculateSize();

mSizeIsDirty = false;

return mCachedSize;

mutable bool mSizeIsDirty;

Unfortunately, this is not legal C++, as the GetSize() method does actually modify member variables (mSizeIsDirty and mCachedSize). However, these are not part of the public interface: they are internal state that lets us offer a more efficient API. This is the reason why there is the notion of logical constness. C++ does provide a way around this problem with the mutable keyword. Declaring the mCachedSize and mSizeIsDirty variables as mutable states that they can be modified within a const method. Using mutable is a great way to maintain the logical constness of your API instead of removing the const keyword on a member function that really should be declared const.

mutable int mCachedSize;

std::string StringToLower(std::string &str);

Tip

Declare methods and parameters as const as soon as you can. Trying to retrofit const correctness into an API at a later date can be a time-consuming and frustrating activity.

6.3.2 Parameter Const Correctness

Use of the const keyword can also be used to indicate whether you intend for a parameter to be an input or an output parameter, that is, a parameter used to pass some value into a method or a parameter used to receive some result. For example, consider a method such as

It’s not clear from this function signature whether this method will modify the string that you pass in. Clearly it returns a string result, but perhaps it also changes the parameter string. It certainly could do so if it wanted to. If the purpose of this method is to take the parameter and return a lowercase version without affecting the input string, then the simple addition of const can make this unequivocally clear.

std::string StringToLower(const std::string &str);

Now the compiler will enforce the fact that the function StringToLower() will not modify the string that the user passes in. As a result, it’s clear and unambiguous what the intended use of this function is just by looking at the function signature.

Often you’ll find that if you have a const method, then any reference or pointer parameters can also be declared const. While this is not a hard and fast rule, it follows logically from the general promise that the const method does not modify any state. For example, in the following function the root_node parameter can be declared const because it’s not necessary to modify this object in order to compute the result of the const method:

bool Node::IsVisible(const Node &root_node) const;

Tip

When passing a reference or pointer into a const method, think about whether that parameter can be declared const too.

6.3.3 Return Value Const Correctness

When returning the result of a function, the main reason to declare that result to be const is if it references internal state of the object. For example, if you are returning a result by value, then it makes little sense to specify it as const because the returned object will be a copy and hence changing it will not affect any of your class’s internal state.

Alternatively, if you return a pointer or reference to a private data member, then you should declare the result to be const, as otherwise users will be able to modify your internal state without going through your public API. In this case, you must also think about whether the returned pointer or reference will survive longer than your class. If this is possible, you should consider returning a reference-counted pointer, such as a std::shared_ptr, as discussed earlier in Chapter 2.

Therefore, the most common decision you will have with respect to return value const correctness is whether to return the result by value or const reference, that is,

// return by value

std::string GetName() const

return mName;

// return by const reference

const std::string &GetName() const

return mName;

// get a const reference to an internal string

In general, I recommend that you return the result by value as it is safer. However, you may prefer the const reference method in a few cases where performance is critical. Returning by value is safer because you don’t have to worry about clients holding onto references after your object has been destroyed, but also because returning a const reference can break encapsulation.

Tip

Prefer to return the result of a function by value rather than const reference.

On the face of it, our const reference GetName() method given earlier seems acceptable: the method is declared to be const to indicate that it doesn’t modify the state of the object, and the returned reference to the object’s internal state is also declared to be const so that clients can’t modify it. However, a determined client can always cast away the constness of the reference and then modify the underlying private data member directly, such as in the following example:

const std::string &const_name = object.GetName();

// cast away the constness

std::string &name = const_cast<std::string &>(const_name);

// and modify the object’s internal data!

name.clear();

6.4 Templates

Templates provide a versatile and powerful ability to generate code at compile time. They are particularly useful for generating lots of code that looks similar but differs only by type. However, if you decide to provide class templates as part of your public API, several issues should be considered to ensure that you provide a well-insulated, efficient, and cross-platform interface. The following sections address several of these factors.

Note that I will not cover all aspects of template programming, only those features that impact good API design. For a more thorough and in-depth treatment of templates, there are several good books on the market (Alexandrescu, 2001; Josuttis, 1999; Vandevoorde and Josuttis, 2002).

6.4.1 Template Terminology

Templates are an often poorly understood part of the C++ specification, so let’s begin by defining some terms so that we can proceed from a common base. I will use the following template declaration as a reference for the definitions:

std::vector<T> mStack;

• Template Parameters: These names are listed after the template keyword in a template declaration. For example, T is the single template parameter specified in our Stack example given earlier.

This class template describes a generic stack class where you can specify the type of the elements in the stack, T.

• Template Arguments: These entities are substituted for template parameters during specialization. For example, given a specialization Stack<int>, “int” is a template argument.

• Instantiation: This is when the compiler generates a regular class, method, or function by substituting each of the template’s parameters with a concrete type. This can happen implicitly when you create an object based on a template or explicitly if you want to control when the code generation happens. For example, the following lines of code create two specific stack instances and will normally cause the compiler to generate code for these two different types.

Stack<int> myIntStack;

Stack<std::string> myStringStack;

• Implicit Instantiation: This is when the compiler decides when to generate code for your template instances. Leaving the decision to the compiler means that it must find an appropriate place to insert the code, and it must also make sure that only one instance of the code exists to avoid duplicate symbol link errors. This is a non-trivial problem and can cause extra bloat in your object files or longer compile and link times to solve. Most importantly for API design, implicit instantiation means that you have to include the template definitions in your header files so that the compiler has access to the definitions whenever it needs to generate the instantiation code.

• Explicit Instantiation: This is when the programmer determines when the compiler should generate the code for a specific specialization. This can make for much more efficient compilation and link times because the compiler no longer needs to maintain bookkeeping information for all of its implicit instantiations. However, the onus is then placed on the programmer to ensure that a particular specialization is explicitly instantiated once and only once. From an API perspective, explicit instantiation allows us to move the template implementation into the .cpp file, and so hide it from the user.

• Lazy Instantiation: This describes the standard implicit instantiation behavior of a C++ compiler wherein it will only generate code for the parts of a template that are actually used. For example, given the previous two instantiations, if you never called IsEmpty() on the myStringStack object, then the compiler would not generate code for the std::string specialization of that method. This means that you can instantiate a template with a type that can be used by some, but not all, methods of a class template. For example, say one method uses the >= operator, but the type you want to instantiate does not define this operator. This is fine as long as you don’t call the particular method that attempts to use the >= operator.

• Specialization: When a template is instantiated, the resulting class, method, or function is called a specialization. More specifically, this is an instantiated (or generated) specialization. However, the term specialization can also be used when you provide a custom implementation for a function by specifying concrete types for all the template parameters. I gave an example of this earlier in the API Styles chapter, where I presented the following implementation of the Stack::Push() method, specialized for integer types. This is called an explicit specialization.

template <>

void Stack<int>::Push(int val)

// integer specific push implementation

• Partial Specialization: This is when you provide a specialization of the template for a subset of all possible cases. That is, you specialize one feature of the template but still allow the user to specify other features. For example, if your template accepts multiple parameters, you could partially specialize it by defining a case where you specify a concrete type for only one of the parameters. In our Stack example with a single template parameter, you could partially specialize this template to specifically handle pointers to any type T. This still lets users create a stack of any type, but it also lets you write specific logic to handle the case where users create a stack of pointers. This partially specialized class declaration might look like:

class Stack<T *>

void Push(T *val);

T *Pop();

std::vector<T *> mStack;

6.4.2 Implicit Instantiation API Design

If you want to allow your clients to instantiate your class templates with their own types, then you need to use implicit template instantiation. For example, if you provide a smart pointer class template, smart_pointer<T>, you do not know ahead of time what types your clients will want to instantiate it with. As a result, the compiler needs to be able to access the definition of the template when it is used. This essentially means that you must expose the template definition in your header files. This is the biggest disadvantage of the implicit instantiation approach in terms of robust API design. However, even if you can’t necessarily hide the implementation details in this situation, you can at least make an effort to isolate them.

Given that you need to include the template definition in your header file, it’s easy, and therefore tempting, to simply inline the definitions directly within the class definition. This is a practice that I have already classified as poor design, and that assertion is still true in the case of templates. Instead, I recommend that all template implementation details be contained within a separate implementation header, which is then included by the main public header. Using the example of our Stack class template, you could provide the main public header:

std::vector<T> mStack;

// isolate all implementation details within a separate header

#include "stack_priv.h"

Then the implementation header, stack_priv.h, would look as follows:

// stack_priv.h

#ifndef STACK_PRIV_H

#define STACK_PRIV_H

void Stack<T>::Push(T val)

mStack.push_back(val);

T val = mStack.back();

mStack.pop_back();

return val;

bool Stack<T>::IsEmpty() const

return mStack.empty();

template class Stack<int>;

This technique is used by many high-quality template-based APIs, such as various Boost headers. It has the benefit of keeping the main public header uncluttered by implementation details while isolating the necessary exposure of internal details to a separate header that is clearly designated as containing private details. (The same technique can be used to isolate consciously inlined function details from their declarations.)

The technique of including template definitions in header files is referred to as the Inclusion Model (Vandevoorde and Josuttis, 2002). It’s worth noting that there is an alternative to this style called the Separation Model. This allows the declaration of a class template in a .h file to be preceded with the export keyword. Then the implementation of the template methods can appear in a .cpp file. From an API design perspective, this is a far more preferable model, as it would allow us to remove all implementation details from public headers. However, this part of the C++ specification is very poorly supported by most compilers. In particular, neither GNU C++ 4.3 nor Microsoft Visual C++ 9.0 compilers support the export keyword. You should therefore avoid this technique in your APIs to maximize the portability of your API.

6.4.3 Explicit Instantiation API Design

If you want to provide only a predetermined set of template specializations for your API and disallow your users from creating further ones, then you do in fact have the option of completely hiding your private code. For example, if you have created a 3D vector class template, Vector3D<T>, you may only want to provide specializations of this template for int, short, float, and double, and you may feel that it’s not necessary to let your users create further specializations.

In this case, you can put your template definitions into a .cpp file and use explicit template instantiation to instantiate those specializations that you wish to export as part of your API. The template keyword can be used to create an explicit instantiation. For instance, using our Stack template example given previously, you could create explicit instantiations for the type int with the statement:

This will cause the compiler to generate the code for the int specialization at this point in the code. As a result, it will subsequently no longer attempt to implicitly instantiate this specialization elsewhere in the code. Consequently, using explicit instantiation can also help increase build times.

Let’s take a look at how you can organize your code to take advantage of this feature. Our stack.h header file looks almost exactly the same as before, just without the #include "stack_priv.h" line:

std::vector<T> mStack;

Now you can contain all of the implementation details for this template in an associated .cpp file:

// stack.cpp

#include "stack.h"

#include <string>

void Stack<T>::Push(T val)

mStack.push_back(val);

T val = mStack.back();

mStack.pop_back();

return val;

bool Stack<T>::IsEmpty() const

return mStack.empty();

// explicit template instantiations

template class Stack<int>;

template class Stack<double>;

template class Stack<std::string>;

The important lines here are the last three, which create explicit instantiations of the Stack class template for the types int, double, and std::string. The user will not be able to create further specializations (and the compiler will not be able to create implicit instantiations for the user either) because the implementation details are hidden in our .cpp file. However, our implementation details are now hidden successfully in our .cpp file.

To indicate to your users which template specializations they can use (i.e., which ones you have explicitly instantiated for them), you could add a few typedefs to the end of your public header, such as

typedef Stack<int> IntStack;

typedef Stack<double> DoubleStack;

typedef Stack<std::string> StringStack;

It’s worth noting that by adopting this template style, not only do you (and your clients) get faster builds due to the removal of the overhead of implicit instantiation, but also, by removing the template definitions from your header, you reduce the #include coupling of your API and reduce the amount of extra code that your clients’ programs must compile every time they #include your API headers.

Tip

Prefer explicit template instantiation if you only need a predetermined set of specializations. Doing so lets you hide private details and can reduce build times.

It’s also worth noting that most compilers provide an option to turn off implicit instantiation completely, which may be a useful optimization if you only plan to use explicit instantiation in your code. This option is called -fno-implicit-templates in the GNU C++ and Intel ICC compilers.

In the new C++11 specification, support has been added for extern templates. That is, you will be able to use the extern keyword to prevent the compiler from instantiating a template in the current translation unit. In fact, support for this feature is already in some current compilers, such as the GNU C++ compiler. With the addition of extern templates, you have the ability to force the compiler to instantiate a template at a certain point and to tell it not to instantiate the template at other points. For example,

// explicitly instantiate the template here

template class Stack<int>;

// do not instantiate the template here

extern template class Stack<int>;

6.5 Operator Overloading

In addition to overloading functions, C++ allows you to overload many of the operators for your classes, such as +, *=, or []. This can be very useful to make your classes look and behave more like built-in types and also to provide a more compact and intuitive syntax for certain methods. For example, instead of having to use syntax such as

add(add(mul(a,b), mul(c,d)), mul(a,c))

you could write classes that support the following syntax:

a*b + c*d + a*c

Of course, you should only use operator overloading in cases where it makes sense, that is, where doing so would be considered natural to the user of your API and not violate the rule of least surprise. This generally means that you should preserve the natural semantics for operators, such as using the + operator to implement an operation analogous to addition or concatenation. You should also avoid overloading the operators &&, ||, & (unary ampersand), and , (comma) as these exhibit behaviors that may surprise your users, such as short-circuited evaluation and undefined evaluation order (Meyers 1998; Sutter and Alexandrescu, 2004).

As covered earlier in this chapter, a C++ compiler will generate a default assignment operator (=) for your class if you don’t define one explicitly. However, if you wish to use any other operators with your objects, then you must explicitly define them, otherwise you’ll end up with link errors.

6.5.1 Overloadable Operators

Certain operators cannot be overloaded in C++, such as ., .*, ?:, and ::, the preprocessor symbols # and ##, and the sizeof operator. Of the remaining operators that you can overload for your own classes, there are two main categories:

1. Unary Operators: These operators act on a single operand. The list of unary operators includes:

2. Binary Operators: These operators act on two operands. The list of binary operators includes:

6.5.2 Free Operators versus Member Operators

Operators can be defined either as members of your class or as free functions. Some operators have to be defined as class members, but others can be defined either way. For example, the following code illustrates the += operator defined as a class member:

class Currency

explicit Currency(unsigned int value);

// method form of operator+=

Currency &operator +=(const Currency &other);

unsigned int GetValue() const;

The following code shows an equivalent API using a free function version of the operator:

class Currency

explicit Currency(unsigned int value);

unsigned int GetValue() const;

// free function form of operator+=

Currency &operator +=(Currency &lhs, const Currency &rhs);

This section covers some best practices for whether you should make your operators free functions or methods.

To begin with, the C++ standard requires that the following operators be declared as member methods to ensure that they receive an lvalue (an expression that refers to an object) as their first operand:

- = Assignment

- [] Subscript

- -> Class member access

- ->* Pointer-to-member selection

- () Function call

- (T) Conversion, i.e., C-style cast

- new/delete

The remaining overloadable operators can be defined as either free functions or class methods. From the perspective of good API design, I recommend that you favor the free function version over the class method version of defining an operator. There are two specific reasons for this.

1. Operator symmetry. If a binary operator is defined as a class method, it must have an object to be applied to as the left-hand operand. Taking the * operator as an example, this means that your users would be able to write expressions such as “currency * 2” (assuming that you’ve defined a non-explicit constructor or a specific * operator for the int type) but not “2 * currency” because 2.operator*(currency) does not make sense. This breaks the commutative property of the operator that your users will expect, that is, that x * y should be the same as y * x. Note also that declaring the * operator as a free function lets you benefit from implicit type conversions for both left- and right-hand operands if you do not declare your constructors as explicit.

2. Reduced coupling. A free function cannot access the private details of a class. It is therefore less coupled to the class because it can only access the public methods. This is a general API design statement that was covered in Chapter 2: turn a class method that does not need to access private or protected members into a free function to reduce the degree of coupling in your API (Meyers, 2000; Tulach, 2008).

Having stated this general preference toward free function operators, I now present the exception to this rule: If your operator must access private or protected members of your class, then you should define the operator as a method of the class. I make this exception because otherwise you would have to declare the free function operator to be a friend of your class. As discussed later in this chapter, adding friends to your classes is a greater evil. One specific reason I’ll mention here is that your clients cannot change the friendship list of your classes, so they could not add new operators in this same way.

Tip

Prefer declaring operators as free functions unless the operator must access protected or private members or the operator is one of =, [], ->, ->*, (), (T), new, or delete.

6.5.3 Adding Operators to a Class

Let’s develop the Currency class a little further to make the aforementioned points more concrete. The += operator modifies the contents of an object, and because we know that all member variables should be private, you will most likely need to make the += operator be a member method. However, the + operator does not modify the left-hand operand. As such, it shouldn’t need access to private members and can be made a free function. You also need to make it a free function to ensure that it benefits from symmetry behavior, as described earlier. In fact, the + operator can be implemented in terms of the += operator, which allows us to reuse code and provide more consistent behavior. It also reduces the number of methods that might need to be overloaded in derived classes.

Currency operator +(const Currency &lhs, const Currency &rhs)

return Currency(lhs) += rhs;

bool operator ==(const Currency &lhs, const Currency &rhs)

Obviously, the same technique applies to the other arithmetic operators, such as -, -=, *, *=, /, and /=. For example, *= can be implemented as a member function, whereas * can be implemented as a free function that uses the *= operator.

As for the relational operators ==, !=, <, <=, >, and >=, these must also be implemented as free functions to ensure symmetrical behavior. In the case of our Currency class, you can implement these using the public GetValue() method. However, if these operators should need access to the private state of the object, there is a way to resolve this apparent dilemma. In this case, you can provide public methods that test for the equality and less than conditions such as IsEqualTo() and IsLessThan(). All relational operators could then be implemented in terms of these two primitive functions (Astrachan, 2000).

return lhs.IsEqualTo(rhs);

bool operator !=(const Currency &lhs, const Currency &rhs)

return ! (lhs == rhs);

bool operator <(const Currency &lhs, const Currency &rhs)

return lhs.IsLessThan(rhs);

bool operator <=(const Currency &lhs, const Currency &rhs)

return ! (lhs > rhs);

bool operator >(const Currency &lhs, const Currency &rhs)

return rhs < lhs;

bool operator >=(const Currency &lhs, const Currency &rhs)

return rhs <= lhs;

explicit Currency(unsigned int value);

The last operator I will consider here is <<, which I will use for stream output (as opposed to bit shifting). Stream operators have to be declared as free functions because the first parameter is a stream object. Again, you can use the public GetValue() method to make this possible. However, if the stream operator did need to access private members of your class, then you could create a public ToString() method for the << operator to call as a way to avoid using friends.

Putting all of these recommendations together, here’s what the operators of our Currency class might look like:

~Currency();

Currency(const Currency &obj);

Currency &operator =(const Currency &rhs);

Currency &operator +=(const Currency &rhs);

Currency &operator -=(const Currency &rhs);

Currency &operator *=(const Currency &rhs);

Currency &operator /=(const Currency &rhs);

unsigned int GetReal() const;

Currency operator +(const Currency &lhs, const Currency &rhs);

Currency operator -(const Currency &lhs, const Currency &rhs);

Currency operator *(const Currency &lhs, const Currency &rhs);

Currency operator /(const Currency &lhs, const Currency &rhs);

bool operator ==(const Currency &lhs, const Currency &rhs);

bool operator !=(const Currency &lhs, const Currency &rhs);

bool operator <(const Currency &lhs, const Currency &rhs);

bool operator >(const Currency &lhs, const Currency &rhs);

bool operator <=(const Currency &lhs, const Currency &rhs);

bool operator >=(const Currency &lhs, const Currency &rhs);

std::ostream& operator <<(std::ostream &os, const Currency &obj);

std::istream& operator >>(std::istream &is, Currency &obj);

6.5.4 Operator Syntax

Table 6.1 provides (i) a list of operators that you can overload in your classes and (ii) the recommended syntax for declaring each operator so that they have the same semantics as their built-in counterparts. Table 6.1 omits operators that you cannot overload, as well as those stated previously that you should not overload, such as && and ||. Where an operator can be defined as either a free function or a class method, I present both forms, but I list the free function form first as you should generally prefer this form, unless the operator needs access to protected or private members.

Table 6.1

List of operators and syntax for declaring these in your APIs

6.5.5 Conversion Operators

A conversion operator provides a way for you to define how an object can be converted automatically to a different type. A classic example is to define a custom string class that can be passed to functions that accept a const char * pointer, such as the standard C library functions strcmp() or strlen().

class MyString

MyString(const char *string);

// convert MyString to a C-style string

operator const char *() { return mBuffer; }

// MyString objects get automatically converted to const char *

MyString mystr("Haggis");

int same = strcmp(mystr, "Edible");

int len = strlen(mystr);

Note that the conversion operator does not specify a return value type. That’s because the type is inferred by the compiler based on the operator’s name. Also, note that conversion operators take no arguments. In the C++11 standard, it’s also possible to prefix a conversion operator with the explicit keyword to prevent its use in implicit conversions.

Tip

Add conversion operators to your classes to let them take advantage of automatic type coercion.

6.6 Function Parameters

The following sections address a couple of C++ best practices relating to the use of function parameters. This includes when you should use pointers instead of references to pass objects into a function and when you should use default arguments.

6.6.1 Pointer versus Reference Parameters

When specifying parameters for your functions you can choose between passing them as value parameters, pointers, or references. For example,

bool GetColor(int r, int g, int b); // pass by value

bool GetColor(int &r, int &g, int &b); // pass by reference

bool GetColor(int *r, int *g, int *b); // pass by pointer

You pass a parameter as a reference or pointer when you want to receive a handle for the actual object rather than a copy of the object. This is done either for performance reasons (as discussed in Chapter 7) or so that you can modify the client’s object. C++ compilers normally implement references using pointers so they are often the same thing under the hood. However, there are several practical differences, such as

• References are used as if they were a value, for example, object.Function() instead of object->Function().

• A reference must be initialized to point to an object and does not support changing the referent object after initialization.

• You cannot take the address of a reference as you can with pointers. Using the & operator on a reference returns the address of the referent object.

• You can’t create arrays of references.

The question of whether to use a pointer or a reference for a parameter is really a matter of personal taste. However, I will suggest that in general you should prefer the use of references over pointers for any input parameters. This is because the calling syntax for your clients is simpler and you do not need to worry about checking for NULL values (because references cannot be NULL). However, if you need to support passing NULL or if you’re writing a plain C API, then you must obviously use a pointer.

In terms of output parameters (parameters that your function may modify), some engineers dislike the fact that the use of references does not indicate to your clients the fact that a parameter may be changed. For example, the reference and pointer versions of the GetColor() function given earlier can be called by clients as follows:

object.GetColor(red, green, blue); // pass by reference

object.GetColor(&red, &green, &blue); // pass by pointer

In both of these cases, the GetColor() function can modify the value of the red, green, and blue variables. However, the pointer version makes this fact explicit due to the required use of the & operator. For this reason, APIs like the Qt framework prefer to represent output parameters using pointers instead of references. If you decide to follow this convention too—which I recommend—then by implication all of your reference parameters should be const references.

Tip

Prefer the use of const references over pointers for input parameters where feasible. For output parameters, consider using pointers over non-const references to indicate explicitly to the client that they may be modified.

6.6.2 Default Arguments

Default arguments are a very useful tool to reduce the number of methods in your API and to provide implicit documentation on their use. They can also be used to extend an API call in a backward-compatible fashion so that older client code will still compile, but newer code can optionally provide additional arguments (although it should be noted that this will break binary compatibility, as the mangled symbol name for the method will necessarily change). As an example, consider the following code fragment for a Circle class:

class Circle

Circle(double x=0, double y=0, double radius=10.0);

Circle c4(2.3, 5.6, 1.5);

In this case, the user is able to construct a new Circle object in a number of different ways, supplying as much detail as needed. For example,

Circle c1();

Circle c2(2.3);

Circle c3(2.3, 5.6);

However, there are two issues to be aware of with this example. First, it supports combinations of arguments that don’t make logical sense, such as supplying an x argument but no y argument. Also, the default values will be compiled into your client’s programs. This means that your clients must recompile their code if you release a new version of the API with a different default radius. In essence, you are exposing the behavior of the API when you do not explicitly specify a radius value.

To illustrate why this might be bad, consider the possibility that you later add support for the notion of different default units, letting the user switch between values specified in meters, centimeters, or millimeters. In this case, a constant default radius of 10.0 would be inappropriate for all units.

An alternative approach is to provide multiple overloaded methods instead of using default arguments. For example,

Circle(double x, double y);

Circle(double x, double y, double radius);

#define SETUP_NOISE(i,b0,b1,r0,r1)\

Using this approach, the implementation of the first two constructors can use a default value for the attributes that are not specified. But importantly, these default values are specified in the .cpp file and are not exposed in the .h file. As a result, a later version of the API could change these values without any impact on the public interface.

Tip

Prefer overloaded functions to default arguments when the default value would expose an implementation constant.

Not all instances of default arguments need to be converted to overloaded methods. In particular, if the default argument represents an invalid or empty value, such as defining NULL as the default value for a pointer or "" for a string argument, then this usage is unlikely to change between API versions. However, if you have cases where you are hardcoding specific constant values into your API that might change in future releases, then you should convert these cases to use the overloaded method technique instead.

As a performance note, you should also try to avoid defining default arguments that involve constructing a temporary object because these will be passed into the method by value and can therefore be expensive.

6.7 Avoid #define for Constants

The #define preprocessor directive is essentially used to substitute one string with another string in your source code. However, its use is generally frowned upon in the C++ community for a number of good reasons (Cline et al., 1998; DeLoura, 2001; Meyers, 2005). Many of these reasons are related to the subtle problems that can happen if you use #define to specify code macros that you wish to insert into multiple places, such as

t = vec[i] + 0x1000;\

b0 = (lltrunc(t)) & 0xff;\

b1 = (b0+1) & 0xff;\

r0 = t - lltrunc(t);\

r1 = r0 - 1.f;

However, you should never be using #define in this way for your public API headers because of course it leaks implementation details. If you want to use this technique in your .cpp files, and you understand all of the idiosyncrasies of #define, then go ahead, but never do this in your public headers.

That just leaves the use of #define to specify constants for your API, such as

#define MORPH_FADEIN_TIME 0.3f

#define MORPH_IN_TIME 1.1f

#define MORPH_FADEOUT_TIME 1.4f

You should avoid even this usage of #define (unless you are writing a pure C API of course) because of the following reasons.

1. No typing. A #define does not involve any type checking for the constant you are defining. You must therefore make sure that you explicitly specify the type of the constant you are defining to avoid any ambiguities, such as the use of the “f” suffix on single-precision floating-point constants. If you defined a floating-point constant as simply “10,” then it may be assumed to be an integer in certain cases and cause undesired math rounding errors.

2. No scoping. A #define statement is global and is not limited to a particular scope, such as within a single class. You can use the #undef preprocessor directive to undefine a previous #define, but this makes little sense for declaring a constant that you want your clients to be able to use.

3. No access control. You cannot mark a #define as public, protected, or private. It is essentially always public. You therefore cannot use #define to specify a constant that should only be accessed by derived classes of a base class that you define.

4. No symbols. In the example given earlier, symbolic names such as MORPH_IN_TIME may be stripped from your code by the preprocessor, and as such the compiler never sees this name and cannot enter it into the symbol table (Meyers, 2005). This can hide valuable information from your clients when they try to debug code using your API because they will simply see the constant value used in the debugger, without any descriptive name.

The preferred alternative to using #define to declare API constants is to declare a const variable. I will discuss some of the best practices of declaring constants in the later chapter on performance, as it’s possible to declare const variables in a way that adds bloat to your clients programs. For now, I will simply present a good conversion of the earlier #define example to be

class Morph

static const float FadeInTime;

static const float InTime;

static const float FadeOutTime;

#define RIGHT_JUSTIFIED 1

where the actual values of these constants are specified in the associated .cpp file. (If you really want your users to know what the values of these constants are, then you can tell them this information in the API documentation for the Morph class.) Note that this representation does not suffer from any of the problems listed previously: the constants are typed as floats, scoped to the Morph class, marked explicitly as publicly accessible, and will generate entries in the symbol table.

Tip

Use static const data members to represent class constants instead of #define.

A further use of #define is to provide a list of possible values for a given variable. For example,

#define LEFT_JUSTIFIED 0

#define CENTER_JUSTIFIED 2

#define FULL_JUSTIFIED 3

This is better expressed using enumerated types via the enum keyword. Using enums gives you better type safety because the compiler will now ensure that you set any enum values with the symbolic name and not directly as an integer (unless you explicitly cast an int to your enum type of course). This also makes it more difficult to pass illegal values, such as –1 or 23 in the example given earlier. You can turn the aforementioned #define lines into an enumerated type as follows:

enum JustificationType {

6.8 Avoid Using Friends

In C++, friendship is a way for your class to grant full access privileges to another class or function. The friend class or function can then access all protected and private members of your class. This can be useful when you need to split up your class into two or more parts but you still need each part to access private members of the other part. It’s also useful when you need to use an internal visitor or callback technique. That is, when some other internal class in your implementation code needs to call a private method in your class.

One alternative would be to expose data members and functions that need to be shared, converting them from private to public so that the other class can access them. However, this would mean that you are exposing implementation details to your clients; details that would not otherwise be part of your logical interface. From this point of view, friends are a good thing because they let you open up access to your class to only specific clients. However, friendship can be abused by your users, allowing them to gain full access to your class’s internal details.

For example, consider the following class that specifies a single Node as part of a Graph hierarchy. The Graph may need to perform various iterations over all nodes and therefore needs to keep track of whether a node has been visited already (to handle graph cycles). One way to implement this would be to have the Node object hold the state for whether it has been visited already, with accessors for this state. Because this is purely an implementation detail, you don’t want to expose this functionality in the public interface. Instead, you declare it as private, but explicitly give the Graph object access to the Node object by declaring it as a friend.

bool IsVisited() const;

// define your own Graph class

This seems okay on the face of it: you have kept the various *Visited() methods as private and only permitted the Graph class to access our internal details. However, the problem with this is that the friendship offer is based on the name of the other class only. It would therefore be possible for clients to create their own class called Graph, which would then be able to access all protected and private members of Node (Lakos, 1996). The following client program demonstrates how easy it is to perform this kind of access control violation.

#include "node.h"

class Graph

void ViolateAccess(Node *node)

// call a private method in Node

// because Graph is a friend of Node

node −> SetVisited();

local_graph.ViolateAccess(&node);

So, by using friends you are leaving a gaping hole in your API that could be used to circumvent your public API boundary and break encapsulation.

In the example just given, a better solution that obviates the need to use friends would be for the Graph object to maintain its own list of nodes that it has already visited, for example, by maintaining a std::set<Node *> container, rather than storing the visited state in the individual nodes themselves. This is also a better conceptual design because the information about whether another class has processed a Node is not inherently an attribute of the Node itself.

Tip

Avoid using friends. They tend to indicate a poor design and can allow users to gain access to all protected and private members of your API.

6.9 Exporting Symbols

In addition to language-level access control features (public, private, and protected), there are two related concepts that allow you to expose symbols in your API at the physical file level. These are:

1. External linkage.

2. Exported visibility.

The term external linkage means that a symbol in one translation unit can be accessed from other translation units, whereas exporting refers to a symbol that is visible from a library file such as a DLL. Only external linkage symbols can be exported.

Let’s look at external linkage first. This is the first stage that determines whether your clients can access symbols in your shared libraries. Specifically, global (file scope) free functions and variables in your .cpp file will have external linkage unless you take steps to prevent this. For example, consider the following code that might appear in one of your .cpp files:

const int INTERNAL_CONSTANT = 42;

std::string Filename = "file.txt";

void FreeFunction()

std::cout << "Free function called" << std::endl;

extern void FreeFunction();

Even though you have contained the use of these functions and variables inside a .cpp file, a resourceful client could easily gain access to these symbols from their own programs (ignoring symbol exporting issues for the moment). They could then call your global functions directly and modify your global state without going through your public API, thus breaking encapsulation. The following program fragment demonstrates how to achieve this:

extern const int INTERNAL_CONSTANT;

extern std::string Filename;

// call an internal function within your module

FreeFunction();

// access a constant defined within your module

std::cout << "Constant = " << INTERNAL_CONSTANT << std::endl;

// change global state within your module

Filename = "different.txt";

There are a couple of solutions to this kind of external linkage leakage problem.

1. Static declaration. Prepend the declaration of your functions and variables with the static keyword. This specifies that the function or variable should have internal linkage and hence will not be accessible outside of the translation unit it appears in.

2. Anonymous namespace. A more idiomatic C++ solution is to enclose your file-scope functions and variables inside an anonymous namespace. This is a better solution because it avoids polluting the global namespace. This can be done as follows:

const int INTERNAL_CONSTANT = 42;

namespace {

std::string Filename = "file.txt";

void FreeFunction()

std::cout << "Free function called" << std::endl;

1. Microsoft Visual Studio. Symbols in a DLL are not accessible by default. You must explicitly export functions, classes, and variables in a DLL to allow your clients to access them. You do this using the __declspec decorator before a symbol. For example, you specify __declspec(dllexport) to export a symbol when you are building a DLL. Clients must then specify __declspec(dllimport) in order to access the same symbol in their own programs.

Tip

Use internal linkage to hide file-scope free functions and variables inside your .cpp files. This means using the static keyword or the anonymous namespace.

For symbols that have external linkage, there is the further concept of exporting symbols, which determines whether a symbol is visible from a shared library. Most compilers provide decorations for classes and functions that let you explicitly specify whether a symbol will appear in the exported symbol table for a library file. However, this tends to be compiler-specific behavior. For example:

2. GNU C++ compiler. Symbols with external linkage in a dynamic library are visible by default. However, you can use the visibility __attribute__ decorator to explicitly hide a symbol. As an alternative to hiding individual symbols, the GNU C++ 4.0 compiler introduced the -fvisibility=hidden flag to force all declarations to hidden visibility by default. Individual symbols can then be explicitly exported using __attribute__ ((visibility("default"))). This is more like the Windows behavior, where all symbols are considered internal unless you explicitly export them. Using the -fvisibility=hidden flag can also cause a dramatic improvement in load time performance of your dynamic library and produce smaller library files.

You can define various preprocessor macros to deal with these compiler differences in a cross-platform way. Here’s an example of defining a DLL_PUBLIC macro to export symbols explicitly and a DLL_HIDDEN macro to hide symbols when using the GNU C++ compiler. Note that you must specify an _EXPORTING define when you build the library file on Windows, that is, /D "_EXPORTING". This is an arbitrary define name—you can call it whatever you like (as long as you also update the code that follows).

#if defined _WIN32 || defined __CYGWIN__

#ifdef _EXPORTING // define this when generating DLL

#ifdef __GNUC__

#define DLL_PUBLIC __attribute__((dllexport))

#else

#define DLL_PUBLIC __declspec(dllexport)