• Table of Contents
• Previous Chapter
• Next Chapter

Chapter 10: More Operator Overloading

Don't hesitate to send in feedback: send an e-mail if you like the C++ Annotations; if you think that important material was omitted; if you find errors or typos in the text or the code examples; or if you just feel like e-mailing. Send your e-mail to Frank B. Brokken.

Please state the document version you're referring to, as found in the title (in this document: 8.3.1) and please state chapter and paragraph name or number you're referring to.

All received mail is processed conscientiously, and received suggestions for improvements will usually have been processed by the time a new version of the Annotations is released. Except for the incidental case I will normally not acknowledge the receipt of suggestions for improvements. Please don't interpret this as me not appreciating your efforts.

Having covered the overloaded assignment operator in chapter 8, and having shown several examples of other overloaded operators as well (i.e., the insertion and extraction operators in chapters 3 and 6), we will now take a look at operator overloading in general.

10.1: Overloading `operator[]()'

Here is an example showing the basic use of the class:

    int main()
    {
        IntArray x(20);                 // 20 ints

        for (int i = 0; i < 20; i++)
            x[i] = i * 2;               // assign the elements

        for (int i = 0; i <= 20; i++)   // produces boundary overflow
            cout << "At index " << i << ": value is " << x[i] << '\n';
    }

First, the constructor is used to create an object containing 20 ints. The elements stored in the object can be assigned or retrieved. The first for-loop assigns values to the elements using the index operator, the second for-loop retrieves the values but also results in a run-time error once the non-existing value x[20] is addressed. The IntArray class interface is:

    class IntArray
    {
        int     *d_data;
        size_t d_size;

         public:
            IntArray(size_t size = 1);
            IntArray(IntArray const &other);
            ~IntArray();
            IntArray const &operator=(IntArray const &other);

                                                // overloaded index operators:
            int &operator[](size_t index);                // first
            int const &operator[](size_t index) const;    // second

            void swap(IntArray &other);         // trivial

        private:
            void boundary(size_t index) const;
            int &operatorIndex(size_t index) const;
    };

• One of its constructors has a size_t parameter having a default argument value, specifying the number of int elements in the object.
• The class internally uses a pointer to reach allocated memory. Hence, the necessary tools are provided: a copy constructor, an overloaded assignment operator and a destructor.
• Note that there are two overloaded index operators. Why are there two?

  The first overloaded index operator allows us to reach and modify the elements of non-constant IntArray objects. This overloaded operator's prototype is a function returning a reference to an int. This allows us to use expressions like x[10] as rvalues or lvalues.

  With non-const IntArray objects operator[] can therefore be used to retrieve and to assign values. The return value of the non-const operator[] member is not an int const &, but an int &. In this situation we don't use const, as we must be able to modify the element we want to access when the operator is used as lvalue.

  This whole scheme fails if there's nothing to assign. Consider the situation where we have an IntArray const stable(5). Such an object is an immutable const object. The compiler detects this and refuses to compile this object definition if only the non-const operator[] is available. Hence the second overloaded index operator is added to the class's interface. Here the return value is an int const &, rather than an int &, and the member function itself is a const member function. This second form of the overloaded index operator is only used with const objects. It is used for value retrieval instead of value assignment. That, of course, is precisely what we want when using const objects. In this situation members are overloaded only by their const attribute. This form of function overloading was introduced earlier in the C++ Annotations (sections 2.5.4 and 7.5).

  Since IntArray stores values of a primitive type IntArray's operator[] const could also have defined a value return type. However, with objects one usually doesn't want the extra copying that's implied with value return types. In those cases const & return values are preferred for const member functions. So, in the IntArray class an int return value could have been used as well, resulting in the following prototype:

      int IntArray::operator[](int index) const;
  

• As there is only one pointer data member, the destruction of the memory allocated by the object is a simple delete[] data.

    #include "intarray.ih"

    IntArray::IntArray(size_t size)
    :
        d_size(size)
    {
        if (d_size < 1)
            throw string("IntArray: size of array must be >= 1");

        d_data = new int[d_size];
    }

    IntArray::IntArray(IntArray const &other)
    :
        d_size(other.d_size);
        d_data(new int[d_size]);
    {
        memcpy(d_data, other.d_data, d_size * sizeof(int));
    }

    IntArray::~IntArray()
    {
        delete[] d_data;
    }

    IntArray const &IntArray::operator=(IntArray const &other)
    {
        IntArray tmp(other);
        swap(tmp);
        return *this;
    }

    int &IntArray::operatorIndex(size_t index) const
    {
        boundary(index);
        return d_data[index];
    }

    int &IntArray::operator[](size_t index)
    {
        return operatorIndex(index);
    }

    int const &IntArray::operator[](size_t index) const
    {
        return operatorIndex(index);
    }

    void IntArray::boundary(size_t index) const
    {
        if (index < d_size)
            return;
        ostringstream out;
        out  << "IntArray: boundary overflow, index = " <<
                index << ", should be < " << d_size << '\n';
        throw out.str();
    }

10.2: Overloading the insertion and extraction operators

The class std::ostream defines insertion operators for primitive types, such as int, char *, etc.. In this section we will learn how to extend the existing functionality of classes (in particular std::istream and std::ostream) in such a way that they can be used also in combination with classes developed much later in history.

In this section we will show how the insertion operator can be overloaded allowing the insertion of any type of object, say Person (see chapter 8), into an ostream. Having defined such an overloaded operator the following will be possible:

    Person kr("Kernighan and Ritchie", "unknown", "unknown");

    cout << "Name, address and phone number of Person kr:\n" << kr << '\n';

                                // declared in `person.h'
    std::ostream &operator<<(std::ostream &out, Person const &person);

                                // defined in some source file
    ostream &operator<<(ostream &out, Person const &person)
    {
        return
            out <<
                "Name:    " << person.name() << ", "
                "Address: " << person.address() << ", "
                "Phone:   " << person.phone();
    }

