C++ Primer, Fifth Edition

Appearance

3.1. Namespace using Declarations

Fundamental

Up to now, our programs have explicitly indicated that each library name we use is in the std namespace. For example, to read from the standard input, we write std::cin. These names use the scope operator (::) (§ 1.2, p. 8), which says that the compiler should look in the scope of the left-hand operand for the name of the right-hand operand. Thus, std::cin says that we want to use the name cin from the namespace std.

Referring to library names with this notation can be cumbersome. Fortunately, there are easier ways to use namespace members. The safest way is a usingdeclaration. § 18.2.2 (p. 793) covers another way to use names from a namespace.

A using declaration lets us use a name from a namespace without qualifying the name with a namespace_name:: prefix. A using declaration has the form

c++
using namespace::name;

Once the using declaration has been made, we can access name directly:

c++
#include <iostream>
// using declaration; when we use the name cin, we get the one from the namespace std
using std::cin;
int main()
{
    int i;
    cin >> i;       // ok: cin is a synonym for std::cin
    cout << i;      // error: no using declaration; we must use the full name
    std::cout << i; // ok: explicitly use cout from namepsace std
    return 0;
}

A Separate using Declaration Is Required for Each Name

Each using declaration introduces a single namespace member. This behavior lets us be specific about which names we’re using. As an example, we’ll rewrite the program from § 1.2 (p. 6) with using declarations for the library names it uses:

c++
#include <iostream>
// using declarations for names from the standard library
using std::cin;
using std::cout; using std::endl;
int main()
{
    cout << "Enter two numbers:" << endl;
    int v1, v2;
    cin >> v1 >> v2;
    cout << "The sum of " << v1 << " and " << v2
         << " is " << v1 + v2 << endl;
    return 0;
}

The using declarations for cin, cout, and endl mean that we can use those names without the std:: prefix. Recall that C++ programs are free-form, so we can put each using declaration on its own line or combine several onto a single line. The important part is that there must be a using declaration for each name we use, and each declaration must end in a semicolon.

Headers Should Not Include using Declarations

Code inside headers (§ 2.6.3, p. 76) ordinarily should not use using declarations. The reason is that the contents of a header are copied into the including program’s text. If a header has a using declaration, then every program that includes that header gets that same using declaration. As a result, a program that didn’t intend to use the specified library name might encounter unexpected name conflicts.

A Note to the Reader

From this point on, our examples will assume that using declarations have been made for the names we use from the standard library. Thus, we will refer to cin, not std::cin, in the text and in code examples.

Moreover, to keep the code examples short, we won’t show the using declarations, nor will we show the necessary #include directives. Table A.1 (p. 866) in Appendix A lists the names and corresponding headers for standard library names we use in this Primer.

WARNING

Readers should be aware that they must add appropriate #include and using declarations to our examples before compiling them.

INFO

Exercises Section 3.1

Exercise 3.1: Rewrite the exercises from § 1.4.1 (p. 13) and § 2.6.2 (p. 76) with appropriate using declarations.