Argument-dependent lookup (ADL), also known as Koenig lookup^[1], is the set of rules for looking up the unqualified function names infunction-call expressions, including implicit function calls tooverloaded operators. These function names are looked up in the namespaces of their arguments in addition to the scopes and namespaces considered by the usualunqualified name lookup.

#include <iostream> int main(){std::cout<<"Test\n";// There is no operator<< in global namespace, but ADL// examines std namespace because the left argument is in// std and finds std::operator<<(std::ostream&, const char*)    operator<<(std::cout,"Test\n");// Same, using function call notation // However,std::cout<< endl;// Error: “endl” is not declared in this namespace.// This is not a function call to endl(), so ADL does not apply     endl(std::cout);// OK: this is a function call: ADL examines std namespace// because the argument of endl is in std, and finds std::endl (endl)(std::cout);// Error: “endl” is not declared in this namespace.// The sub-expression (endl) is not an unqualified-id}

[edit]Details

First, the argument-dependent lookup is not considered if the lookup set produced by usualunqualified lookup contains any of the following:

Otherwise, for every argument in a function call expression its type is examined to determine theassociated set of namespaces and classes that it will add to the lookup.

After the associated set of classes and namespaces is determined, all declarations found in classes of this set are discarded for the purpose of further ADL processing, except namespace-scoped friend functions and function templates, as stated in point 2 below.

The set of declarations found by ordinaryunqualified lookup and the set of declarations found in all elements of the associated set produced by ADL, are merged, with the following special rules:

[edit]Notes

Because of argument-dependent lookup, non-member functions and non-member operators defined in the same namespace as a class are considered part of the public interface of that class (if they are found through ADL)^[2].

ADL is the reason behind the established idiom for swapping two objects in generic code:usingstd::swap; swap(obj1, obj2); because callingstd::swap(obj1, obj2) directly would not consider the user-definedswap() functions that could be defined in the same namespace as the types ofobj1 orobj2, and just calling the unqualifiedswap(obj1, obj2) would call nothing if no user-defined overload was provided. In particular,std::iter_swap and all other standard library algorithms use this approach when dealing withSwappable types.

Name lookup rules make it impractical to declare operators in global or user-defined namespace that operate on types from thestd namespace, e.g. a customoperator>> oroperator+ forstd::vector or forstd::pair (unless the element types of the vector/pair are user-defined types, which would add their namespace to ADL). Such operators would not be looked up from template instantiations, such as the standard library algorithms. Seedependent names for further details.

ADL can find afriend function (typically, an overloaded operator) that is defined entirely within a class or class template, even if it was never declared at namespace level.

template<typename T>struct number{    number(int);friend number gcd(number x, number y){return0;};// Definition within// a class template}; // Unless a matching declaration is provided gcd is// an invisible (except through ADL) member of this namespacevoid g(){    number<double> a(3), b(4);    a= gcd(a, b);// Finds gcd because number<double> is an associated class,// making gcd visible in its namespace (global scope)//  b = gcd(3, 4); // Error; gcd is not visible}

namespace N1{struct S{}; template<int X>void f(S);} namespace N2{template<class T>void f(T t);} void g(N1::S s){    f<3>(s);// Syntax error until C++20 (unqualified lookup finds no f)    N1::f<3>(s);// OK, qualified lookup finds the template 'f'    N2::f<3>(s);// Error: N2::f does not take a constant parameter//        N1::f is not looked up because ADL only works//              with unqualified names using N2::f;    f<3>(s);// OK: Unqualified lookup now finds N2::f//     then ADL kicks in because this name is unqualified//     and finds N1::f}

In the following contexts ADL-only lookup (that is, lookup in associated namespaces only) takes place:

• thedependent name lookup from the point of template instantiation.

[edit]Examples

namespace A{struct X;struct Y; void f(int);void g(X);} namespace B{void f(int i){        f(i);// Calls B::f (endless recursion)} void g(A::X x){        g(x);// Error: ambiguous between B::g (ordinary lookup)//        and A::g (argument-dependent lookup)} void h(A::Y y){        h(y);// Calls B::h (endless recursion): ADL examines the A namespace// but finds no A::h, so only B::h from ordinary lookup is used}}

[edit]Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

[edit]See also

• Name lookup
• Template argument deduction
• Overload resolution

[edit]External links

• In other languages

• Español
• 日本語
• Русский
• 中文