• The function returns a reference to an ostream object, to enable `chaining' of the insertion operator.
• The two operands of operator<< are passed to the free function as its arguments. In the example, the parameter out was initialized by cout, the parameter person by kr.

In order to overload the extraction operator for, e.g., the Person class, members are needed modifying the class's private data members. Such modifiers are normally offered by the class interface. For the Person class these members could be the following:

    void setName(char const *name);
    void setAddress(char const *address);
    void setPhone(char const *phone);

    void Person::setAddress(char const *address)
    {
        delete[] d_address;
        d_address = strdupnew(address);
    }

    istream &operator>>(istream &in, Person &person)
    {
        string name;
        string address;
        string phone;

        if (in >> name >> address >> phone)    // extract three strings
        {
            person.setName(name.c_str());
            person.setAddress(address.c_str());
            person.setPhone(phone.c_str());
        }
        return in;
    }

10.3: Conversion operators

    class String
    {
        char *d_string;

        public:
            String();
            String(char const *arg);
            ~String();
            String(String const &other);
            String const &operator=(String const &rvalue);
            String const &operator=(char const *rvalue);
    };

Usually, in classes that are less directly linked to their data than this String class, there will be an accessor member function, like a member char const *String::c_str() const. However, the need to use this latter member doesn't appeal to our intuition when an array of String objects is defined by, e.g., a class StringArray. If this latter class provides the operator[] to access individual String members, it would most likely offer at least the following class interface:

    class StringArray
    {
        String *d_store;
        size_t d_n;

        public:
            StringArray(size_t size);
            StringArray(StringArray const &other);
            StringArray const &operator=(StringArray const &rvalue);
            ~StringArray();

            String &operator[](size_t index);
    };

    StringArray sa(10);

    sa[4] = sa[3];  // String to String assignment

    sa[3] = "hello world";

• First, sa[3] is evaluated. This results in a String reference.
• Next, the String class is inspected for an overloaded assignment, expecting a char const * to its right-hand side. This operator is found, and the string object sa[3] receives its new value.

    char const *cp = sa[3];

One possibility is to define an accessor member function c_str():

    char const *cp = sa[3].c_str()

A conversion operator is a kind of overloaded operator, but this time the overloading is used to cast the object to another type. In class interfaces, the general form of a conversion operator is:

    operator <type>() const;

Conversion operators are somewhat dangerous. The conversion is automatically performed by the compiler and unless its use is perfectly transparent it may confuse those who read code in which conversion operators are used. E.g., novice C++ programmers are frequently confused by statements like `if (cin) ...'.

As a rule of thumb: classes should define at most one conversion operator. Multiple conversion operators may be defined but frequently result in ambiguous code. E.g., if a class defines operator bool() const and operator int() const then passing an object of this class to a function expecting a size_t argument results in an ambiguity as an int and a bool may both be used to initialize a size_t.

In the current example, the class String could define the following conversion operator for char const *:

    String::operator char const *() const
    {
        return d_string;
    }

• Conversion operators do not define return types. The conversion operator returns a value of the type specified beyond the operator keyword.
• In certain situations (e.g., when a String argument is passed to a function specifying an ellipsis parameter) the compiler needs a hand to disambiguate our intentions. A static_cast will solve the problem.
• With template functions conversion operators may not work immediately as expected. For example, when defining a conversion operator X::operator std::string const() const then cout << X() won't compile. The reason for this is explained in section 20.8, but a shortcut allowing the conversion operator to work is to define the following overloaded operator<< function:

      std::ostream &operator<<(std::ostream &out, std::string const &str)
      {
          return out.write(str.data(), str.length());
      }
  

• If a class X defining a conversion operator also defines an insertion operator accepting an X object the insertion operator is used;
• Otherwise, if the type returned by the conversion operator is insertable then the conversion operator is used;
• Otherwise, a compilation error results. Note that this happens if the type returned by the conversion operator itself defines a conversion operator to a type that may be inserted into a stream.

    #include <iostream>
    #include <string>
    using namespace std;

    struct Insertable
    {
        operator int() const
        {
            cout << "op int()\n";
        }
    };
    ostream &operator<<(ostream &out, Insertable const &ins)
    {
        return out << "insertion operator";
    }
    struct Convertor
    {
        operator Insertable() const
        {
            return Insertable();
        }
    };
    struct Text
    {
        operator int() const
        {
            return 1;
        }
    };
    struct Error
    {
        operator Text() const
        {
            return Text();
        }
    };

    int main()
    {
        Insertable insertable;
        cout << insertable << '\n';
        Convertor convertor;
        cout << convertor << '\n';
        Error error;
        cout << error << '\n';
    }

