scope of using declaration within a namespace

Question

Is it safe (and correct) in a C++ header file to use the using declaration within a namespace as follows:

#include <boost/numeric/ublas/vector.hpp>
namespace MyNamespace {
    using boost::numeric::ublas::vector;
    vector MyFunc(vector in);
}

I.e. is the "using boost::numeric::ublas::vector" properly contained within the MyNamespace block, or will this pollute the namespace of any file that includes this header?

Answer 1

No, it is not safe - it won't pollute another namespace, but it is dangerous for other reasons:

A using directive will import anything that is currently visible by the name you specify into the namespace where you use it. While your using will only be visible to users of MyNamespace, other things from "outside" will be visible to your using declaration.

So how is this dangerous when used in a header? Because it will import things that are visible at the point of the declaration, the exact behavior will depend on the order of headers you include before the declaration (There might be different things visible from boost::numeric::ublas::vector). Since you cannot really control which headers are included before your header (nor should you be! headers should be self-sufficient!), this can lead to very strange problems where your function will find one thing in one compilation unit, and another in the next.

As a rule of thumb, using declarations should only be used after all includes in a .cpp file. There's also an item on this exact issue in the book "C++ Coding Standards" by Sutter and Alexandrescu (Item 59). Here's a quote: "But here's the common trap: Many people think that using declarations issued at namespace level (...) are safe. They are not. They are at least as dangerous, and in a subtler and more insidious way."

Even when it's unlikely that the name you are using doesn't exist anywhere else (as is probably the case here), things can get ugly: In a header, all declarations should be fully qualified. This is pain, but otherwise, strange things can happen.

Also see Migrating to Namespaces, Using-declarations and namespace aliases and Namespace Naming for examples and the problem described in-depth.

Answer 2

A using declaration is, as the name says, a declaration. All declarations are scoped to the enclosing block (7.2), in this case the namespace MyNamespace. It will not be visible outside that namespace.

Answer 3

It will not pollute any other namespaces, but it certainly will pollute the MyNamespace namespace.

Answer 4

It is safe, but it will pollute the MyNamespace namespace. So, any file that include that header will have functions/classes in the MyNamespace.

Answer 5

To summarize, no, using-declarations in a header are not ok, even within a namespace, for 2 reasons. Further, using-declarations within a namespace in a non-header are error-prone or pointless (see end). Using-declarations in a header are not ok because:

1. They introduce a name into the namespace, which affects all files that include the header.
2. They introduce only declarations for the name that have already been seen, which means that behavior depends on order of includes!

In your example, this means that:

1. Within MyNamespace, vector now may resolve to boost::numeric::ublas::vector, for any files that include this header: it "pollutes" the MyNamespace namespace.
2. Which boost::numeric::ublas::vector declarations are imported depends on what declarations appear before this using-declaration, which depends on the order of includes in the file that includes this header, and all of its includes (properly, the order of declarations in the translation unit, after preprocessing).

Per your comment of May 30 '11 at 11:51 you actually want behavior 1, but this doesn't work, due to problem 2. You can get the desired behavior by having a separate header that is included after all others (and fully qualifying the name in other headers). However, this is fragile and thus discouraged, preferably being reserved only when transitioning to namespaces:

//--- file myheader.hpp ---
#include <boost/numeric/ublas/vector.hpp>
namespace MyNamespace {
    ::boost::numeric::ublas::vector MyFunc(::boost::numeric::ublas::vector in);
}

//--- file myproject_last.hpp ---
namespace MyNamespace {
    using ::boost::numeric::ublas::vector;
}

//--- file myproject.cpp ---
#include "myheader.hpp"
// ...other includes
#include "myproject_last.hpp"

See GotW #53: Migrating to Namespaces for details, this workaround, and advice: "Namespace using declarations should never appear in header files."

It is possible to avoid problem 1 by adding an unnamed namespace around the using-declaration (to prevent those names from being visible) and then another one outside the unnamed namespace (to make the desired name itself visible), but that still suffers from problem 2 and uglifies the header:

//--- file myheader.hpp ---
#include <boost/numeric/ublas/vector.hpp>
namespace MyNamespace {
    namespace {
        using ::boost::numeric::ublas::vector;
        vector MyFunc(vector in);
    }
    using MyFunc; // MyNamespace::(unique)::MyFunc > MyNamespace::MyFunc
}

Due to these problems, you should only use using-declarations in non-header (.cc/.cpp) files: this doesn't affect other files, so problem 1 is avoided; and all headers have been included, so problem 2 is avoided. In this case it's a matter of taste whether you put them in a namespace or not, since they don't affect other files; it's safest to always use fully qualified names on in the using-declaration itself (absolute, starting with ::).

Simplest is to put all using-declarations at the top of the file, after the includes, but outside of any namespaces: this is safe, unambiguous, easy to read, and allows the names to be used throughout the file. Some common deviations:

1. Using-declaration within a function (or struct or class or nested block): fine. This minimizes scope and is just a matter of taste: using-declaration is close to use (legibility win), but they are now scattered throughout the file (legibility loss).

2. Using-declaration with a relative name within a (named) namespace: error-prone. This is more concise and adds some clarity (related names used in the namespace to which they relate), but is potentially ambiguous (just like includes with relative paths), and is safer to avoid:

   using ::foo::bar;
   namespace foo { ... }
   
   namespace foo {
       // Implicitly ::foo:bar, could be ::bar, or ::other::foo::bar.
       using bar;
   }
   

3. Using-declaration with an absolute name within a named namespace: pointless. This introduces the name only into the namespace, but you shouldn't care, since you shouldn't be including the .cc/.cpp file:

   namespace foo {
       using ::bar;
   }
   

4. Using-declaration within an unnamed namespace: pointless, slightly dangerous. For example, if you have a function in an unnamed namespace, say an implementation detail, then you can have a using-declaration for its return type or param types. This introduces the name into just that namespace (so can't be referenced from other files), but again, you shouldn't care, since you shouldn't be including the .cc/.cpp file (unnamed namespaces are especially for avoid name clashes at link time, which isn't applicable here: it's just a compile-time alias). Worse, it introduces ambiguity if that name already does exist!