std::, Namespaces and the Headers You Will Actually Include

Bob's contest program starts with #include <bits/stdc++.h>, and on the Playground it compiles and passes. Maria copies it to her Mac, whose compiler is clang with its own library, and it stops at the first line: fatal error: 'bits/stdc++.h' file not found. Nothing in the program is wrong, and still one compiler takes it and another refuses. To see why, you need two ideas: where a standard name lives, and which file brings it into your program. This lesson gives you both, and a table to keep.

A namespace is a named box of names

In C every function name is global, so two libraries cannot both have a sort. C libraries dodge this with a prefix on every name, such as sqlite3_open. C++ has a better tool. A namespace is a named box of names: two boxes can each hold a sort, and they never clash.

namespace box_name {
    declarations: functions, variables, constants
}

box_name::name

Here are two functions called sort in one program, one in a shop's box and one in a school's.

#include <iostream>

namespace shop {
void sort()
{
    std::cout << "shop::sort puts prices cheapest first\n";
}
}

namespace school {
void sort()
{
    std::cout << "school::sort puts marks highest first\n";
}
}

int main()
{
    shop::sort();
    school::sort();
    return 0;
}

shop::sort puts prices cheapest first
school::sort puts marks highest first

The compiler never asks which sort you mean, because each call names its box. main itself lives in no box you made. It sits in the global namespace, the outermost box of every program, where all of C's names live too.

So a namespace lets two pieces of code use the same name, and box::name says which one you mean.

std:: and three ways not to type it

The C++ standard library keeps every one of its names in one namespace, std. That is why lesson 01 wrote std::cout: the cout in the std box. Typing std:: fifty times a program is tiring, so C++ has three ways to skip it.

A using-declaration lets one name in: using std::cout;. A using-directive lets the whole box in: using namespace std;. Each one works from the line it is written on to the end of the block that holds it. Written at the top of the file, that is the rest of the file; written inside a function, it is that function only.

#include <iostream>
#include <string>

using std::cout;

int main()
{
    using std::cin;

    std::string title;
    int pages = 0;
    cin >> title >> pages;
    cout << title << " has " << pages << " pages\n";
    return 0;
}

Matilda has 240 pages

That output is for the input Matilda 240. cout needs no std:: anywhere below its using-declaration, and cin needs none inside main. std::string was never let in, so it keeps its std::.

So cout after any of these is still std::cout. What changes is how many names you let out of the box, and how far.

What using namespace std costs, and the one rule

Lesson 01 said that using namespace std; pours hundreds of names into your program, and that one of yours can collide with one of them. Here is the collision. Kenji counts the laps he has left in a global variable named left.

#include <iostream>

using namespace std;

int left = 3;

int main()
{
    cout << left << " laps left\n";
    return 0;
}

GCC 12 refuses it at the Playground's command line and at -Wall -Wextra alike: error: reference to 'left' is ambiguous. The notes name the two candidates, Kenji's 'int left' and 'std::ios_base& std::left(ios_base&)'. std::left is a real name from <iostream>, a setting that lines output up on the left. Kenji never asked for it; the using-directive let it out, and now there are two global lefts.

Move the variable inside main, and the same program compiles and prints 3 laps left. A name declared inside a function hides the ones outside it, the box's included. So the clash bites names at the top of a file, which is where contest programs keep their big arrays and counters.

That is the cost in a single file. In a header, a file that other files include, the cost spreads. #include pastes the header's text into the file that includes it, as in C. So a using-directive inside a header lands in every one of those files. Their authors never wrote it, and their names start colliding.

So this track has one rule, and one habit. The rule: using namespace std; never goes in a header. The habit: a short one-file contest program may use it, but this module, and every project lesson in the track, writes std:: on every standard name.

The header table: which file brings which name

A namespace says what a name is called. A header says where it is declared, and you must #include it before the name exists in your program. Every name in this track comes from one of the headers below. The table is worth keeping open beside your first STL programs.

Two rows surprise people. std::priority_queue has no header of its own; it lives in <queue>. And std::swap is in <utility>, while its neighbours std::max and std::min are in <algorithm>. So when GCC says a name is not a member of 'std', look its header up here first.

Include exactly what you use

Here is a fact found while writing lesson 05. This program has no <algorithm>, and GCC 12 compiles it anyway.

#include <iostream>

int main()
{
    std::cout << std::max(3, 7) << '\n';
    return 0;
}

7

