As mentioned earlier, one of the advantages of C++ exception handling is that it allows you to concentrate on the problem you’re actually trying to solve in one place, and then deal with the errors from that code in another place^.

If you’re inside a function and you throw an exception (or a called function throws an exception), the function exits in the process of throwing. If you don’t want a throw to leave a function, you can set up a special block within the function where you try to solve your actual programming problem (and potentially generate exceptions). This block is called the try block because you try your various function calls there. The try block is an ordinary scope, preceded by the keyword try:^.

try {

  // Code that may generate exceptions

}

Of course, the thrown exception must end up some place. This place is the exception handler, and you need one exception handler for every exception type you want to catch. Exception handlers immediately follow the try block and are denoted by the keyword catch:^.

try {

  // Code that may generate exceptions

} catch(type1 id1) {

  // Handle exceptions of type1

} catch(type2 id2) {

  // Handle exceptions of type2

} catch(type3 id3)

  // Etc...

} catch(typeN idN)

  // Handle exceptions of typeN

}

// Normal execution resumes here...

When an exception is thrown, the exception-handling system looks through the "nearest" handlers in the order they appear in the source code. When it finds a match, the exception is considered handled and no further searching occurs^.

Matching an exception doesn’t require a perfect correlation between the exception and its handler. An object or reference to a derived-class object will match a handler for the base class. (However, if the handler is for an object rather than a reference, the exception object is "sliced"— truncated to the base type — as it is passed to the handler; this does no damage but loses all the derived-type information.) For this reason, as well as to avoid making yet another copy of the exception object, it is always better to catch an exception by reference instead of by value[3]. If a pointer is thrown, the usual standard pointer conversions are used to match the exception. However, no automatic type conversions are used to convert from one exception type to another in the process of matching, for example:^.

//: C01:Autoexcp.cpp

// No matching conversions

#include <iostream>

using namespace std;

Sometimes you want to create a handler that catches any type of exception. You do this using the ellipsis in the argument list:^.

Catch(...) {

  cout << "an exception was thrown" << endl;

}

You usually want to re-throw an exception when you have some resource that needs to be released, such as a network connection or heap memory that needs to be deallocated. (See the section "Resource Management" later in this chapter for more detail). If an exception occurs, you don’t necessarily care what error caused the exception—you just want to close the connection you opened previously. After that, you’ll want to let some other context closer to the user (that is, higher up in the call chain) handle the exception. In this case the ellipsis specification is just what you want. You want to catch any exception, clean up your resource, and then re-throw the exception so that it can be handled elsewhere. You re-throw an exception by using throw with no argument inside a handler:^.

catch(...) {

cout << "an exception was thrown" << endl;

// Deallocate your resource here, and then re-throw…

  throw;

}

Part of the magic of exception handling is that you can pop from normal program flow into the appropriate exception handler. Doing so wouldn’t be useful, however, if things weren’t cleaned up properly as the exception was thrown. C++ exception handling guarantees that as you leave a scope, all objects in that scope whose constructors have been completed will have destructors called^.

Here’s an example that demonstrates that constructors that aren’t completed don’t have the associated destructors called. It also shows what happens when an exception is thrown in the middle of the creation of an array of objects:^.

//: C01:Cleanup.cpp

// Exceptions clean up complete objects only

#include <iostream>

using namespace std;

When writing code with exceptions, it’s particularly important that you always ask, "If an exception occurs, will my resources be properly cleaned up?" Most of the time you’re fairly safe, but in constructors there’s a particular problem: if an exception is thrown before a constructor is completed, the associated destructor will not be called for that object. Thus, you must be especially diligent while writing your constructor^.

The general difficulty is allocating resources in constructors. If an exception occurs in the constructor, the destructor doesn’t get a chance to deallocate the resource. This problem occurs most often with "naked" pointers. For example:^.

//: C01:Rawp.cpp

// Naked pointers

#include <iostream>

using namespace std;

To prevent such resource leaks, you must guard against these "raw" resource allocations in one of two ways:

·         You can catch exceptions inside the constructor and then release the resource.

·         You can place the allocations inside an object’s constructor, and you can place the deallocations inside an object’s destructor.

Using the latter approach, each allocation becomes atomic, by virtue of being part of the lifetime of a local object, and if it fails, the other resource allocation objects are properly cleaned up during stack unwinding. This technique is called Resource Acquisition Is Initialization (RAII for short) , because it equates resource control with object lifetime. Using templates is an excellent way to modify the previous example to achieve this:^.

//: C01:Wrapped.cpp

