C++ Reference ยท Types and Language Concepts
Name lookup and argument-dependent lookup (ADL)
Concept page on C++ name lookup: qualified and unqualified lookup, argument-dependent lookup, hidden friends, std::swap idiom and two-phase lookup.
When you write a name in C++, the compiler has to find which declaration it refers to. This is name lookup. A qualified name such as std::sort or Widget::size is looked up only in the named scope. An unqualified name such as sort(v) or a + b is looked up in the enclosing scopes, innermost first, and stops at the first scope that contains the name.
For unqualified function calls there is one extra step: argument-dependent lookup (ADL), also called Koenig lookup. The compiler also searches the namespaces associated with the types of the arguments. This is why std::cout << x finds operator<< and why swap(a, b) can find a swap written for your own type, without any using declaration.
namespace geo { struct Point { int x, y; }; void print(const Point&); } geo::Point p{1, 2}; print(p); // found by ADL in namespace geo
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
How lookup proceeds
Unqualified lookup
The name is searched in the current block, then each enclosing block, then the enclosing class (if any), then the enclosing namespaces up to the global scope. The first scope that has any declaration of that name ends the search. This is why a member function called print hides a free function print for calls inside the class: the free function is never considered unless you qualify it (::print(x)).
Qualified lookup
A::name searches only in A (and, for classes, its bases). A leading :: starts at the global namespace.
Argument-dependent lookup
For an unqualified call f(a, b), the compiler adds the associated namespaces of each argument's type:
- the namespace where the class is defined (and where its template arguments' classes live, for specializations like
std::vector<geo::Point>), - the namespaces of its base classes,
- for function pointer arguments, the namespaces of parameter and return types.
Functions found this way join the ordinary candidates and compete in overload resolution. ADL is not used if ordinary lookup finds a class member, a block-scope function declaration that is not a using declaration, or a non-function. Qualified calls (geo::mirror(p)) switch it off.
Two-phase lookup in templates
Inside a template, a name that does not depend on a template parameter is looked up when the template is defined. A name that depends on one (like swap(a, b) where a has type T) is looked up again at instantiation, using ADL only. This explains why a function declared after a template can still be called from it through ADL, but one found only by ordinary lookup must be declared before. In a derived template class, names from a dependent base need this->name or Base<T>::name.
Usage notes
- Customization points:
using std::swap; swap(a, b);is the classic two-step. C++20 ranges usestd::ranges::swap,begin,endand similar customization point objects that do this lookup for you. - Hidden friends (friend functions defined inside the class) are only found by ADL, which keeps operators from polluting namespaces and from taking part in overload sets of unrelated types.
- ADL surprises: adding an overload to a namespace can change which function an existing call picks. Avoid generic names (
process,get,swap) with unconstrained templates in namespaces that other code uses. - Qualify when you mean it: write
std::move(x)andstd::forward<T>(x)qualified to stop an unrelatedmovefrom being picked up. using namespacein a header pulls all names into every includer's lookup; prefer targetedusingdeclarations inside functions.- Operators found by ADL:
a + bis looked up as both membera.operator+(b)and freeoperator+(a, b), using ADL for the free form.