Argument-dependent lookup - cppreference.com (original) (raw)

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

Argument-dependent lookup makes it possible to use operators defined in a different namespace. Example:

#include   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 usual unqualified lookup contains any of the following:

1. a declaration of a class member.

2. a declaration of a function at block scope (that's not a using declaration).

3. any declaration that is not a function or a function template (e.g. a function object or another variable whose name conflicts with the name of the function that's being looked up).

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

1. For arguments of fundamental type, the associated set of namespaces and classes is empty.

2. For arguments of class type (including union), the set consists of:

a) The class itself.

b) If the class is complete, all of its direct and indirect base classes.

d) The innermost enclosing namespaces of the classes added to the set.

1. For arguments whose type is a class template specialization, in addition to the class rules, the following associated classes and namespaces are added to the set.

a) The types of all template arguments provided for type template parameters (skipping constant template parameters and skipping template template parameters).

b) The namespaces in which any template template arguments are members.

c) The classes in which any template template arguments are members (if they happen to be class member templates).

1. For arguments of enumeration type, the innermost enclosing namespace of the declaration of the enumeration type is defined is added to the set. If the enumeration type is a member of a class, that class is added to the set.

2. For arguments of type pointer to T or pointer to an array of T, the type T is examined and its associated set of classes and namespaces is added to the set.

3. For arguments of function type, the function parameter types and the function return type are examined and their associated set of classes and namespaces are added to the set.

4. For arguments of type pointer to member function F of class X, the function parameter types, the function return type, and the class X are examined and their associated set of classes and namespaces are added to the set.

5. For arguments of type pointer to data member T of class X, the member type and the type X are both examined and their associated set of classes and namespaces are added to the set.

6. If the argument is the name or the address-of expression for a set of overloaded functions (or function templates), every function in the overload set is examined and its associated set of classes and namespaces is added to the set.

• Additionally, if the set of overloads is named by a template identifier, all of its type template arguments and template template arguments (but not constant template arguments) are examined and their associated set of classes and namespaces are added to the set.

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 ordinary unqualified lookup and the set of declarations found in all elements of the associated set produced by ADL, are merged, with the following special rules:

1. namespace-scoped friend functions (and function templates) that are declared in an associated class are visible through ADL even if they are not visible through ordinary lookup.

2. all names except for the functions and function templates are ignored (no collision with variables).

[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:using std::swap; swap(obj1, obj2); because calling std::swap(obj1, obj2) directly would not consider the user-defined swap() functions that could be defined in the same namespace as the types of obj1 or obj2, and just calling the unqualified swap(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 with Swappable types.

Name lookup rules make it impractical to declare operators in global or user-defined namespace that operate on types from the std namespace, e.g. a custom operator>> or operator+ for std::vector or for std::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. See dependent names for further details.

ADL can find a friend 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 struct number { number(int); friend number gcd(number x, number y) { return 0; }; // Definition within // a class template };   // Unless a matching declaration is provided gcd is // an invisible (except through ADL) member of this namespace void g() { number a(3), b(4); a = gcd(a, b); // Finds gcd because number is an associated class, // making gcd visible in its namespace (global scope) // b = gcd(3, 4); // Error; gcd is not visible }

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

• the dependent name lookup from the point of template instantiation.

[edit] Examples

Example from http://www.gotw.ca/gotw/030.htm

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

1. ↑ Andrew Koenig: "A Personal Note About Argument-Dependent Lookup"
2. ↑ H. Sutter (1998) "What's In a Class? - The Interface Principle" in C++ Report, 10(3)