Back to Implementation
Continue to Item 30: Avoid member functions that return non-const pointers or references to members less accessible than themselves.

Item 29: Avoid returning "handles" to internal data.

A scene from an object-oriented romance:

Object A: Darling, don't ever change!

Object B: Don't worry, dear, I'm `const`.

Yet just as in real life, A wonders, "Can B be trusted?" And just as in real life, the answer often hinges on B's nature: the constitution of its member functions.

Suppose B is a constant `String` object:

    class String {
    public:
      String(const char *value);        // see Item 11 for pos-
      ~String();                        // sible implementations;
                                        // see Item M5 for comments
                                        // on the first constructor

      operator char *() const;          // convert String -> char*;
                                        // see also Item M5
      ...

    private:
      char *data;
    };

    const String B("Hello World");      // B is a const object

Because `B` is `const`, it had better be the case that the value of `B` now and evermore is "Hello World". Of course, this supposes that programmers working with `B` are playing the game in a civilized fashion. In particular, it depends on the fact that nobody is "casting away the constness" of `B` through nefarious ploys such as this (see Item 21):

    String& alsoB =              // make alsoB another name
      const_cast<String&>(B);    // for B, but without the
                                 // constness

Given that no one is doing such evil deeds, however, it seems a safe bet that `B` will never change. Or does it? Consider this sequence of events:

    char *str = B;               // calls B.operator char*()

    strcpy(str, "Hi Mom");       // modifies what str
                                 // points to

Does `B` still have the value "Hello World", or has it suddenly mutated into something you might say to your mother? The answer depends entirely on the implementation of `String::operator` `char*`.

Here's a careless implementation, one that does the wrong thing. However, it does it very efficiently, which is why so many programmers fall into this trap:

    // a fast, but incorrect implementation
    inline String::operator char*() const
    { return data; }

The flaw in this function is that it's returning a "handle" — in this case, a pointer — to information that should be hidden inside the `String` object on which the function is invoked. That handle gives callers unrestricted access to what the private field `data` points to. In other words, after the statement

    char *str = B;

the situation looks like this:

Clearly, any modification to the memory pointed to by `str` will also change the effective value of `B`. Thus, even though `B` is declared `const`, and even though only `const` member functions are invoked on `B`, `B` might still acquire different values as the program runs. In particular, if `str` modifies what it points to, `B` will also change.

There's nothing inherently wrong with the way `String::operator char*` is written. What's troublesome is that it can be applied to constant objects. If the function weren't declared `const`, there would be no problem, because it couldn't be applied to objects like `B`.

Yet it seems perfectly reasonable to turn a `String` object, even a constant one, into its equivalent `char*`, so you'd like to keep this function `const`. If you want to do that, you must rewrite your implementation to avoid returning a handle to the object's internal data:

    // a slower, but safer implementation
    inline String::operator char*() const
    {
      char *copy = new char[strlen(data) + 1];
      strcpy(copy, data);

      return copy;

    }

This implementation is safe, because it returns a pointer to memory that contains a copy of the data to which the `String` object points; there is no way to change the value of the `String` object through the pointer returned by this function. As usual, such safety commands a price: this version of `String::operator` `char*` is slower than the simple version above, and callers of this function must remember to use `delete` on the pointer that's returned.

If you think this version of `operator` `char*` is too slow, or if the potential memory leak makes you nervous (as well it should), a slightly different tack is to return a pointer to constant `char`s:

    class String {
    public:
        operator const char *() const;

      ...

    };

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

This function is fast and safe, and, though it's not the same as the function you originally specified, it suffices for most applications. It's also the moral equivalent of the °C++ standardization committee's solution to the `string`/`char*` conundrum: the standard `string` type contains a member function `c_str` that returns a `const` `char*` version of the `string` in question. For more information on the standard `string` type, turn to Item 49.