Some final remarks regarding conversion operators:

• A conversion operator should be a `natural extension' of the facilities of the object. For example, the stream classes define operator bool(), allowing constructions like if (cin).
• A conversion operator should return an rvalue. It should do so to enforce data-hiding and because it is the intended use of the conversion operator. Defining a conversion operator as an lvalue (e.g., defining an operator int &() conversion operator) opens up a back door, and the operator can only be used as lvalue when explicitly called (as in: x.operator int&() = 5). Don't use it.
• Conversion operators should be defined as const member functions as they don't modify their object's data members.
• Conversion operators returning composed objects should return const references to these objects whenever possible to avoid calling the composed object's copy constructor.

10.4: The keyword `explicit'

Assume a data base class DataBase is defined in which Person objects can be stored. It defines a Person *d_data pointer, and so it offers a copy constructor and an overloaded assignment operator.

In addition to the copy constructor DataBase offers a default constructor and several additional constructors:

• DataBase(Person const &): the DataBase initially contains a single Person object;
• DataBase(istream &in): the data about multiple persons are read from in.
• DataBase(size_t count, istream &in = cin): the data of count persons are read from in, by default the standard input stream.

The above constructors all are perfectly reasonable. But they also allow the compiler to compile the following code without producing any warning at all:

    DataBase db;
    DataBase db2;
    Person person;

    db2 = db;           // 1
    db2 = person;       // 2
    db2 = 10;           // 3
    db2 = cin;          // 4

All four statements are the result of implicit promotions. Since constructors accepting, respectively a Person, a size_t and an istream have been defined for PersonData and since the assignment operator expects a PersonData right-hand side (rhs) argument the compiler will first convert the rhs arguments to anonymous DataBase objects which are then assigned to db2.

It is good practice to prevent implicit promotions by using the explicit modifier when declaring a constructor. Constructors using the explicit modifier can only be used to construct objects explicitly. Statements 2-4 would not have compiled if the constructors expecting one argument would have been declared using explicit. E.g.,

    explicit DataBase(Person const &person);
    explicit DataBase(size_t count, std:istream &in);

Having declared all constructors accepting one argument as explicit the above assignments would have required the explicit specification of the appropriate constructors, thus clarifying the programmer's intent:

    DataBase db;
    DataBase db2;
    Person person;

    db2 = db;               // 1
    db2 = DataBase(person); // 2
    db2 = DataBase(10);     // 3
    db2 = DataBase(cin);    // 4

10.4.1: Explicit conversion operators (C++0x, 4.5)

For example, a class might define operator bool() const returning true if an object of that class is in a usable state and false if not. Since the type bool is an arithmetic type this could result in unexpected or unintended behavior. Consider:

    class StreamHandler
    {
        public:
            operator bool() const;      // true: object is fit for use
            ...
    };

    int fun(StreamHandler &sh)
    {
        int sx;

        if (sh)                         // intended use of operator bool()
            ... use sh as usual; also use `sx'

        process(sh);                    // typo: `sx' was intended
    }

With explicit conversion operators implicit conversions like the one shown in the example are prevented and such conversion operators will only be used in situations where the converted type is explicitly required. E.g., in the condition sections of if or repetition statements where a bool value is expected. In such cases an explicit operator bool() conversion operator would automatically be used.

10.5: Overloading the increment and decrement operators

Used as postfix operator, the value's object is returned as an rvalue, temporary const object and the post-incremented variable itself disappears from view. Used as prefix operator, the variable is incremented, and its value is returned as lvalue and it may be altered again by modifying the prefix operator's return value. Whereas these characteristics are not required when the operator is overloaded, it is strongly advised to implement these characteristics in any overloaded increment or decrement operator.

Suppose we define a wrapper class around the size_t value type. Such a class could offer the following (partially shown) interface:

    class Unsigned
    {
        size_t d_value;

        public:
            Unsigned();
            explicit Unsigned(size_t init);

            Unsigned &operator++();
    }

    Unsigned &Unsigned::operator++()
    {
        ++d_value;
        return *this;
    }

To define the postfix operator, an overloaded version of the operator is defined, expecting a (dummy) int argument. This might be considered a kludge, or an acceptable application of function overloading. Whatever your opinion in this matter, the following can be concluded:

• Overloaded increment and decrement operators without parameters are prefix operators, and should return references to the current object.
• Overloaded increment and decrement operators having an int parameter are postfix operators, and should return a constant value which is a copy of the object at the point where its postfix operator is used.

    Unsigned const operator++(int);

    Unsigned const Unsigned::operator++(int)
    {
        Unsigned tmp(*this);
        ++d_value;
        return tmp;
    }

In the above example the statement incrementing the current object offers the nothrow guarantee as it only involves an operation on a primitive type. If the initial copy construction throws then the original object is not modified, if the return statement throws the object has safely been modified. But incrementing an object could itself throw exceptions. How to implement the increment operators in that case? Once again, swap is our friend. Here are the pre- and postfix operators offering the strong guarantee when the member increment performing the increment operation may throw:

    Unsigned &Unsigned::operator++()
    {
        Unsigned tmp(*this);
        tmp.increment();
        swap(tmp);
        return *this;
    }
    Unsigned const Unsigned::operator++(int)
    {
        Unsigned tmp(*this);
        tmp.increment();
        swap(tmp);
        return tmp;
    }

