There’s not much in C++ you couldn’t manage using C, given enough effort. I both use and bitch about C++ and sometimes it’s good to get back to the plain and wholesome taste of C. Not for long though: I start to miss the standard containers and algorithms, operator overloading, exceptions etc.

I mention this because I’ve been thinking about what makes good software documentation. If I’m working with the C standard library, I tend to refer to the man pages for help, and very fine they are too. Apparently man pages for the C++ standard library exist but they don’t come as standard on my platform and I haven’t installed them — instead I refer to the SGI STL Programmer’s Guide, which I’ve downloaded locally for instant and offline access. Now, it’s clear this guide hasn’t been actively maintained (the “What’s New” page lists nothing more recent than June 2000): it includes non-standard extensions and in some places I’ve found it’s no longer correct^[1]. Nonetheless, its clear exposition and clean layout make it my first point of reference.

C++’s standard map container bears a superficial resemblance to Python’s dict, associating keys with values (under the surface, a map is a balanced tree and a dict is a hash table^[2]). Like Python, the [] operator syntax can be used for container access. Unlike Python, accessing the value associated with a key not present in the map succeeds — the key gets added and the value is default constructed^[3]. Here’s how the SGI guide documents this overloading of operator[] (emphasis mine).

Since operator[] might insert a new element into the map, it can’t possibly be a const member function. Note that the definition of operator[] is extremely simple: m[k] is equivalent to (*((m.insert(value_type(k, data_type()))).first)).second. Strictly speaking, this member function is unnecessary: it exists only for convenience.

Should reference documentation entertain? This paragraph may not have had me rolling on the floor with laughter, but I did snort in my coffee.

Here’s some compact C++ code designed to showcase the convenience of the operator overload, in this case calculating word frequencies in an istream:

typedef std::string Word;
typedef std::map<Word, int> WordCounts;

void count_words(std::istream & text, WordCounts & word_counts)
{
    Word word;
    while (text >> word)
    {
        ++word_counts[word];
    }
}

Using the supplied definition of operator[], the loop reads:

    while (text >> word)
    {
        ++(*((word_counts.insert
              (WordCounts::value_type(word, WordCounts::mapped_type()))
              .first))).second;
    }

Now, I realise you have to be clever to use C++, and I’m sure there’s a better way of laying out this expression, but can really anyone find it extremely simple?

Syntactic sugar. Pour it on!

[1] For example, in the quoted documentation for operator[], data_type() should now read mapped_type().

[2] TR1 at last brings a standard hash table to C++, which goes under the unlikely name of std::tr1::unordered_map.

[3] Python provides collections.defaultdict if you want this behaviour.