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 chars:

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.