Share via

C++ Library Conventions

  • Article

C++ Library Conventions

The Standard C++ library obeys much the same conventions as the Standard C library, plus a few more outlined here.

Except for macro names, which obey no scoping rules, all names in the Standard C++ library are declared in the std namespace. Including a Standard C++ header does not introduce any library names into the current namespace. You must, for example, refer to the standard input stream cin as std::cin, even after including the header <iostream> that declares it. Alternatively, you can incorporate all members of the std namespace into the current namespace by writing:

using namespace std;

immediately after all include directives that name the standard headers. Note that the Standard C headers behave mostly as if they include no namespace declarations. If you include, for example, <cstdlib>, you call std::abort() to cause abnormal termination, but if you include <stdlib.h>, you call abort().

An implementation has certain latitude in how it declares types and functions in the Standard C++ library:

  • Names of functions in the Standard C library may have either extern "C++" or extern "C" linkage. Include the appropriate Standard C header rather than declare a library entity inline.
  • A member function name in a library class may have additional function signatures beyond those listed in this document. You can be sure that a function call described here behaves as expected, but you cannot reliably take the address of a library member function. (The type may not be what you expect.)
  • A library class may have undocumented (nonvirtual) base classes. A class documented as derived from another class may, in fact, be derived from that class through other undocumented classes.
  • A type defined as a synonym for some integer type may be the same as one of several different integer types.
  • A library function that has no exception specification can throw an arbitrary exception, unless its definition clearly restricts such a possibility.

On the other hand, there are some restrictions you can count on:

  • The Standard C library uses no masking macros. Only specific function signatures are reserved, not the names of the functions themselves.
  • A library function name outside a class will not have additional, undocumented function signatures. You can reliably take its address.
  • Base classes and member functions described as virtual are assuredly virtual, while those described as nonvirtual are assuredly nonvirtual.
  • Two types defined by the Standard C++ library are always different unless this document explicitly suggests otherwise.
  • Functions supplied by the library, including the default versions of replaceable functions, can throw at most those exceptions listed in any exception specification. (Functions in the Standard C library may propagate an exception, as when qsort calls a comparison function that throws an exception, but they do not otherwise throw exceptions.)