It works by luck. GCC's library, libstdc++, builds <iostream> out of other headers. A few files down that chain it includes <string>, and <string> includes bits/stl_algobase.h, the file where std::max is defined. Compiler Explorer's include list (GCC's -H option) shows every step of it.

Other compilers come with other libraries, built in other ways. On Compiler Explorer we compiled three one-header programs, each including only <iostream>, on three toolchains.

The GCC column is the Playground's command line, -O2 -std=c++17. The clang column is clang 15 with -stdlib=libc++, its own library, and the MSVC column is "x64 msvc v19.latest" with /std:c++17. Each library drags in a different set of extras, and none of them promises to keep doing it. So a program that leans on an extra is right on one machine and broken on the next.

The fix costs one line per header. Include every header whose names you use, even when the program compiles without it. Then it compiles on any standard library, today and after the next library update. So the safe answer is never "it compiled on mine", but "every name I use has its header at the top".

bits/stdc++.h: every header at once, on GCC only

<bits/stdc++.h> is a file inside GCC's library that includes every standard header in one go. Its own comment calls it "an implementation file for a precompiled header", a helper for GCC's build speed. It is not part of the C++ standard. Contest programmers love it, because one line replaces a dozen, and the Playground and many contest judges compile with GCC.

#include <bits/stdc++.h>

int main()
{
    std::cout << "hello\n";
    return 0;
}

hello

That is GCC 12's output. Other toolchains do not have the file at all. On Compiler Explorer, clang 15 with libc++, the library a Mac uses by default, stops at line 1: fatal error: 'bits/stdc++.h' file not found. MSVC stops there too: fatal error C1083: Cannot open include file: 'bits/stdc++.h': No such file or directory. That is Bob and Maria's story from the top of this lesson.

It also costs compile time, because the compiler reads every header, used or not. We built the hello program twice, once with <iostream> and once with <bits/stdc++.h>, one run each.

On both machines the one line made a five-line program build at least three times slower. Three later runs on Compiler Explorer gave 289 to 378 ms against 1,863 to 2,888 ms. The local runs came after one warm-up build of each, so the disk was not the difference. In a contest that is a cost you can afford; in a project with hundreds of files, every file pays it.

So the track's rule is simple. <bits/stdc++.h> is allowed in a contest program, and we name it as GCC-only every time it appears. It never appears in a project lesson, because a project must build on every compiler its team uses.

#include <iostream>

namespace bookshop {
int stock = 0;
}

namespace library {
int stock = 0;
}

int main()
{
    bookshop::stock = 12;
    library::stock = 340;
    bookshop::stock = bookshop::stock - 2;

    std::cout << "bookshop " << bookshop::stock << ", library " << library::stock << '\n';
    return 0;
}

bookshop 10, library 340

#include <algorithm>
#include <iostream>

namespace shop {
// Prices go cheapest first.
void sort(int prices[], int n)
{
    std::sort(prices, prices + n);
}
}

namespace school {
// Marks go highest first.
void sort(int marks[], int n)
{
    std::sort(marks, marks + n);
    std::reverse(marks, marks + n);
}
}

void print(const int a[], int n)
{
    for (int i = 0; i < n; i++) {
        if (i > 0) {
            std::cout << ' ';
        }
        std::cout << a[i];
    }
    std::cout << '\n';
}

int main()
{
    int prices[4] = {300, 120, 450, 200};
    int marks[4] = {72, 91, 65, 85};

    shop::sort(prices, 4);
    school::sort(marks, 4);
    print(prices, 4);
    print(marks, 4);
    return 0;
}

120 200 300 450
91 85 72 65

#include <algorithm>
#include <iostream>
#include <numeric>
#include <string>

const int MAX_N = 100;

int main()
{
    std::string shop;
    int n = 0;
    std::cin >> shop >> n;
    if (n == 0) {
        std::cout << shop << ": no items\n";
        return 0;
    }

    int prices[MAX_N] = {0};
    for (int i = 0; i < n; i++) {
        std::cin >> prices[i];
    }

    std::sort(prices, prices + n);
    long long total = std::accumulate(prices, prices + n, 0LL);

    std::cout << shop << ": " << n << " items, total " << total << '\n';
    std::cout << "cheapest " << prices[0] << ", dearest " << prices[n - 1] << '\n';
    return 0;
}

Bookworm: 4 items, total 1070
cheapest 120, dearest 450

cout << "hello\n";

std:cout << "hello\n";

#include <iostream>

int main()
{
    std::vector<int> v(3);
    return 0;
}

namespace shop {
void sort()
{
}
}

sort();

#include <algorithm>
#include <iostream>

using namespace std;

int count = 0;

int main()
{
    int marks[100] = {0};
    int x = 0;
    while (count < 100 && cin >> x) {
        marks[count] = x;
        count++;
    }
    sort(marks, marks + count);
    cout << count << " marks, lowest " << marks[0] << '\n';
    return 0;
}

#include <iostream>
// Add the other headers this program uses here, one per line,
// in alphabetical order. Not <bits/stdc++.h>.

const int MAX_N = 100;

int main()
{
    int n = 0;
    std::cin >> n;

    // Read n words into an array of std::string, sort it with
    // std::sort, and print the words one per line.

    return 0;
}

#include <algorithm>
#include <iostream>

namespace weather {
// Return whichever of a and b is further from zero; on a tie, return a.
int max(int a, int b)
{
    return a; // replace this line
}
}

int main()
{
    int a = 0;
    int b = 0;
    std::cin >> a >> b;

    // Print "std::max " and std::max(a, b) on one line,
    // then "weather::max " and weather::max(a, b) on the next.

    return 0;
}

That is the last lesson of this module. Next comes its problem set, ten judged problems that use lessons 01 to 07, and after it Module 2 opens std::vector.