// Safe, atomic pointers

#include <iostream>

using namespace std;

Since dynamic memory is the most frequent resource used in a typical C++ program, the standard provides an RAII wrapper for pointers to heap memory that automatically frees the memory. The auto_ptr class template, defined in the <memory> header, has a constructor that takes a pointer to its generic type (whatever you use in your code). The auto_ptr class template also overloads the pointer operators * and -> to forward these operations to the original pointer the auto_ptr object is holding. You can, therefore, use the auto_ptr object as if it were a raw pointer. Here’s how it works:^.

//: C01:Auto_ptr.cpp

// Illustrates the RAII nature of auto_ptr

#include <memory>

#include <iostream>

using namespace std;

Since constructors can routinely throw exceptions, you might want to handle exceptions that occur when an object’s member or base subobjects are initialized. To do this, you can place the initialization of such subobjects in a function-level try block. In a departure from the usual syntax, the try block for constructor initializers is the constructor body, and the associated catch block follows the body of the constructor, as in the following example^.

//: C01:InitExcept.cpp

// Handles exceptions from subobjects

//{-bor}

#include <iostream>

using namespace std;

You’re not required to inform the people using your function what exceptions you might throw. Failure to do so can be considered uncivilized, however, because it means that users cannot be sure what code to write to catch all potential exceptions. Of course, if they have your source code, they can hunt through and look for throw statements, but often a library doesn’t come with sources. Good documentation can help alleviate this problem, but how many software projects are well documented? C++ provides syntax that allows you to tell the user what exceptions this function throws, so the user can handle them. This is the optional exception specification, which adorns a function’s declaration, appearing after the argument list^.

The exception specification reuses the keyword throw, followed by a parenthesized list of all the types of potential exceptions that the function can throw. Your function declaration might look like this:^.

void f() throw(toobig, toosmall, divzero);

You may feel that the existing exception specification rules aren’t very safe, and that

void f();

Each public function in a class essentially forms a contract with the user; if you pass it certain arguments, it will perform certain operations and/or return a result. The same contract must hold true in derived classes; otherwise the expected "is-a" relationship between derived and base classes is violated. Since exception specifications are logically part of a function’s declaration, they too must remain consistent across an inheritance hierarchy. For example, if a member function in a base class says it will only throw an exception of type A, an override of that function in a derived class must not add any other exception types to the specification list, because that would result in unexpected exceptions for the user, breaking any programs that adhere to the base class interface. You can, however, specify fewer exceptions or none at all, since that doesn’t require the user to do anything differently. You can also specify anything that "is-a" A in place of A in the derived function’s specification. Here’s an example^.

// C01:Covariance.cpp

// Compile Only!

//{-msc}

#include <iostream>

using namespace std;

If you peruse the function declarations throughout the Standard C++ library, you’ll find that not a single exception specification occurs anywhere! Although this might seem strange, there is a good reason for this seeming incongruity: the library consists mainly of templates, and you never know what a generic might do. For example, suppose you are developing a generic stack template and attempt to affix an exception specification to your pop function, like this:

T pop() throw(logic_error);

For most programmers, especially C programmers, exceptions are not available in their existing language and take a bit of adjustment. Here are some guidelines for programming with exceptions^.

Writing software is all about meeting requirements.[18] It doesn’t take much experience, however, to figure out that coming up with requirements in the first place is no easy task, and, more important, requirements are not static. It’s not unheard of to discover at a weekly project meeting that what you just spent the week doing is not exactly what the users really want^.

Frustrating? Yes. Reasonable? Also, yes! It is unreasonable to expect mere humans to be able to articulate software requirements in detail without sampling an evolving, working system. It's much better to specify a little, design a little, code a little, test a little. Then, after evaluating the outcome, do it all over again. The ability to develop from soup to nuts in such an iterative fashion is one of the great advances of this object-oriented era in software history. It requires nimble programmers who can craft resilient code. Change is hard^.

Ironically, another impetus for change comes from you, the programmer. The craftsperson in you likely has the habit of continually improving the physical design of working code. What maintenance programmer hasn’t had occasion to curse the aging, flagship company product as a convoluted patchwork of spaghetti, wholly resistant to modification? Management’s knee-jerk reluctance to let you tamper with a functioning system, while not totally unfounded, robs code of the resilience it needs to endure. "If it’s not broken, don’t fix it" eventually gives way to, "We can’t fix it—rewrite it." Change is necessary^.