When calling the postfix increment or decrement operator using its full member function name then any int argument passed to the member function will result in calling the postfix operator. Example:

    Unsigned uns(13);

    uns.operator++();     // prefix-incrementing uns
    uns.operator++(0);    // postfix-incrementing uns

10.6: Overloading binary operators

Most binary operators come in two flavors: the plain binary operator (like the + operator) and the arithmetic assignment variant (like the += operator). Whereas the plain binary operators return const expression values, the arithmetic assignment operators return a (non-const) reference to the object to which the operator was applied. For example, with std::string objects the following code (annotations below the example) may be used:

    std::string s1;
    std::string s2;
    std::string s3;

    s1 = s2 += s3;                  // 1
    (s2 += s3) + " postfix";        // 2
    s1 = "prefix " + s3;            // 3
    "prefix " + s3 + "postfix";     // 4
    ("prefix " + s3) += "postfix";  // 5

• at // 1 the contents of s3 is added to s2. Next, s2 is returned, and its new contents are assigned to s1. Note that += returns s2 itself.
• at // 2 the contents of s3 is also added to s2, but as += returns s2 itself, it's possible to add some more to s2
• at // 3 the + operator returns a std::string containing the concatenation of the text prefix and the contents of s3. This string returned by the + operator is thereupon assigned to s1.
• at // 4 the + operator is applied twice. The effect is:
  1. The first + returns a std::string containing the concatenation of the text prefix and the contents of s3.
  2. The second + operator takes this returned string as its left hand value, and returns a string containing the concatenated text of its left and right hand operands.
  3. The string returned by the second + operator represents the value of the expression.
• statement // 5 is interesting in that it should not compile (it does compile with the Gnu compiler). It should not compile, as the + operator should return a const string. This should prevent its modification by the subsequent += operator (compare this situation with int values: (3 + intVar) += 4 won't compile. Clearly, std::string does not do `as the ints do'). In the C++ Annotations binary arithmetic operators return const values to render statements like statement // 5 incompilable.

Consider the following code, in which a class Binary supports an overloaded operator+:

    class Binary
    {
        public:
            Binary();
            Binary(int value);
            Binary const operator+(Binary const &rvalue);
    };

    int main()
    {
        Binary b1;
        Binary b2(5);

        b1 = b2 + 3;            // 1
        b1 = 3 + b2;            // 2
    }

    error: no match for 'operator+' in '3 + b2'

In order to understand this remember promotions. As we have seen in section 10.4, constructors expecting a single argument may be implicitly activated when an argument of an appropriate type is provided. We've encountered this repeatedly with std::string objects, where an ASCII-Z string may be used to initialize a std::string object.

Analogously, in statement // 1, the + operator is called for the b2 object. This operator expects another Binary object as its right hand operand. However, an int is provided. As a constructor Binary(int) exists, the int value is first promoted to a Binary object. Next, this Binary object is passed as argument to the operator+ member.

In statement // 2 no promotions are available: here the + operator is applied to an lvalue that is an int. An int is a primitive type and primitive types have no concept of `constructors', `member functions' or `promotions'.

How, then, are promotions of left-hand operands implemented in statements like "prefix " + s3? Since promotions are applied to function arguments, we must make sure that both operands of binary operators are arguments. This means that plain binary arithmetic operators should be declared as free operators, also called free functions. Functions like the plain binary arithmetic operators conceptually belong to the class for which they implement the binary operator. Consequently they should be declared within the class's header file. We will cover their implementations shortly, but here is our first revision of the declaration of the class Binary, declaring an overloaded + operator as a free function:

    class Binary
    {
        public:
            Binary();
            Binary(int value);
    };

    Binary const operator+(Binary const &l_hand, Binary const &r_hand);

By defining binary operators as free functions, the following promotions are possible:

• If the left-hand operand is of the intended class type, the right hand argument will be promoted whenever possible;
• If the right-hand operand is of the intended class type, the left hand argument will be promoted whenever possible;
• No promotions occur when none of the operands are of the intended class type;
• An ambiguity occurs when promotions to different classes are possible for the two operands. For example:

      class A;
  
      class B
      {
          public:
              B(A const &a);
      };
  
      class A
      {
          public:
              A();
              A(B const &b);
      };
  
      A const operator+(A const &a, B const &b);
      B const operator+(B const &b, A const &a);
  
      int main()
      {
          A a;
  
          a + a;
      };
  

  Here, both overloaded + operators are possible when compiling the statement a + a. The ambiguity must be solved by explicitly promoting one of the arguments, e.g., a + B(a) will allow the compiler to resolve the ambiguity to the first overloaded + operator.

The next step is to implement the corresponding overloaded arithmetic assignment operator. As this operator always has a left-hand operand which is an object of its own class, it is implemented as a true member function. Furthermore, the arithmetic assignment operator should return a reference to the object to which the arithmetic operation applies, as the object might be modified in the same statement. E.g., (s2 += s3) + " postfix". Here is our second revision of the class Binary, showing both the declaration of the plain binary operator and the corresponding arithmetic assignment operator:

    class Binary
    {
        public:
            Binary();
            Binary(int value);
            Binary const operator+(Binary const &rvalue);

            Binary &operator+=(Binary const &other);
    };

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

    Binary const operator+(Binary const &&ltmp, Binary const &rhs);
    Binary const operator+(Binary const &lhs,   Binary const &&rtmp);
    Binary const operator+(Binary const &&ltmp, Binary const &&rtmp);