A pointer isn't the only way to return a handle to internal data. References are just as easy to abuse. Here's a common way to do it, again using the `String` class:

    class String {
    public:

      ...

      char& operator[](int index) const
     { return data[index]; }

    private:
      char *data;
    };

    String s = "I'm not constant";

    s[0] = 'x';               // fine, s isn't const

    const String cs = "I'm constant";

    cs[0] = 'x';              // this modifies the const
                              // string, but compilers
                              // won't notice

Notice how `String::operator[]` returns its result by reference. That means that the caller of this function gets back another name for the internal element `data[index]`, and that other name can be used to modify the internal data of the supposedly constant object. This is the same problem you saw before, but this time the culprit is a reference as a return value, not a pointer.

The general solutions to this kind of problem are the same as they were for pointers: either make the function non-`const`, or rewrite it so that no handle is returned. For a solution to this particular problem — how to write `String::operator[]` so that it works for both `const` and non-`const` objects — see Item 21.

`const` member functions aren't the only ones that need to worry about returning handles. Even non-`const` member functions must reconcile themselves to the fact that the validity of a handle expires at the same time as the object to which it corresponds. This may be sooner than a client expects, especially when the object in question is a compiler-generated temporary object.

For example, take a look at this function, which returns a `String` object:

    String someFamousAuthor()           // randomly chooses and
    {                                   // returns an author's name

      switch (rand() % 3) {             // rand() is in <stdlib.h>
                                        // (and <cstdlib> — see
                                        // Item 49)
      case 0:
        return "Margaret Mitchell";     // Wrote "Gone with the
                                        // Wind," a true classic
      case 1:
        return "Stephen King";          // His stories have kept
                                        // millions from sleeping
                                        // at night
      case 2:
        return "Scott Meyers";          // Ahem, one of these
      }                                 // things is not like the
                                        // others...

      return "";                        // we can't get here, but
                                        // all paths in a value-
                                        // returning function must
    }                                   // return a value, sigh

Kindly set aside your concerns about how "random" the values returned from `rand` are, and please humor my delusions of grandeur in associating myself with real writers. Instead, focus on the fact that the return value of `someFamousAuthor` is a `String` object, a temporary `String` object (see Item M19). Such objects are transient — their lifetimes generally extend only until the end of the expression containing the call to the function creating them. In this case, that would be until the end of the expression containing the call to `someFamousAuthor`.

Now consider this use of `someFamousAuthor`, in which we assume that `String` declares an `operator` `const` `char*` member function as described above:

    const char *pc = someFamousAuthor();

    cout << pc;                    // uh oh...

Believe it or not, you can't predict what this code will do, at least not with any certainty. That's because by the time you try to print out the sequence of characters pointed to by `pc`, that sequence is undefined. The difficulty arises from the events that transpire during the initialization of `pc`:

1. A temporary `String` object is created to hold `someFamousAuthor`'s return value.
2. That `String` is converted to a `const` `char*` via `String`'s `operator` `const` `char*` member function, and `pc` is initialized with the resulting pointer.
3. The temporary `String` object is destroyed, which means its destructor is called. Within the destructor, its `data` pointer is deleted (the code is shown in Item 11). However, `data` points to the same memory as `pc` does, so `pc` now points to deleted memory — memory with undefined contents.

Because `pc` was initialized with a handle into a temporary object and temporary objects are destroyed shortly after they're created, the handle became invalid before `pc` could do anything with it. For all intents and purposes, `pc` was dead on arrival. Such is the danger of handles into temporary objects.

For `const` member functions, then, returning handles is ill-advised, because it violates abstraction. Even for non-`const` member functions, however, returning handles can lead to trouble, especially when temporary objects get involved. Handles can dangle, just like pointers, and just as you labor to avoid dangling pointers, you should strive to avoid dangling handles, too.

Still, there's no reason to get fascist about it. It's not possible to stomp out all possible dangling pointers in nontrivial programs, and it's rarely possible to eliminate all possible dangling handles, either. Nevertheless, if you avoid returning handles when there's no compelling need, your programs will benefit, and so will your reputation.

Back to Implementation
Continue to Item 30: Avoid member functions that return non-const pointers or references to members less accessible than themselves.