# Name Lookup, Qualified Lookup, and ADL

> Trace how the compiler maps an identifier to candidate declarations across unqualified lookup, qualified lookup, Argument-Dependent Lookup, and two-phase template lookup.

- **Source:** C++ Atlas (https://cppatlas.com/topics/name-lookup-and-adl)
- **Track:** Program structure
- **Estimated reading time:** 9 minutes
- **ISO C++ clauses:** [basic.lookup.unqual] (https://eel.is/c++draft/basic.lookup.unqual), [basic.lookup.qual] (https://eel.is/c++draft/basic.lookup.qual), [basic.lookup.argdep] (https://eel.is/c++draft/basic.lookup.argdep), [namespace.udir] (https://eel.is/c++draft/namespace.udir), [temp.res] (https://eel.is/c++draft/temp.res)
- **cppreference links:** [Name lookup](https://en.cppreference.com/w/cpp/language/lookup), [Unqualified name lookup](https://en.cppreference.com/w/cpp/language/unqualified_lookup), [Qualified name lookup](https://en.cppreference.com/w/cpp/language/qualified_lookup), [Argument-dependent lookup](https://en.cppreference.com/w/cpp/language/adl), [Using-declaration](https://en.cppreference.com/w/cpp/language/using_declaration), [Dependent names](https://en.cppreference.com/w/cpp/language/dependent_name), [Friend declaration](https://en.cppreference.com/w/cpp/language/friend)
- **Prerequisites:** translation-units-and-linkage

When the compiler sees an expression like `process(x)` or `ns::find(y)`, it does not jump straight to matching parameter types or checking `private` access. It runs a strict multi-stage pipeline where **name lookup** executes first, completely blind to argument types (except during Argument-Dependent Lookup) and access specifiers.

## Lookup precedes overload resolution and access checking

Every function call passes through four sequential stages:

1. **Name lookup** collects candidate declarations from scopes determined by syntax.
2. **Template argument deduction** synthesizes specializations for any function templates found.
3. **Overload resolution** ranks the viable candidates by argument conversion sequences.
4. **Access control** verifies that the chosen declaration is `public` or accessible via friendship.

Because lookup finishes before overload resolution begins, an inner scope declaration **hides** outer declarations of the same name regardless of signature. Likewise, because access checking happens *last*, a `private` overload with a better parameter match wins overload resolution and then triggers an access error rather than falling back to a worse `public` overload.

> **Mental model.** Name lookup builds the candidate menu by name alone; overload resolution picks the best dish from that menu; access control checks whether you are allowed to order it.

## Unqualified lookup and name hiding

**Unqualified name lookup** (`[basic.lookup.unqual]`) searches outward from the point of use through enclosing block, class (including base classes), and namespace scopes—stopping at the **first** scope that contains at least one declaration of that name. Once a declaration is found, outer scopes are never examined, even if parameter types do not match.

This hiding rule catches programmers off guard in derived classes. Declaring `void log(int)` in `Derived` hides every `log` overload in `Base`—including `void log(const std::string&)`—unless `using Base::log;` pulls the base overload set into `Derived` scope.

```cpp
#include <string>

struct Base {
    void log(double) {}
};

struct Derived : Base {
    using Base::log; // Without this, Base::log(double) is hidden by Derived::log(int)
    void log(int) {}
};

void run_lookup() {
    Derived d;
    d.log(3.5); // Resolves to Base::log(double) thanks to using-declaration
    d.log(42);  // Resolves to Derived::log(int)
}
```

Unqualified lookup interacts subtly with `using` declarations versus `using namespace` directives. A `using ns::foo;` declaration introduces `foo` as a synonym in the *current* declarative region—so it participates in overloading, hides outer declarations, and is visible to qualified lookup. By contrast, a `using namespace ns;` directive (`[namespace.udir]`) instructs unqualified lookup to search `ns` as if its members were declared in the nearest common enclosing namespace of the directive and `ns`. It does not inject names into the current scope itself.

| Mechanism | Scope where name appears | Participates in qualified lookup? | Can cause ambiguity with local name? |
| --- | --- | --- | --- |
| Unqualified declaration | Current block, class, or namespace | Yes, via enclosing qualifier | Redefinition or overload |
| `using ns::name;` | Current declarative region | Yes (`Current::name`) | Yes, conflicts with identical signature |
| `using namespace ns;` | Nearest common enclosing namespace | Never (`Current::name` ignores it) | Only if unqualified lookup reaches both |

## Qualified name lookup and using-declarations

When a name follows `::`, `.`, or `->`, the compiler performs **qualified name lookup** (`[basic.lookup.qual]`). Qualified lookup searches strictly inside the named class (and its base classes) or namespace (and any `inline namespace` members plus transitive `using namespace` directives inside that namespace—ignoring directives in the caller's scope).

Crucially, **qualified lookup disables Argument-Dependent Lookup**. Writing `std::swap(a, b)` forces lookup inside `namespace std` alone and refuses to consider a custom `swap` defined alongside user types. Also worth noting is the **injected-class-name**: inside any class `Widget` (or template `Box<T>`), the bare name `Widget` (or `Box`) is injected into the class scope itself, which is why `Widget::Widget` names the constructor and `Box` inside `Box<T>` denotes `Box<T>`.

## Argument-Dependent Lookup and hidden friends

Why does `std::cout << "hello"` compile without writing `std::operator<<(std::cout, "hello")`? Because of **Argument-Dependent Lookup (ADL)** (`[basic.lookup.argdep]`), also called Koenig lookup. When an unqualified function call uses a bare function name (not parenthesized and not qualified with `::`), the compiler augments ordinary unqualified lookup by searching the **associated namespaces and classes** of every argument's type.

> **Standardese.** Under `[basic.lookup.argdep]`, ADL is bypassed completely if ordinary unqualified lookup finds a class member declaration, a block-scope function declaration (that is not a using-declaration), or any declaration that is neither a function nor a function template.

Each argument type contributes associated namespaces and classes according to its structure:

- **Class types** contribute the class itself, its enclosing namespace (plus inline namespace parents), and all direct and indirect base classes along with their enclosing namespaces.
- **Class template specializations** contribute the same namespaces as a non-template class, plus the associated namespaces of template type arguments (so `std::vector<geom::Vec>` brings in both `std` and `geom`).
- **Fundamental types** (`int`, `double`, pointers to them) contribute **zero** associated namespaces.

One of the cleanest idioms in modern C++—**hidden friends**—relies entirely on ADL. A `friend` function defined *inline inside a class body* is a member of the enclosing namespace, yet is **invisible** to ordinary qualified or unqualified lookup (`geom::operator+` fails). It can *only* be found by ADL when an argument of that class type appears in the call. Hidden friends keep namespace overload sets tiny, improve compile times, and prevent unintended implicit conversions when unrelated types are passed.

```cpp
#include <utility>

namespace geom {
struct Vec {
    int x, y;

    // Hidden friend: visible only via ADL when Vec is an argument.
    friend Vec operator+(Vec a, Vec b) {
        return {a.x + b.x, a.y + b.y};
    }
};

int norm_sq(Vec v) {
    return v.x * v.x + v.y * v.y;
}
} // namespace geom

template<class T>
void generic_swap(T& a, T& b) {
    using std::swap; // Fallback for types without custom swap
    swap(a, b);      // Unqualified call triggers ADL for T's namespace
}

int test_adl() {
    geom::Vec u{1, 2}, v{3, 4};
    geom::Vec sum = u + v; // Finds hidden friend operator+ via ADL
    // (norm_sq)(sum);     // Parentheses suppress ADL: ill-formed here
    generic_swap(u, v);
    return norm_sq(sum);   // Unqualified id triggers ADL into geom
}
```

> **Pitfall.** Parenthesizing a function name—`(func)(arg)`—turns the callee from an unqualified-id into a parenthesized expression, which **disables ADL** just like `ns::func(arg)`. Standard C++20 customization point objects (like `std::ranges::sort`, nicknamed *niebloids*) are function objects rather than function declarations, intentionally blocking ADL at call sites while internally performing controlled customization dispatch.

## Two-phase lookup in templates

Templates resolve names in two distinct phases (`[temp.res]`):

- **Phase 1 (template definition time):** All **non-dependent names** (names that do not depend on a template parameter) are resolved immediately using ordinary unqualified or qualified lookup in the template's definition context—**without** ADL.
- **Phase 2 (template instantiation time):** **Dependent names** (such as `f(t)` where `t` has dependent type `T`) are looked up in the template's definition context *and*, via ADL only, in the instantiation context.

This split explains why `Derived<T>` inheriting from dependent `Base<T>` cannot write bare `count` inside member functions: `count` is syntactically non-dependent, and in phase 1 the compiler refuses to look inside `Base<T>` because a future explicit specialization of `Base<int>` could omit or alter `count`. Writing `this->count` or `Base<T>::count` makes the lookup dependent, deferring resolution to phase 2.

> **Pitfall.** Defining an unqualified helper `void trace(int)` *after* a template definition does not make `trace(t)` find it during phase 2 when `T = int`. Phase 2 looks in the instantiation context **only via ADL**, and fundamental types like `int` have no associated namespaces.

```cpp
template<class T>
struct Store {
    int count = 1;
};

template<class T>
struct CachedStore : Store<T> {
    int read() const {
        // `return count;` would fail Phase 1 lookup (non-dependent name ignores Store<T>).
        return this->count; // Dependent member access defers lookup to Phase 2
    }
};
```

## What to remember

- The compiler always resolves **name lookup** before template deduction, overload resolution, and access control; inner names hide outer names regardless of signature, and `private` best matches still win overload resolution and fail access checks.
- **Qualified lookup** (`ns::f`, `obj.f`) and parenthesized callees (`(f)(x)`) disable ADL.
- **ADL** searches associated namespaces and classes of argument types unless ordinary lookup finds a class member, a block-scope function declaration, or a non-function.
- **Hidden friends** defined inline inside a class are reachable exclusively through ADL, preventing accidental overload pollution.
- **Two-phase lookup** resolves non-dependent names at template definition time and dependent names at instantiation time (via ADL for unqualified calls).

## Concept Map Outline

- **Name Lookup & ADL:** Maps identifiers to candidate declarations before template deduction, overload resolution, and access control run.
  - **Lookup Pipeline:** Runs strictly before deduction, overload ranking, and private/protected access checks.
    - **Name Hiding First:** Inner scopes stop lookup before parameter types are ever compared.
    - **Access Checking Last:** Overload resolution can select a private best match and then fail access control.
  - **Unqualified Lookup:** Searches outward through enclosing blocks, classes, and namespaces until the first match.
    - **using-declarations:** Brings base or namespace names into the current scope so overloads stay visible.
    - **using-directives:** Exposes namespace members from the nearest common enclosing namespace for unqualified calls.
  - **Qualified Lookup:** Inspects only the named class or namespace scope and disables ADL.
    - **Scope Qualifier :::** Confines search to the target namespace or class hierarchy while ignoring caller directives.
    - **Injected Class Name:** Places the class's own name inside its scope so templates and constructors resolve.
  - **Argument-Dependent Lookup:** Extends unqualified function calls into the associated namespaces and classes of arguments.
    - **Associated Namespaces:** Contributed by class types, bases, enclosing namespaces, and template arguments.
    - **Hidden Friends:** Inline friend definitions inside a class are callable solely via ADL.
    - **ADL Suppression:** Blocked by scope qualification, parentheses around callee, class members, or block declarations.
  - **Two-Phase Template Lookup:** Separates non-dependent lookup at template definition from dependent lookup at instantiation.
    - **Phase 1 (Definition):** Resolves non-dependent names early and ignores dependent base classes like Base<T>.
    - **Phase 2 (Instantiation):** Looks up dependent calls via ADL in instantiation context, missing fundamental types.

## Standardese Quiz Questions

### Question 1 [warmup] ([namespace.udecl], [basic.lookup.unqual])

What is the role of `using Base::log;` inside a derived class that defines `void log(int)` when `Base` defines `void log(double)`?

A. It marks Base::log as virtual so Derived can override it.
B. It prevents Derived::log(int) from hiding Base::log(double) during name lookup.
C. It enables Argument-Dependent Lookup across Base's namespace.
D. It suppresses access checking on private members of Base.

**Answer (B):** It prevents Derived::log(int) from hiding Base::log(double) during name lookup.

**Why:** Without `using Base::log;`, unqualified lookup finds `log` in `Derived` and stops before inspecting `Base`, hiding `Base::log(double)`. A using-declaration introduces the base overloads into `Derived` scope so overload resolution can choose among all of them.

### Question 2 [warmup] ([basic.lookup.argdep])

Which call disables Argument-Dependent Lookup when invoking a free function `process` on an object `v` of type `geom::Vec`?

A. process(v);
B. using geom::process; process(v);
C. (process)(v);
D. a + b; // where operator+ is a hidden friend

**Answer (C):** (process)(v);

**Why:** ADL only applies when the postfix expression of a function call is an unqualified-id. Wrapping `process` in parentheses `(process)(v)` or qualifying it (`geom::process(v)`) suppresses ADL.

### Question 3 [tricky] ([class.access], [over.match])

What happens when calling `w.emit(42)` on this class?

```cpp
struct Writer {
    void emit(double) {}
private:
    void emit(int) {}
};
void test(Writer& w) { w.emit(42); }
```

A. It calls public emit(double) because private overloads are hidden from callers.
B. It is ambiguous because both overloads accept 42.
C. It compiles with a warning and converts 42 to double.
D. It fails to compile with an access error because overload resolution selects private emit(int) before checking access.

**Answer (D):** It fails to compile with an access error because overload resolution selects private emit(int) before checking access.

**Why:** Name lookup collects all `emit` members regardless of access specifier, overload resolution selects `emit(int)` as an exact match over `emit(double)`, and access control runs last and rejects the call to private `emit(int)`.

### Question 4 [tricky] ([temp.dep], [temp.res])

Why does `return value;` inside `Derived<T>::get()` fail to compile when `Base<T>` defines `int value = 1;`?

```cpp
template<class T> struct Base { int value = 1; };
template<class T> struct Derived : Base<T> {
    int get() const { return value; }
};
```

A. Because `value` is a non-dependent name, Phase 1 lookup runs at template definition time and does not inspect dependent base class Base<T>.
B. Because data members of template bases are always private unless marked protected.
C. Because `const` member functions cannot access inherited non-const fields.
D. Because ADL only finds functions, not data members.

**Answer (A):** Because `value` is a non-dependent name, Phase 1 lookup runs at template definition time and does not inspect dependent base class Base<T>.

**Why:** Under two-phase name lookup ([temp.res]), non-dependent unqualified names inside a template are looked up during Phase 1 without inspecting dependent base classes like `Base<T>`, since an explicit specialization could redefine `Base<T>`. Writing `this->value` or `Base<T>::value` makes it dependent.

### Question 5 [standardese] ([basic.lookup.argdep])

Under [basic.lookup.argdep], which declaration found by ordinary unqualified lookup prevents ADL from running for `swap(a, b)`?

```cpp
namespace ns { struct Item {}; void swap(Item&, Item&); }
void run(ns::Item& a, ns::Item& b) {
    void swap(int&, int&);
    swap(a, b);
}
```

A. Only if `swap(int&, int&)` is a better match than `ns::swap`.
B. A block-scope function declaration that is not a using-declaration suppresses ADL completely, making `swap(a, b)` ill-formed.
C. A `using std::swap;` declaration inside `run` suppresses ADL just like a function declaration.
D. ADL still runs and finds `ns::swap` because `int&` cannot bind to `ns::Item`.

**Answer (B):** A block-scope function declaration that is not a using-declaration suppresses ADL completely, making `swap(a, b)` ill-formed.

**Why:** [basic.lookup.argdep] specifies that if ordinary unqualified lookup finds a block-scope function declaration (that is NOT a using-declaration), a class member, or a non-function, ADL is not performed. By contrast, `using std::swap;` is a using-declaration and intentionally allows ADL.

### Question 6 [standardese] ([basic.lookup.argdep])

Why does `std::vector<geom::Vec>` allow ADL on `f(vec)` to search `namespace geom` in addition to `namespace std`?

A. Because `std::vector` places a `using namespace geom;` directive inside `std`.
B. Because ADL always searches every namespace declared before the call site.
C. Because associated namespaces of a class template specialization include the associated namespaces of its template type arguments.
D. Because `geom::Vec` inherits from `std::vector` implicitly.

**Answer (C):** Because associated namespaces of a class template specialization include the associated namespaces of its template type arguments.

**Why:** Under [basic.lookup.argdep], the set of associated namespaces and classes of a class template specialization includes not only its own enclosing namespace and bases, but also the associated namespaces and classes of its template type arguments (and template template arguments).
