Skip to content
Tutorials Center
My learning

Topics

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.

C++
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

C++ ADL finds functions next to the type

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.

C++ The swap idiom and hidden friends

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 use std::ranges::swap, begin, end and 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) and std::forward<T>(x) qualified to stop an unrelated move from being picked up.
  • using namespace in a header pulls all names into every includer's lookup; prefer targeted using declarations inside functions.
  • Operators found by ADL: a + b is looked up as both member a.operator+(b) and free operator+(a, b), using ADL for the free form.