Fortunately, our industry has finally gotten used to the discipline of refactoring, the art of internally restructuring code to improve its design, without changing the functionality visible to the user.[19] Such tweaks include extracting a new function from another, or its inverse, combining member functions; replacing a member function with an object; parameterizing a member function or class; and replacing conditionals with polymorphism. Refactoring helps code embrace evolution^.

Whether the force for change comes from users or programmers, however, there is still the risk that changes today will break what worked yesterday. What is needed is a way to build code that withstands the winds of change and actually improves over time^.

Many practices purport to support such a quick-on-your-feet motif, of which Extreme Programming is only one.[20] In this section we explore what we think is the key to making flexible, incremental development succeed: a ridiculously easy-to-use automated unit test framework. (Please note that we in no way mean to de-emphasize the role of testers, software professionals who test others’ code for a living. They are indispensable. We are merely describing a way to help developers write better code.)^.

Developers write unit tests to gain the confidence to say the two most important things that any developer can say:

1.I understand the requirements.

2.My code meets those requirements to the best of my knowledge.

There is no better way to ensure that you know what the code you're about to write should do than to write the unit tests first. This simple exercise helps focus the mind on the task ahead and will likely lead to working code faster than just jumping into coding. Or, to express it in XP terms: Testing + Programming is faster than just Programming. Writing tests first also puts you on guard up front against boundary conditions that might cause your code to break, so your code is more robust right out of the chute^.

Once your code passes all your tests, you have the peace of mind that if the system you contribute to isn't working, it's not your fault. The statement "All my tests pass" is a powerful trump card in the workplace that cuts through any amount of politics and hand waving^.

So what does a unit test look like? Too often developers just use some well-behaved input to produce some expected output, which they inspect visually. Two dangers exist in this approach. First, programs don't always receive only well-behaved input. We all know that we should test the boundaries of program input, but it's hard to think about this when you're trying to just get things working. If you write the test for a function first before you start coding, you can wear your "tester hat" and ask yourself, "What could possibly make this break?" Code a test that will prove the function you'll write isn't broken, and then put on your developer hat and make it happen. You'll write better code than if you hadn't written the test first^.

The second danger is that inspecting output visually is tedious and error prone. Most any such thing a human can do a computer can do, but without human error. It's better to formulate tests as collections of Boolean expressions and have a test program report any failures^.

For example, suppose you need to build a Date class that has the following properties:

·         A date can be initialized with a string (YYYYMMDD), three integers (Y, M, D), or nothing (giving today's date).

·         A date object can yield its year, month, and day or a string of the form "YYYYMMDD".

·         All relational comparisons are available, as well as computing the duration between two dates (in years, months, and days).

·         Dates to be compared need to be able to span an arbitrary number of centuries (for example, 1600–2200).

Your class can store three integers representing the year, month, and day. (Just be sure the year is at least 16 bits in size to satisfy the last bulleted item.) The interface for your Date class might look like this:^.

// A first pass at Date.h

#ifndef DATE_H

#define DATE_H

#include <string>

Some automated C++ unit test tools are available on the World Wide Web for download, such as CppUnit.[22] These are well designed and implemented, but our purpose here is not only to present a test mechanism that is easy to use, but also easy to understand internally and even tweak if necessary. So, in the spirit of "TheSimplestThingThatCouldPossiblyWork," we have developed the TestSuite Framework, a namespace named TestSuite that contains two key classes: Test and Suite^.

The Test class is an abstract class you derive from to define a test object. It keeps track of the number of passes and failures for you and displays the text of any test condition that fails. Your main task in defining a test is simply to override the run( ) member function, which should in turn call the test_( ) macro for each Boolean test condition you define^.

To define a test for the Date class using the framework, you can inherit from Test as shown in the following program:

//: C02:DateTest.h

#ifndef DATE_TEST_H

#define DATE_TEST_H

#include "Date.h"

#include "../TestSuite/Test.h"

Real projects usually contain many classes, so you need a way to group tests so that you can just push a single button to test the entire project.[25] The Suite class allows you to collect tests into a functional unit. You derive Test objects to a Suite with the addTest( ) member function, or you can swallow an entire existing suite with addSuite( ). We have a number of date-related classes to illustrate how to use a test suite. Here's an actual test run:^.

// Illustrates a suite of related tests

#include <iostream>

#include "suite.h"         // includes test.h

#include "JulianDateTest.h"

#include "JulianTimeTest.h"

#include "MonthInfoTest.h"

#include "DateTest.h"

#include "TimeTest.h"

using namespace std;

The test framework code library is in a subdirectory called TestSuite in the code distribution available on the MindView website. To use it, include the search path for the TestSuite subdirectory in your header, link the object files, and include the TestSuite subdirectory in the library search path. Here is the header for Test.h:

//: TestSuite:Test.h

#ifndef TEST_H

#define TEST_H

#include <string>

#include <iostream>

#include <cassert>

using std::string;

using std::ostream;

using std::cout;

The best debugging habit to get into is to use assertions as explained in the beginning of this chapter; by doing so you’ll be more likely to find logic errors before they cause real trouble. This section contains some other tips and techniques that might help during debugging^.

Sometimes it’s helpful to print the code of each statement as it is executed, either to cout or to a trace file. Here’s a preprocessor macro to accomplish this:^.

#define TRACE(ARG) cout << #ARG << endl; ARG

DISCLAIMER: This section and the next contain code which is officially unsanctioned by the C++ standard. In particular, we redefine cout and new via macros, which can cause surprising results if you’re not careful. Our examples work on all the compilers we use, however, and provide useful information. This is the only place in this book where we will depart from the sanctity of standard-compliant coding practice. Use at your own risk!

The following code allows you to easily create a trace file and send all the output that would normally go to cout into the file. All you have to do is #define TRACEON and include the header file (of course, it’s fairly easy just to write the two key lines right into your file):^.

//: C03:Trace.h

// Creating a trace file

#ifndef TRACE_H

#define TRACE_H

#include <fstream>

If you’ve programmed in C, you are accustomed to the convenience of a large family of functions for writing, searching, modifying, and copying char arrays. However, there are two unfortunate aspects of the Standard C library functions for handling char arrays. First, there are two loosely organized families of them: the "plain" group, and the ones that require you to supply a count of the number of characters to be considered in the operation at hand. The roster of functions in the C char array handling library shocks the unsuspecting user with a long list of cryptic, mostly unpronounceable names. Although the kinds and number of arguments to the functions are somewhat consistent, to use them properly you must be attentive to details of function naming and parameter passing^.

The second inherent trap of the standard C char array tools is that they all rely explicitly on the assumption that the character array includes a null terminator. If by oversight or error the null is omitted or overwritten, there’s little to keep the C char array handling functions from manipulating the memory beyond the limits of the allocated space, sometimes with disastrous results^.

C++ provides a vast improvement in the convenience and safety of string objects. For purposes of actual string handling operations, there are about the same number of distinct member function names in the string class as there are functions in the C library, but because of overloading there is much more functionality. Coupled with sensible naming practices and the judicious use of default arguments, these features combine to make the string class much easier to use than the C library^.

One of the most valuable and convenient aspects of C++ strings is that they grow as needed, without intervention on the part of the programmer. Not only does this make string-handling code inherently more trustworthy, it also almost entirely eliminates a tedious "housekeeping" chore—keeping track of the bounds of the storage in which your strings live. For example, if you create a string object and initialize it with a string of 50 copies of ‘X’, and later store in it 50 copies of "Zowie", the object itself will reallocate sufficient storage to accommodate the growth of the data. Perhaps nowhere is this property more appreciated than when the strings manipulated in your code change size and you don’t know how big the change is. Appending, concatenating, and inserting strings often give rise to this circumstance, but the string member functions append( ) and insert( ) transparently reallocate storage when a string grows^.

//: C03:StrSize.cpp

#include <string>

#include <iostream>

using namespace std;

The insert( ) function is particularly nice because it absolves you of making sure the insertion of characters in a string won’t overrun the storage space or overwrite the characters immediately following the insertion point. Space grows, and existing characters politely move over to accommodate the new elements. Sometimes, however, this might not be what you want to happen. If you want the size of the string to remain unchanged, use the replace( ) function to overwrite characters. There are quite a number of overloaded versions of replace( ), but the simplest one takes three arguments: an integer indicating where to start in the string, an integer indicating how many characters to eliminate from the original string, and the replacement string (which can be a different number of characters than the eliminated quantity). Here’s a simple example:^.

//: C03:StringReplace.cpp

// Simple find-and-replace in strings

#include <cassert>

#include <string>

using namespace std;

One of the most delightful discoveries awaiting a C programmer learning about C++ string handling is how simply strings can be combined and appended using operator+ and operator+=. These operators make combining strings syntactically similar to adding numeric data^.

//: C03:AddStrings.cpp

#include <string>

#include <cassert>

using namespace std;

The find family of string member functions allows you to locate a character or group of characters within a given string. Here are the members of the find family and their general usage :

Sometimes it’s necessary to search through a string from end to beginning, if you need to find the data in "last in / first out" order. The string member function rfind( ) handles this job^.

//: C03:Rparse.cpp

//{L} ../TestSuite/Test

#include <string>

#include <vector>

#include "../TestSuite/Test.h"

using namespace std;

The find_first_of( ) and find_last_of( ) member functions can be conveniently put to work to create a little utility that will strip whitespace characters from both ends of a string. Notice that it doesn’t touch the original string, but instead returns a new string:^.

//: C03:Trim.h

#ifndef TRIM_H

#define TRIM_H

#include <string>

// General tool to strip spaces from both ends:

inline std::string trim(const std::string& s) {

  if(s.length() == 0)

    return s;

  int beg = s.find_first_not_of(" \a\b\f\n\r\t\v");

  int end = s.find_last_not_of(" \a\b\f\n\r\t\v");

  if(beg == std::string::npos) // No non-spaces

    return "";

  return std::string(s, beg, end - beg + 1);

}

#endif // TRIM_H ///:~

Removing characters is easy and efficient with the erase( ) member function, which takes two arguments: where to start removing characters (which defaults to 0), and how many to remove (which defaults to string::npos). If you specify more characters than remain in the string, the remaining characters are all erased anyway (so calling erase( ) without any arguments removes all characters from a string). Sometimes it’s useful to take an HTML file and strip its tags and special characters so that you have something approximating the text that would be displayed in the Web browser, only as a plain text file. The following uses erase( ) to do the job:^.

//: C03:HTMLStripper.cpp

//{L} ReplaceAll

// Filter to remove html tags and markers

#include <cassert>

#include <cmath>

#include <cstddef>

#include <fstream>

#include <iostream>

#include <string>

#include "../require.h"

using namespace std;

Comparing strings is inherently different from comparing numbers. Numbers have constant, universally meaningful values. To evaluate the relationship between the magnitudes of two strings, you must make a lexical comparison. Lexical comparison means that when you test a character to see if it is "greater than" or "less than" another character, you are actually comparing the numeric representation of those characters as specified in the collating sequence of the character set being used. Most often this will be the ASCII collating sequence, which assigns the printable characters for the English language numbers in the range 32 through 127 decimal. In the ASCII collating sequence, the first "character" in the list is the space, followed by several common punctuation marks, and then uppercase and lowercase letters. With respect to the alphabet, this means that the letters nearer the front have lower ASCII values than those nearer the end. With these details in mind, it becomes easier to remember that when a lexical comparison that reports s1 is "greater than" s2, it simply means that when the two were compared, the first differing character in s1 came later in the alphabet than the character in that same position in s2^.

C++ provides several ways to compare strings, and each has advantages. The simplest to use are the nonmember, overloaded operator functions: operator ==, operator != operator >, operator <, operator >=, and operator <=^.

//: C03:CompStr.cpp

//{L} ../TestSuite/Test

#include <string>

#include "../TestSuite/Test.h"

using namespace std;

The program Find.cpp earlier in this chapter leads us to ask the obvious question: Why isn’t case-insensitive comparison part of the standard string class? The answer provides interesting background on the true nature of C++ string objects^.

Consider what it means for a character to have "case." Written Hebrew, Farsi, and Kanji don’t use the concept of upper- and lowercase, so for those languages this idea has no meaning. It would seem that if there were a way to designate some languages as "all uppercase" or "all lowercase," we could design a generalized solution. However, some languages that employ the concept of "case" also change the meaning of particular characters with diacritical marks: for example, the cedilla in Spanish, the circumflex in French, and the umlaut in German. For this reason, any case-sensitive collating scheme that attempts to be comprehensive will be nightmarishly complex to use^.

Although we usually treat the C++ string as a class, this is really not the case. The string type is actually a specialization of a more general constituent, the basic_string< > template. Observe how string is declared in the standard C++ header file:[35]

typedef basic_string<char> string;

All these issues make it clear that one of the first priorities for the standard class libraries for C++ should handle I/O. Because "hello, world" is the first program just about everyone writes in a new language, and because I/O is part of virtually every program, the I/O library in C++ must be particularly easy to use. It also has the much greater challenge that it must accommodate any new class. Thus, its constraints require that this foundation class library be a truly inspired design. In addition to gaining a great deal of leverage and clarity in your dealings with I/O and formatting, you’ll also see in this chapter how a really powerful C++ library can work^.

A stream is an object that transports and formats characters of a fixed width. You can have an input stream (via descendants of the istream class), an output stream (with ostream objects), or a stream that does both simultaneously (with objects derived from iostream). The iostreams library provides different types of such classes: ifstream, ofstream, and fstream for files, and istringstream, ostringstream, and stringstream for interfacing with the Standard C++ string class. All these stream classes have nearly identical interfaces, so you can use streams in a uniform manner, whether you’re working with a file, standard I/O, a region of memory, or a string object. The single interface you learn also works for extensions added to support new classes. Some functions implement your formatting commands, and some functions read and write characters without formatting^.

The stream classes mentioned earlier are actually template specializations,[39] much like the standard string class is a specialization of the basic_string template. The basic classes in the iostreams inheritance hierarchy are shown in the following figure^.

The ios_base class declares everything that is common to all streams, independent of the type of character the stream handles. These declarations are mostly constants and functions to manage them, some of which you’ll see throughout this chapter. The rest of the classes are templates that have the underlying character type as a parameter. The istream class, for example, is defined as follows:^.

typedef basic_istream<char> istream;

As the Date extractor illustrated, you must be on guard for erroneous input. If the input produces an unexpected value, the process is skewed, and it’s difficult to recover. In addition, formatted input defaults to white space delimiters. Consider what happens when we collect the code fragments from earlier in this chapter into a single program:^.

//: C04:Iosexamp.cpp

// Iostream examples

#include <iostream>

using namespace std;

The Date extractor shown earlier sets a stream’s fail bit under certain conditions. How does the user know when such a failure occurs? You can detect stream errors by either calling certain stream member functions to see if an error state has occurred, or if you don’t care what the particular error was, you can just evaluate the stream in a Boolean context. Both techniques derive from the state of a stream’s error bits^.

Manipulating files with iostreams is much easier and safer than using stdio in C. All you do to open a file is create an object; the constructor does the work. You don’t have to explicitly close a file (although you can, using the close( ) member function) because the destructor will close it when the object goes out of scope. To create a file that defaults to input, make an ifstream object. To create one that defaults to output, make an ofstream object. An fstream object can do both input and output^.

The file stream classes fit into the iostreams classes as shown in the following figure.

Here’s an example that shows many of the features discussed so far. Notice the inclusion of <fstream> to declare the file I/O classes. Although on many platforms this will also include <iostream> automatically, compilers are not required to do so. If you want portable code, always include both headers^.

//: C04:Strfile.cpp

// Stream I/O with files

// The difference between get() & getline()

#include <fstream>

#include <iostream>

#include "../require.h"

using namespace std;

You can control the way a file is opened by overriding the constructor’s default arguments. The following table shows the flags that control the mode of the file:^.

A string stream works directly with memory instead of a file or standard output. It allows you to use the same reading and formatting functions that you use with cin and cout to manipulate bytes in memory. On old computers, the memory was referred to as core, so this type of functionality is often called in-core formatting^.

The class names for string streams echo those for file streams. If you want to create a string stream to extract characters from, you create an istringstream. If you want to put characters into a string stream, you create an ostringstream. All declarations for string stream are in the standard header <sstream>. As usual, there are class templates that fit into the iostreams hierarchy, as shown in the following figure:^.

To read from a string using stream operations, you create an istringstream object initialized with the string. The following program shows how to use an istringstream object.

//: C04:Istring.cpp

// Input string streams

#include <cassert>

#include <cmath>  // For fabs()

#include <iostream>

#include <limits> // For epsilon()

#include <sstream>

#include <string>

using namespace std;

To create an output string stream to put data into, you just create an ostringstream object, which manages a dynamically sized character buffer to hold whatever you insert. To get the formatted result as a string object, you call the str( ) member function. Here’s an example:^.

//: C04:Ostring.cpp

// Illustrates ostringstream

#include <iostream>

#include <sstream>

#include <string>

using namespace std;

The goal of the iostreams design is to allow you to easily move and/or format characters. It certainly wouldn’t be useful if you couldn’t do most of the formatting provided by C’s printf( ) family of functions. In this section, you’ll learn all the output formatting functions that are available for iostreams, so you can format your bytes the way you want them^.

The formatting functions in iostreams can be somewhat confusing at first because there’s often more than one way to control the formatting: through both member functions and manipulators. To further confuse things, a generic member function sets state flags to control formatting, such as left or right justification, to use uppercase letters for hex notation, to always use a decimal point for floating-point values, and so on. On the other hand, separate member functions set and read values for the fill character, the field width, and the precision^.

In an attempt to clarify all this, we’ll first examine the internal formatting data of an iostream , along with the member functions that can modify that data. (Everything can be controlled through the member functions, if desired.) We’ll cover the manipulators separately^.

The class ios contains data members to store all the formatting information pertaining to a stream. Some of this data has a range of values and is stored in variables: the floating-point precision, the output field width, and the character used to pad the output (normally a space). The rest of the formatting is determined by flags, which are usually combined to save space and are referred to collectively as the format flags. You can find out the value of the format flags with the ios::flags( ) member function, which takes no arguments and returns an object of type fmtflags (usually a synonym for long) that contains the current format flags. All the rest of the functions make changes to the format flags and return the previous value of the format flags^.

fmtflags ios::flags(fmtflags newflags);

fmtflags ios::setf(fmtflags ored_flag);

fmtflags ios::unsetf(fmtflags clear_flag);

fmtflags ios::setf(fmtflags bits, fmtflags field);

The second type of formatting flags work in a group. Only one of these flags can be, like the buttons on old car radios—you push one in, the rest pop out. Unfortunately this doesn’t happen automatically, and you have to pay attention to what flags you’re setting so that you don’t accidentally call the wrong setf( ) function. For example, there’s a flag for each of the number bases: hexadecimal, decimal, and octal. Collectively, these flags are referred to as the ios::basefield. If the ios::dec flag is set and you call setf(ios::hex), you’ll set the ios::hex flag, but you won’t clear the ios::dec bit, resulting in undefined behavior. The proper thing to do is call the second form of setf( ) like this: setf(ios::hex, ios::basefield). This function first clears all the bits in the ios::basefield and then sets ios::hex. Thus, this form of setf( ) ensures that the other flags in the group "pop out" whenever you set one. Of course, the ios::hex manipulator does all this for you, automatically, so you don’t have to concern yourself with the internal details of the implementation of this class or to even care that it’s a set of binary flags. Later you’ll see that there are manipulators to provide equivalent functionality in all the places you would use setf( )^.

Here are the flag groups and their effects:

The internal variables that control the width of the output field, the fill character used to pad an output field, and the precision for printing floating-point numbers are read and written by member functions of the same name^.

The fill and precision values are fairly straightforward, but width requires some explanation. When the width is zero, inserting a value produces the minimum number of characters necessary to represent that value. A positive width means that inserting a value will produce at least as many characters as the width; if the value has fewer than width characters, the fill character is used to pad the field. However, the value will never be truncated, so if you try to print 123 with a width of two, you’ll still get 123. The field width specifies a minimum number of characters; there’s no way to specify a maximum number^.

The width is also distinctly different because it’s reset to zero by each inserter or extractor that could be influenced by its value. It’s really not a state variable, but rather an implicit argument to the inserters and extractors. If you want a constant width, call width( ) after each insertion or extraction^.

To make sure you know how to call all the functions previously discussed, here’s an example that calls them all:^.

//: C04:Format.cpp

// Formatting Functions

#include <fstream>

#include <iostream>

#include "../require.h"

using namespace std;

#define D(A) T << #A << endl; A

As you can see from the previous program, calling the member functions for stream formatting operations can get a bit tedious. To make things easier to read and write, a set of manipulators is supplied to duplicate the actions provided by the member functions. Manipulators are a convenience because you can insert them for their effect within a containing expression; you don’t have to create a separate function-call statement^.

Manipulators change the state of the stream instead of (or in addition to) processing data. When you insert endl in an output expression, for example, it not only inserts a newline character, but it also flushes the stream (that is, puts out all pending characters that have been stored in the internal stream buffer but not yet output). You can also just flush a stream like this:^.

cout << flush;

There are six standard manipulators, such as setw( ), that take arguments. These are defined in the header file <iomanip>, and are summarized in the following table.

If you’re doing a lot of formatting, you can see how using manipulators instead of calling stream member functions can clean up your code. As an example, here’s the program from the previous section rewritten to use the manipulators. (The D( ) macro is removed to make it easier to read.)^.

//: C04:Manips.cpp

// Format.cpp using manipulators

#include <fstream>

#include <iomanip>

#include <iostream>

using namespace std;

Sometimes you’d like to create your own manipulators, and it turns out to be remarkably simple. A zero-argument manipulator such as endl is simply a function that takes as its argument an ostream reference and returns an ostream reference. The declaration for endl is^.

ostream& endl(ostream&);

As you’ve seen, zero-argument manipulators are easy to create. But what if you want to create a manipulator that takes arguments? If you inspect the <iomanip> header, you’ll see a type called smanip, which is what the manipulators with arguments return. You might be tempted to somehow use that type to define your own manipulators, but don’t give in to the temptation. The smanip type is implementation-dependent, so using it would not be portable. Fortunately, you can define such manipulators in a straightforward way without any special machinery, based on a technique introduced by Jerry Schwarz, called an effector.[46] An effector is a simple class whose constructor formats a string representing the desired operation, along with an overloaded operator<< to insert that string into a stream. Here’s an example with two effectors. The first outputs a truncated character string, and the second prints a number in binary^.

//: C04:Effector.cpp

// Jerry Schwarz's "effectors"

#include <cassert>

#include <limits>  // For max()

#include <sstream>

#include <string>

using namespace std;

In this section you’ll see some examples of what you can do with all the information you’ve learned in this chapter. Although many tools exist to manipulate bytes (stream editors such as sed and awk from UNIX are perhaps the most well known, but a text editor also fits this category), they generally have some limitations. Both sed and awk can be slow and can only handle lines in a forward sequence, and text editors usually require human interaction, or at least learning a proprietary macro language. The programs you write with iostreams have none of these limitations: they’re fast, portable, and flexible^.

Generally, when you create a class, you think in library terms: you make a header file Name.h for the class declaration, and you create a file in which the member functions are implemented, called Name.cpp. These files have certain requirements: a particular coding standard (the program shown here uses the coding format for this book), and in the header file the declarations are generally surrounded by some preprocessor statements to prevent multiple declarations of classes. (Multiple declarations confuse the compiler—it doesn’t know which one you want to use. They could be different, so it throws up its hands and gives an error message.)^.

This example allows you to create a new header/implementation pair of files or to modify an existing pair. If the files already exist, it checks and potentially modifies the files, but if they don’t exist, it creates them using the proper format^.

//: C04:Cppcheck.cpp

// Configures .h & .cpp files to conform to style

// standard. Tests existing files for conformance.

#include <fstream>

#include <sstream>

#include <string>

#include "../require.h"

using namespace std;

All the code in this book is designed to compile as shown without errors. Any line of code that should generate a compile-time error is commented out with the special comment sequence "//!". The following program will remove these special comments and append a numbered comment to the line. When you run your compiler, it should generate error messages, and you will see all the numbers appear when you compile all the files. This program also appends the modified line to a special file so that you can easily locate any lines that don’t generate errors^.

//: C04:Showerr.cpp

// Un-comment error generators

#include <cstddef>

#include <cstdlib>

#include <cstdio>

#include <fstream>

#include <iostream>

#include <sstream>

#include <string>

#include "../require.h"

using namespace std;

The software industry is now a healthy, worldwide economic market, and applications that can run in various languages and cultures are in demand. As early as the late 1980s, the C Standards Committee added support for non-U.S. formatting conventions with their locale mechanism. A locale is a set of preferences for displaying certain entities such as dates and monetary quantities. In the 1990s, the C Standards Committee approved an addendum to Standard C that specified functions to handle wide characters (denoted by the type wchar_t), which allow support for character sets other than ASCII and its commonly used Western European extensions. Although the size of a wide character is not specified, some platforms implement them as 32-bit quantities, so they can hold the encodings specified by the Unicode Consortium, as well as mappings to multi-byte characters sets defined by Asian standards bodies. C++ has integrated support for both wide characters and locales into the iostreams library^.

A wide stream is a simply a stream class that handles wide characters. All the examples so far (except for the last traits example in Chapter 3) have used narrow streams, meaning streams that hold instances of char. Since stream operations are essentially the same no matter the underlying character type, they are encapsulated generically as templates. As we mentioned earlier, all input streams, for example, are connected somehow to the basic_istream class template, which is defined as follows:

template<class charT, class traits = char_traits<charT> >

class basic_istream {…};

Perhaps the most notable difference in typical numeric computer output from country to country is the punctuator used to separate the integer and fractional parts of a real number. In the United States, a period denotes a decimal point, but in much of the world, a comma is expected instead. It would be quite inconvenient to do all your own formatting for locale-dependent displays. Once again, creating an abstraction that handles these differences solves the problem.

That abstraction is the locale. All streams have an associated locale object that they use for guidance on how to display certain quantities for different cultural environments. A locale manages the categories of culture-dependent display rules, which are defined as follows:

As we illustrated in Volume 1, templates come in two flavors: function templates and class templates. Both are wholly characterized by their parameters. Each template parameter itself can represent one of the following categories of arguments:

1.       Types (either built-in or user-defined)