Overloading Stream Insertion and Stream Extraction Operators

C++ is able to input and output the fundamental types using the stream extraction operator >> and the stream insertion operator <<. The class libraries provided with C++ compilers overload these operators to process each fundamental type, including pointers and C-like char * strings. The stream insertion and stream extraction operators also can be overloaded to perform input and output for user-defined types. The program of Figs. 11.3-11.5 demonstrates overloading these operators to handle data of a user-defined telephone number class called PhoneNumber. This program assumes telephone numbers are input correctly.

Figure 11.3. PhoneNumber class with overloaded stream insertion and stream extraction operators as friend functions.

(This item is displayed on pages 577 - 578 in the print version)

 1 // Fig. 11.3: PhoneNumber.h
 2 // PhoneNumber class definition
 3 #ifndef PHONENUMBER_H
 4 #define PHONENUMBER_H
 5
 6 #include 
 7 using std::ostream;
 8 using std::istream;
 9
10 #include 
11 using std::string;
12
13 class PhoneNumber
14 {
15 friend ostream &operator<<( ostream &, const PhoneNumber & );
16 friend istream &operator>>( istream &, PhoneNumber & ); 
17 private:
18 string areaCode; // 3-digit area code
19 string exchange; // 3-digit exchange
20 string line; // 4-digit line
21 }; // end class PhoneNumber
22
23 #endif

---

The stream extraction operator function operator>> (Fig. 11.4, lines 2231) takes istream reference input and PhoneNumber reference num as arguments and returns an istream reference. Operator function operator>> inputs phone numbers of the form

 [phone]

 

Figure 11.4. Overloaded stream insertion and stream extraction operators for class PhoneNumber.

(This item is displayed on page 578 in the print version)

 1 // Fig. 11.4: PhoneNumber.cpp
 2 // Overloaded stream insertion and stream extraction operators
 3 // for class PhoneNumber.
 4 #include 
 5 using std::setw;
 6
 7 #include "PhoneNumber.h"
 8
 9 // overloaded stream insertion operator; cannot be 
10 // a member function if we would like to invoke it with 
11 // cout << somePhoneNumber; 
12 ostream &operator<<( ostream &output, const PhoneNumber &number )
13 { 
14  output << "(" << number.areaCode << ") " 
15  << number.exchange << "-" << number.line; 
16  return output; // enables cout << a << b << c; 
17 } // end function operator<< 
18
19 // overloaded stream extraction operator; cannot be 
20 // a member function if we would like to invoke it with 
21 // cin >> somePhoneNumber; 
22 istream &operator>>( istream &input, PhoneNumber &number ) 
23 { 
24  input.ignore(); // skip ( 
25  input >> setw( 3 ) >> number.areaCode; // input area code
26  input.ignore( 2 ); // skip ) and space 
27  input >> setw( 3 ) >> number.exchange; // input exchange 
28  input.ignore(); // skip dash (-) 
29  input >> setw( 4 ) >> number.line; // input line 
30  return input; // enables cin >> a >> b >> c; 
31 } // end function operator>> 

into objects of class PhoneNumber. When the compiler sees the expression

 cin >> phone

in line 19 of Fig. 11.5, the compiler generates the global function call

 operator>>( cin, phone );

 

Figure 11.5. Overloaded stream insertion and stream extraction operators.

(This item is displayed on pages 578 - 579 in the print version)

 1 // Fig. 11.5: fig11_05.cpp
 2 // Demonstrating class PhoneNumber's overloaded stream insertion
 3 // and stream extraction operators.
 4 #include 
 5 using std::cout;
 6 using std::cin;
 7 using std::endl;
 8
 9 #include "PhoneNumber.h"
10
11 int main()
12 {
13 PhoneNumber phone; // create object phone
14
15 cout << "Enter phone number in the form [phone]:" << endl;
16
17 // cin >> phone invokes operator>> by implicitly issuing
18 // the global function call operator>>( cin, phone ) 
19 cin >> phone; 
20
21 cout << "The phone number entered was: ";
22
23 // cout << phone invokes operator<< by implicitly issuing
24 // the global function call operator<<( cout, phone ) 
25 cout << phone << endl; 
26 return 0;
27 } // end main

 

 Enter phone number in the form [phone]:
 [phone]
 The phone number entered was: [phone]

 

When this call executes, reference parameter input (Fig. 11.4, line 22) becomes an alias for cin and reference parameter number becomes an alias for phone. The operator function reads as strings the three parts of the telephone number into the areaCode (line 25), exchange (line 27) and line (line 29) members of the PhoneNumber object referenced by parameter number. Stream manipulator setw limits the number of characters read into each character array. When used with cin and strings, setw restricts the number of characters read to the number of characters specified by its argument (i.e., setw( 3 ) allows three characters to be read). The parentheses, space and dash characters are skipped by calling istream member function ignore (Fig. 11.4, lines 24, 26 and 28), which discards the specified number of characters in the input stream (one character by default). Function operator>> returns istream reference input (i.e., cin). This enables input operations on PhoneNumber objects to be cascaded with input operations on other PhoneNumber objects or on objects of other data types. For example, a program can input two PhoneNumber objects in one statement as follows:

---

 cin >> phone1 >> phone2;

First, the expression cin >> phone1 executes by making the global function call

 operator>>( cin, phone1 );

This call then returns a reference to cin as the value of cin >> phone1, so the remaining portion of the expression is interpreted simply as cin >> phone2. This executes by making the global function call

 operator>>( cin, phone2 );

The stream insertion operator function (Fig. 11.4, lines 1217) takes an ostream reference (output) and a const PhoneNumber reference (number) as arguments and returns an ostream reference. Function operator<< displays objects of type PhoneNumber. When the compiler sees the expression

 cout << phone

in line 25 of Fig. 11.5, the compiler generates the global function call

 operator<<( cout, phone );

Function operator<< displays the parts of the telephone number as strings, because they are stored as string objects.

Error-Prevention Tip 11.1

Returning a reference from an overloaded << or >> operator function is typically successful because cout, cin and most stream objects are global, or at least long-lived. Returning a reference to an automatic variable or other temporary object is dangerouscreating "dangling references" to nonexisting objects.

Note that the functions operator>> and operator<< are declared in PhoneNumber as global, friend functions (Fig. 11.3, lines 1516). They are global functions because the object of class PhoneNumber appears in each case as the right operand of the operator. Remember, overloaded operator functions for binary operators can be member functions only when the left operand is an object of the class in which the function is a member. Overloaded input and output operators are declared as friends if they need to access non-public class members directly for performance reasons or because the class may not offer appropriate get functions. Also note that the PhoneNumber reference in function operator<<'s parameter list (Fig. 11.4, line 12) is const, because the PhoneNumber will simply be output, and the PhoneNumber reference in function operator>>'s parameter list (line 22) is non-const, because the PhoneNumber object must be modified to store the input telephone number in the object.

Software Engineering Observation 11.3

New input/output capabilities for user-defined types are added to C++ without modifying C++'s standard input/output library classes. This is another example of the extensibility of the C++ programming language.