When implementing the arithmetic assignment operator the strong guarantee should again be kept in mind. Use a temporary object and swap if the arithmetic operation might throw. Example:

    Binary &operator+=(Binary const &other)
    {
        Binary tmp(*this);
        tmp.add(other);     // this may throw
        swap(tmp);
        return *this;
    }

Having available the arithmetic assignment operator, implementating the plain binary operator is easy. The lhs argument is copied into a Binary tmp to which the rhs operand is added. Then tmp is returned. The copy construction and two statements may be contracted into one single return statement, but then compilers usually aren't able to apply copy elision resulting in two copy constructions. Usually copy elision is performed when the steps are taken separately:

    class Binary
    {
        public:
            Binary();
            Binary(int value);
            Binary const operator+(Binary const &rvalue);

            Binary &operator+=(Binary const &other);
    };

    Binary const operator+(Binary const &lhs, Binary const &rhs)
    {
        Binary tmp(lhs);
        tmp += rhs;
        return tmp;
    }

10.7: Overloading `operator new(size_t)'

It is possible to define multiple versions of the operator new, as long as each version defines its own unique set of arguments. When overloaded operator new members must dynamically allocate memory they can do so using the global operator new, applying the scope resolution operator ::. In the next example the overloaded operator new of the class String will initialize the substrate of dynamically allocated String objects to 0-bytes:

    #include <cstddef>
    #include <iosfwd>

    class String
    {
        std::string *d_data;

        public:
            void *operator new(size_t size)
            {
                return memset(::operator new(size), 0, size);
            }
            bool empty() const
            {
                return d_data == 0;
            }
    };

    #include "string.h"
    #include <iostream>
    using namespace std;

    int main()
    {
        String *sp = new String;

        cout << boolalpha << sp->empty() << '\n';   // shows: true
    }

• First, String::operator new was called, allocating and initializing a block of memory, the size of a String object.
• Next, a pointer to this block of memory was passed to the (default) String constructor. Since no constructor was defined, the constructor itself didn't do anything at all.

All member functions (including constructors and destructors) we've encountered so far define a (hidden) pointer to the object on which they should operate. This hidden pointer becomes the function's this pointer.

In the next example of pseudo C++ code, the pointer is explicitly shown to illustrate what's happening when operator new is used. In the first part a String object str is directly defined, in the second part of the example the (overloaded) operator new is used:

    String::String(String *const this);     // real prototype of the default
                                            // constructor

    String *sp = new String;                // This statement is implemented
                                            // as follows:

        String *sp = reinterpret_cast<String *>(            // allocation
                        String::operator new(sizeof(String))
                     );
        String::String(sp);                                 // initialization

Following the allocation, the memory is passed (as the this pointer) to the constructor for further processing.

Operator new can have multiple parameters. The first parameter is initialized as an implicit argument and is always a size_t parameter. Additional overloaded operators may define additional parameters. An interesting additional operator new is the placement new operator. With the placement new operator a block of memory has already been set aside and one of the class's constructors will be used to initialize that memory. Overloading placement new requires an operator new having two parameters: size_t and char *, pointing to the memory that was already available. The size_t parameter is implicitly initialized, but the remaining parameters must explicitly be initialized using arguments to operator new. Hence we reach the familiar syntactical form of the placement new operator in use:

    char buffer[sizeof(String)];        // predefined memory
    String *sp = new(buffer) String;    // placement new call

    void *operator new(size_t size, char *memory);

    void *String::operator new(size_t size, char *memory)
    {
        return memset(memory, 0, size);
    }

        // use:
    String *next(String **pointers, size_t *idx)
    {
        return new(pointers, (*idx)++) String;
    }

        // implementation:
    void *String::operator new(size_t size, String **pointers, size_t idx)
    {
        return pointers[idx] = ::operator new(size);
    }

10.8: Overloading `operator delete(void *)'

Operator delete must define a void * parameter. A second overloaded version defining a second parameter of type size_t is related to overloading operator new[] and is discussed in section 10.9.

Overloaded operator delete members return void.

The `home-made' operator delete is called when deleting a dynamically allocated object after executing the destructor of the associated class. So, the statement

    delete ptr;

    ptr->~String(); // call the class's destructor

                    // and do things with the memory pointed to by ptr
    String::operator delete(ptr);

    void String::operator delete(void *ptr)
    {
        // any operation considered necessary, then, maybe:
        ::delete ptr;
    }

    void operator delete(void *ptr);

10.9: Operators `new[]' and `delete[]'

As it is possible to overload new[] and delete[] as well as operator new and operator delete, one should be careful in selecting the appropriate set of operators. The following rule of thumb should always be applied:

If new is used to allocate memory, delete should be used to deallocate memory. If new[] is used to allocate memory, delete[] should be used to deallocate memory.

By default these operators act as follows:

• operator new is used to allocate a single object or primitive value. With an object, the object's constructor is called.
• operator delete is used to return the memory allocated by operator new. Again, with class-type objects, the class's destructor is called.
• operator new[] is used to allocate a series of primitive values or objects. If a series of objects is allocated, the class's default constructor is called to initialize each object individually.
• operator delete[] is used to delete the memory previously allocated by new[]. If objects were previously allocated, then the destructor will be called for each individual object. Be careful, though, when pointers to objects were allocated. If pointers to objects were allocated the destructors of the objects to which the allocated pointers point won't automatically be called. A pointer is a primitive type and so no further action is taken when it is returned to the common pool.

10.9.1: Overloading `new[]'

    void *operator new[](size_t size);

    void *operator new[](size_t size)
    {
        return ::operator new[](size);
        // alternatively:
        // return ::operator new(size);
    }

Once the overloaded operator new[] has been defined, it will be used automatically in statements like:

    String *op = new String[12];

    void *String::operator new[](size_t size, char *memory)
    {
        return memset(memory, 0, size);
    }

    char buffer[12 * sizeof(String)];
    String *sp = new(buffer) String[12];

10.9.2: Overloading `delete[]'

    void operator delete[](void *memory);

There are some subtleties to be aware of when implementing operator delete[]. Although the addresses returned by new and new[] point to the allocated object(s), there is an additional size_t value available immediately before the address returned by new and new[]. This size_t value is part of the allocated block and contains the actual size of the block. This of course does not hold true for the placement new operator.

When a class defines a destructor the size_t value preceding the address returned by new[] does not contain the size of the allocated block, but the number of objects specified when calling new[]. Normally that is of no interest, but when overloading operator delete[] it might become a useful piece of information. In those cases operator delete[] will not receive the address returned by new[] but rather the address of the initial size_t value. Whether this is at all useful is not clear. By the time delete[]'s code is executed all objects have already been destroyed, so operator delete[] is only to determine how many objects were destroyed but the objects themselves cannot be used anymore.

Here is an example showing this behavior of operator delete[] for a minimal Demo class:

    struct Demo
    {
        size_t idx;
        Demo()
        {
            cout << "default cons\n";
        }
        ~Demo()
        {
            cout << "destructor\n";
        }
        void *operator new[](size_t size)
        {
            return ::operator new(size);
        }
        void operator delete[](void *vp)
        {
            cout << "delete[] for: " << vp << '\n';
            ::operator delete[](vp);
        }
    };

    int main()
    {
        Demo *xp;
        cout << ((int *)(xp = new Demo[3]))[-1] << '\n';
        cout << xp << '\n';
        cout << "==================\n";
        delete[] xp;
    }
    // This program displays (your 0x?????? addresses might differ, but
    // the difference between the two should be sizeof(size_t)):
    //  default cons
    //  default cons
    //  default cons
    //  3
    //  0x8bdd00c
    //  ==================
    //  destructor
    //  destructor
    //  destructor
    //  delete[] for: 0x8bdd008

        delete[] new String[5];

Operator delete[] may also be overloaded using an additional size_t parameter:

    void operator delete[](void *p, size_t size);

    void String::operator delete[](void *p, size_t size)
    {
        cout << "deleting " << size << " bytes\n";
        ::operator delete[](ptr);
    }

Additional overloads of operator delete[] may be defined, but to use them they must explicitly be called as static member functions (cf. chapter 11). Example:

        // declaration:
    void String::operator delete[](void *p, ostream &out);
        // usage:
    String *xp = new String[3];
    String::operator delete[](xp, cout);

10.9.3: `new[]', `delete[]' and exceptions

To begin, new[] might throw while trying to allocate the required memory. In this case a bad_alloc is thrown and we don't leak as nothing was allocated.

Having allocated the required memory the class's default constructor will be called for each of the objects in turn. At some point a constructor might throw. What happens next is defined by the C++ standard: the destructors of the already constructed objects will be called and the memory allocated for the objects themselves is returned to the common pool. Assuming that the failing constructor offers the basic guarantee new[] is therefore exception safe even if a constructor may throw.

The following example illustrates this behavior. A request to allocate and initialize five objects is made, but after constructing two objects construction fails by throwing an exception. The output shows that the destructors of properly constructed objects are called and that the allocated substrate memory is properly returned:

    #include <iostream>
    using namespace std;

    static size_t count = 0;

    class X
    {
        int x;

        public:
            X()
            {
                if (count == 2)
                    throw 1;
                cout << "Object " << ++count << '\n';
            }
            ~X()
            {
                cout << "Destroyed " << this << "\n";
            }
            void *operator new[](size_t size)
            {
                cout << "Allocating objects: " << size << " bytes\n";
                return ::operator new(size);
            }
            void operator delete[](void *mem)
            {
                cout << "Deleting memory at " << mem << ", containing: " <<
                    *reinterpret_cast<int *>(mem) << "\n";
                ::operator delete(mem);
            }
    };

    int main()
    try
    {
        X *xp = new X[5];
        cout << "Memory at " << xp << '\n';
        delete[] xp;
    }
    catch (...)
    {
        cout << "Caught exception.\n";
    }
    // Output from this program (your 0x??? addresses might differ)
    //  Allocating objects: 24 bytes
    //  Object 1
    //  Object 2
    //  Destroyed 0x8428010
    //  Destroyed 0x842800c
    //  Deleting memory at 0x8428008, containing: 5
    //  Caught exception.

