TITLE: std namespaces and inclusion

(Newsgroups: comp.lang.c++.moderated, 15 Oct 96)

PROBLEM: Thaddeus L. Olczyk

>> I've noticed that in some references to C++ header files, the .h is
>> missing eg <strstream> instead of <strstream.h>. Is this part of the
>> standard? When was this adopted?

RESPONSE: "Alf P. Steinbach" <alfps@online.no>

>I'm using Microsoft VC++ 4.0, which does not comply with the draft
>standard (bool, specialization of virtual function pointer result,
>throw-specifications for member functions, and much more missing).
>But as far as I understand the draft standard, file "bongo", without
>suffix "h", defines everything as part of namespace "std", and file
>"bongo.h" includes "bongo" and just says "uses namespace std" so
>you don't have to qualify the names of everything (except in case
>of name clashes, where qualification with "std::" should be handy).


RESPONSE: clamage@taumet.Eng (Steve Clamage)

That isn't quite right. I'll cover briefly what the draft standard
says, but you have to bear in mind that few existing compilers
fully implement these rules yet. For one things, the rules have
undergone some adjustment.

The entire standard C++ library is in namespace "std", including what
we would think of as the standard C library. Clearly, it would not
be desirable if previously valid programs like
	#include <stdio.h>
	int main() { printf("Hello, world!\n"); return 0; }
wouldn't compile under the new rules. Consequently, the headers inherited
from standard C place their identifiers in the global namespace as well
as in the std namespace. For example, a C++ version of the stdio header
might look in part like this:
	namespace std {
	    int printf(const char*, ... );
	}
	using std::printf;
The canonical C program above will now compile and run correctly as C++.

What if you are writing new C++ programs and want to take advantage of
the entire standard library being in its own namespace? If you wrote
	#include <stdio.h>
you would get all the stdio names in the global namespace as well.
Consequently all the headers inherited from standard C of the form
<name.h> have an additional form <cname>. That is, the ".h" is dropped,
and a prefix "c" is added. The <cname> form is the same as the <name.h>
form, except that none of the names are put in the global namespace.
The "hello world" program would not compile if you used <cstdio> instead
of <stdio.h>, but could be make to work if you qualify the printf:
	#include <cstdio>
	int main() { std::printf("Hello, world!\n"); return 0; }

The standard headers in C have always been spelled with a ".h" suffix,
but that was not the case for C++ headers. Early C++ implementations used
a variety of suffixes on text files, and used the same suffixes in the
spellings of the headers in include directives. The C++ Committee
addressed that problem in 1991, and concluded that the fairest solution
was to omit the suffix in the spelling of the standard C++ headers.
Thus, you would write
	#include <iostream>
	#include <new>
and so on. The spelling of the header name need have no particular
relationship to the name of any text file residing on disk, in C or
in C++. The implementation can do anything it likes when it sees
"#include <stdio.h>" or "#include <iostream>", as long as the result
is to declare and define what the standard specifies.

A C++ implementation in becoming standard-conforming could choose to
retain the names of its header text files on disk. It could also choose
to continue to allow "#include <iostream.h>" or "include <iostream.hxx>",
or whatever its previous convention was. The only requirement is that
"#include <iostream>" be accepted, and result in the iostream names
being declared and defined in the std namespace and not in the global
namespace.

What about the cannonical first C++ program:
	#include <iostream.h>
	int main() { cout << "Hello, world!\n"; return 0; }
First of all, that wouldn't compile on all C++ systems, since some would
have required <iostream.hxx> or some other spelling for the header. We
never had complete portability, and a purpose of the standard is to provide 
portability. You never could rely on the above program compiling, but the
standard does tell you what must compile on all conforming implementations.

There are several ways to write the above program to conform to the
standard. Here are two ways:
	#include <iostream>
	using namespace std;
	int main() { cout << "Hello, world!\n"; return 0; }

	#include <iostream>
	int main() { std::cout << "Hello, world!\n"; return 0; }

An implementation that used to use the spelling <iostream.h> could
choose to continue to accept that spelling, and that version of the
header could put all the iostream names in the global namespace as
well as in the std namespace. (The standard makes no comment about the
spelling <iostream.h>, so an implementation can do anything it wants.)
If the original C++ "hello world" program used to work, it would then
still work. (But of course on a given system, the ".h" spelling might
never have worked.)

At one time we had a provision in the draft requiring ".h" forms of
the C++ headers to do what I outlined in the paragraph above. That
provision created as many problems as it solved, so it was removed.
It is up to implementors to choose extensions to adopt (or not), so as
to allow whatever backward compatibility their customers want.

One final comment: It is a common misconception that an implementation
might choose to create <iostream.h> like this:
	#include <iostream>
	using namespace std;
That would be a bad idea. It would put ALL std names from ALL included
headers in the global namespace. Although a programmer might choose to
put such a using-directive in a program, a system header should
not do so. A better implemenation of <iostream.h> would have a
using-declaration for each name in <iostream> instead:
	#include <iostream>
	using std::istream;
	using std::ostream;
	using std::cin;
	using std::cout;
	... etc