CODEWITHSUNDEEP
c++namespaces
danijar
danijar

Reputation: 34285

Should I #include in my library's namespace?

I have a library that lives in its own namespace. Every file is wrapped by this namespace. When I use the standard library, should I include it into the global namespace or the one of my library? Moreover, what about library intern includes. Should they go inside or outside the namespace?

#include <vector> // This allows reuse

namespace library {
    #include <vector> // This would not leak anything
    #include "cart.h"
    using namespace std;

    class Train {
        vector<cart> carts;
    };
}

Including into the global namespace would make sense when the user needs vectors, too, so that the compiler doesn't need to integrate two versions of the standard library. On the other hand, including into the library's namespace makes sure that nothing leaks outside.

Upvotes: 0

Views: 835

Answers (1)

Jonathan Leffler
Jonathan Leffler

Reputation: 755094

Applied 'common sense' suggests that you can't reliably include C++ standard headers inside your own namespace. The standard library code is meant to be in the std namespace, not the library::std namespace. If there are any non-templated functions, the system library will provide std::non_templated_function and not library::std::non_templated_function, so your code won't link. If everything is a template, you may get away with it, but it is (unnecessarily) risky at best so don't do it.

Further (as noted by T.C. in a comment), the C++11 standard (ISO/IEC 14882:2011) standard explicitly says in §17.6.2.2 Headers [using.headers]:

¶3 A translation unit shall include a header only outside of any external declaration or definition, and shall include the header lexically before the first reference in that translation unit to any of the entities declared in that header.

This refers to a header from the C++ standard library, of course; it makes no such proscription for your own headers.

In theory, your library's internal headers could be included inside your library namespace if you want (but they shouldn't be — see below):

namespace library {
    #include "library/internal-header.h"
    …other declarations or definitions…
}

However (as Matt McNabb noted in a comment), doing so would mean that the internal header could not include any new standard headers, and yet it is quite plausible that an internal header would need to use some (extra) standard headers.

You might care to think about including them inside your own internal sub-namespace (for example, library::internal). If your internal headers do not contain their own namespace library { … } block, ensure you always include them inside the scope of your namespace library { … } brackets in the headers that include them, but note that the internal headers are no longer completely standalone.

Alternatively, and much more reliably, your library's internal headers could should be made standalone, with their contents defined inside your library namespace (since namespaces are extensible).

#include "library/internal-header.h"
namespace library {
    …other declarations or definitions…
}

where "library/internal-header.h" would contain:

namespace library {
    namespace internal {
        …internal declarations or definitions…
    }
}

where the namespace internal { and matching } are optional — and you might want a using namespace library::internal; directive as well.

Either mechanism could be made to work. On the whole, though, standalone headers are much the better (I agree with πάντα ῥεῖ and his comment and Matt McNabb).

Upvotes: 2

Related Questions