10.10: Function Objects

Function objects are important when using generic algorithms. The use of function objects is preferred over alternatives like pointers to functions. The fact that they are important in the context of generic algorithms leaves us with a didactic dilemma. At this point in the C++ Annotations it would have been nice if generic algorithms would already have been covered, but for the discussion of the generic algorithms knowledge of function objects is required. This bootstrapping problem is solved in a well known way: by ignoring the dependency for the time being, for now concentrating on the function object concept.

Function objects are objects for which operator() has been defined. Function objects are not just used in combination with generic algorithms, but also as a (preferred) alternative to pointers to functions.

Function objects are frequently used to implement predicate functions. Predicate functions return boolean values. Predicate functions and predicate function objects are commonly referred to as `predicates'. Predicates are frequently used by generic algorithms such as the count_if generic algorithm, covered in chapter 19, returning the number of times its function object has returned true. In the standard template library two kinds of predicates are used: unary predicates receive one argument, binary predicates receive two arguments.

Assume we have a class Person and an array of Person objects. Further assume that the array is not sorted. A well known procedure for finding a particular Person object in the array is to use the function lsearch, which performs a lineair search in an array. Example:

    Person &target = targetPerson();    // determine the person to find
    Person *pArray;
    size_t n = fillPerson(&pArray);

    cout << "The target person is";

    if (!lsearch(&target, pArray, &n, sizeof(Person), compareFunction))
        cout << " not";
    cout << "found\n";

The comparison function must be available, as its address is one of the arguments of lsearch. It must be a real function having an address. If it is defined inline then the compiler has no choice but to ignore that request as inline functions don' have addresses. CompareFunction could be implemented like this:

    int compareFunction(void const *p1, void const *p2)
    {
        return *reinterpret_cast<Person const *>(p1)    // lsearch wants 0
                !=                                      // for equal objects
                *reinterpret_cast<Person const *>(p2);
    }

On average n / 2 times at least the following actions take place:

1. The two arguments of the compare function are pushed on the stack;
2. The value of the final parameter of lsearch is determined, producing compareFunction's address;
3. The compare function is called;
4. Then, inside the compare function the address of the right-hand argument of the Person::operator!= argument is pushed on the stack;
5. Person::operator!= is evaluated;
6. The argument of the Person::operator!= function is popped off the stack;
7. The two arguments of the compare function are popped off the stack.

    Person const *PersonSearch(Person *base, size_t nmemb,
                               Person const &target);

    Person &target = targetPerson();
    Person *pArray;
    size_t n = fillPerson(&pArray);

    cout << "The target person is";

    if (!PersonSearch(pArray, n, target))
        cout << " not";

    cout << "found\n";

    Person const *PersonSearch(Person *base, size_t nmemb,
                                Person const &target)
    {
        for (int idx = 0; idx < nmemb; ++idx)
            if (target(base[idx]))
                return base + idx;
        return 0;
    }

    bool Person::operator()(Person const &other) const
    {
        return *this == other;
    }

    bool operator()(Person const &other) const;

1. The address of the right-hand argument of the Person::operator== argument is pushed on the stack;
2. The operator== function is evaluated (which probably also is a semantic improvement over calling operator!= when looking for an object equal to a specified target object);
3. The argument of Person::operator== argument is popped off the stack.

Function objects may truly be defined inline. Functions that are called indirectly (i.e., using pointers to functions) can never be defined inline as their addresses must be known. Therefore, even if the function object needs to do very little work it is defined as an ordinary function if it is going to be called through pointers. The overhead of performing the indirect call may annihilate the advantage of the flexibility of calling functions indirectly. In these cases using inline function objects can result in an increase of a program's efficiency.

An added benefit of function objects is that they may access the private data of their objects. In a search algorithm where a compare function is used (as with lsearch) the target and array elements are passed to the compare function using pointers, involving extra stack handling. Using function objects, the target person doesn't vary within a single search task. Therefore, the target person could be passed to the function object's class constructor. This is in fact what happens in the expression target(base[idx]) receiving as its only argument the subsequent elements of the array to search.

10.10.1: Constructing manipulators

Actually the construction of a manipulator is rather simple. To start, a definition of the manipulator is needed. Let's assume we want to create a manipulator w10 which will set the field width of the next field to be written by the ostream object to 10. This manipulator is constructed as a function. The w10 function will have to know about the ostream object in which the width must be set. By providing the function with an ostream & parameter, it obtains this knowledge. Now that the function knows about the ostream object we're referring to, it can set the width in that object.

Next, it must be possible to use the manipulator in an insertion sequence. This implies that the return value of the manipulator must be a reference to an ostream object also.

From the above considerations we're now able to construct our w10 function:

    #include <ostream>
    #include <iomanip>

    std::ostream &w10(std::ostream &str)
    {
        return str << std::setw(10);
    }

        #include <iostream>
        #include <iomanip>

        using namespace std;

        extern ostream &w10(ostream &str);

        int main()
        {
            w10(cout) << 3 << " ships sailed to America\n;
            cout << "And " << w10 << 3 << " more ships sailed too.\n";
        }

    ostream& operator<<(ostream ostream &(*func)(ostream &str))
    {
        return (*func)(*this);
    }

    ostream &operator<<(ios_base &(*func)(ios_base &base))
    {
        (*func)(*this);
        return *this;
    }

The above procedure does not work for manipulators requiring arguments. It is of course possible to overload operator<< to accept an ostream reference and the address of a function expecting an ostream & and, e.g., an int, but while the address of such a function may be specified with the <<-operator, the arguments itself cannot be specified. So, one wonders how the following construction has been implemented:

    cout << setprecision(3)

10.10.1.1: Manipulators requiring arguments

So, one might consider constructing another overloaded operator<< accepting the address of a function receiving not just the ostream reference, but a series of other arguments as well. But this creaes the problem that it isn't clear how the function should receive its arguments: you can't just call it since that takes us back to the abovementioned problem. Merely passing its address is fine, but then no arguments can't be passed to the function.

There exists a solution, based on the use of anonymous objects:

• First, a class is constructed, e.g. Align, whose constructor expects multiple arguments. In our example representing, respectively, the field width and the alignment.
• Furthermore, we define the function:

          ostream &operator<<(ostream &ostr, Align const &align)
  

  so we can insert an Align object into the ostream.

    #include <iostream>
    #include <iomanip>

    class Align
    {
        unsigned d_width;
        std::ios::fmtflags d_alignment;

        public:
            Align(unsigned width, std::ios::fmtflags alignment);
            std::ostream &operator()(std::ostream &ostr) const;
    };

        Align::Align(unsigned width, std::ios::fmtflags alignment)
        :
            d_width(width),
            d_alignment(alignment)
        {}

        std::ostream &Align::operator()(std::ostream &ostr) const
        {
            ostr.setf(d_alignment, std::ios::adjustfield);
            return ostr << std::setw(d_width);
        }

    std::ostream &operator<<(std::ostream &ostr, Align const &align)
    {
        return align(ostr);
    }

    using namespace std;

    int main()
    {
        cout
            << "`" << Align(5, ios::left) << "hi" << "'"
            << "`" << Align(10, ios::right) << "there" << "'\n";
    }

    /*
        Generated output:

        `hi   '`     there'
    */

10.11: The case of [io]fstream::open()

    fstream out;
    out.open("/tmp/out", ios::out);

    fstream out;
    out.open("/tmp/out", ios::in | ios::out);

When trying to combine enum values using a `home made' enum we may run into problems. Consider the following:

    enum Permission
    {
        READ =      1 << 0,
        WRITE =     1 << 1,
        EXECUTE =   1 << 2
    };

    void setPermission(Permission permission);

    int main()
    {
        setPermission(READ | WRITE);
    }

The question is of course: why is it OK to combine ios::openmode values passing these combined values to the stream's open member, but not OK to combine Permission values.

Combining enum values using arithmetic operators results in int-typed values. Conceptually this never was our intention. Conceptually it can be considered correct to combine enum values if the resulting value conceptually makes sense as a value that is still within the original enumeration domain. Note that after adding a value READWRITE = READ | WRITE to the above enum we're still not allowed to specify READ | WRITE as an argument to setPermission.

To answer the question about combining enumeration values and yet stay within the enumeration's domain we turn to operator overloading. Up to this point operator overloading has been applied to class types. Free functions like operator<< have been overloaded, and those overloads are conceptually within the domain of their class.

As C++ is a stronly typed language realize that defining an enum is really something beyond the mere association of int-values with symbolic names. An enumeration type is really a type of its own, and as with any type its operators can be overloaded. When writing READ | WRITE the compiler will perform the default converstion from enum values to int values and thus will apply the operator to ints. It does so when it has no alternative.

But it is also possible to overload the enum type's operators. Thus we may ensure that we'll remain within the enum's domain even though the resulting value wasn't defined by the enum. The advantage of type-safety and conceptual clarity is considered to outweigh the somewhat peculiar introduction of values hitherto not defined by the enum.

Here is an example of such an overloaded operator:

    Permission operator|(Permission left, Permission right)
    {
        return static_cast<Permission>(static_cast<int>(left) | right);
    }

Operators like the above were defined for the ios::openmode enumeration type, allowing us to specify ios::in | ios::out as argument to open while specifying the corresponding parameter as ios::openmode as well. Clearly, operator overloading can be used in many situations, not necessarily only involving class-types.

10.12: Overloadable operators

    +       -       *       /       %       ^       &       |
    ~       !       ,       =       <       >       <=      >=
    ++      --      <<      >>      ==      !=      &&      ||
    +=      -=      *=      /=      %=      ^=      &=      |=
    <<=     >>=     []      ()      ->      ->*     new     new[]
    delete  delete[]

Several of these operators may only be overloaded as member functions within a class. This holds true for the '=', the '[]', the '()' and the '->' operators. Consequently, it isn't possible to redefine, e.g., the assignment operator globally in such a way that it accepts a char const * as an lvalue and a String & as an rvalue. Fortunately, that isn't necessary either, as we have seen in section 10.3.

Finally, the following operators cannot be overloaded:

    .       .*      ::      ?:      sizeof  typeid

• Table of Contents
• Previous Chapter
• Next Chapter