# Specialization, overloading, and customization points

This chapter presents the decision rule for choosing concepts versus specialization, then shows the related mechanisms.
## Class template specialization

A class template defines a family of types parameterised by one or more template arguments. A **full specialization** provides a concrete definition for a *specific* set of arguments. A **partial specialization** fixes *some* arguments while leaving others as parameters.

```cpp
// Primary template: works for any type T
template <typename T>
struct Printer {
    static void print() { std::cout << "primary" << '\n'; }
};

// Partial specialization for pointer types
template <typename T>
struct Printer<T*> {
    static void print() { std::cout << "pointer" << '\n'; }
};
```

The primary template is selected when the argument list does not match any partial or full specialization. The partial specialization above matches any pointer type `T*`. The compiler chooses the *most specialised* viable definition.

```cpp
{{#include ../../examples/ch20/template_specialization.cpp}}
```
### How the compiler decides

* **Matching**: the argument list is compared against each specialization’s pattern.
* **Partial ordering**: if more than one specialization matches, the compiler ranks them by how many arguments are fixed. The one with the *greater* number of fixed arguments is preferred.
* **Full specialization**: a specialization that fixes *all* arguments is the ultimate match and overrides any partial specialization.

Because specializations are an *out‑of‑band* mechanism, they do not participate in overload resolution. They merely replace the primary definition before the compiler instantiates the class template.

A full specialization is written with an empty template parameter list and a concrete argument: `template<> struct Printer<int> { ... };`. It is the only form that can introduce a definition with a completely different set of members, because it no longer depends on any template parameter. Partial specializations must still match the primary template's parameter list in shape, so they can vary the pattern but not the member set arbitrarily. In practice most code needs at most one partial specialization and a handful of full ones.

One caution: the primary template must remain well formed even if only specializations are used, because the compiler instantiates the primary in some contexts before consulting specializations. Keep a sensible default body in the primary and treat specializations as refinements.
## The decision rule

When you need different behaviour, ask two questions:

1. **Do the types share the same logical interface?** If the answer is *yes* but the implementation varies based on a property (e.g., pointer vs non‑pointer), prefer **concepts** or **`if constexpr`** inside a generic implementation.
2. **Is the representation fundamentally different?** If the answer is *no* but the underlying storage or layout differs (e.g., a raw array versus a `std::span`), use **specialization**.

In short, *choice is semantic → use concepts*. *Representation changes → specialise*.

Applying the decision rule consistently avoids scattered overloads and specializations. When a concept describes a semantic property, the requirement appears directly in the function signature and the implementation stays in a single generic body. Use specialization only when the type’s layout or representation differs fundamentally, such as a raw array versus a `std::span`. This discipline simplifies refactoring and provides clearer compile‑time diagnostics.
## Variable templates

Variable templates let you define **compile‑time constants** that depend on a template parameter. They are the value‑side analogue of function templates.

```cpp
template <typename T>
constexpr T pi = static_cast<T>(3.1415926535897932385L);

static_assert(pi<double> == 3.1415926535897932385);
```

The standard library uses this pattern extensively, e.g. the `_v` suffix for trait variables such as `std::is_same_v<T, U>`.

```cpp
{{#include ../../examples/ch20/variable_template.cpp}}
```

Variable templates are instantiated only when ODR‑used, so they impose no runtime cost. They also serve as a natural place for configuration constants such as `std::numeric_limits<T>::max()`. They compose, e.g., `template<typename T> constexpr T half_pi = pi<T> / 2;`, allowing the compiler to fold arithmetic at translation time. Because they are `constexpr`, they can feed `static_assert`, `if constexpr` conditions, or non‑type template arguments, bridging value and type worlds. Variable templates also act as value‑side customization points. A library can declare `template<typename T> struct traits;` and specialize `traits<T>::value`, while a variable template like `template<typename T> inline constexpr bool is_trivially_copyable_v` provides the standard‑preferred concise spelling.
## `if constexpr` as in‑body dispatch

Sometimes a single function needs two completely different implementations, but you do not want to write separate overloads or specializations. `if constexpr` lets you branch at compile time based on a constant expression.

```cpp
template <typename T>
void show() {
    if constexpr (std::is_pointer_v<T>) {
        std::cout << "pointer" << '\n';
    } else {
        std::cout << "primary" << '\n';
    }
}

int main() { show<int*>(); show<int>(); }
```

The compiler discards the unreachable branch, so no ill‑formed code can appear in the omitted path. This technique is especially useful when the two paths require different headers or heavy SFINAE tricks.

```cpp
{{#include ../../examples/ch20/if_constexpr_dispatch.cpp}}
```

`if constexpr` replaces tag dispatch. The compiler discards the unreachable branch, so the same `show` function works for both pointer and non‑pointer arguments without any overload set.
## Specialising `std::formatter`

`std::format` formats arbitrary types using the **formatter** customization point. To make a user‑defined type printable, you specialise `std::formatter<T>` for your type `T`.

```cpp
struct Vec2 { int x, y; };

template <> struct std::formatter<Vec2> : std::formatter<std::string> {
    // parse format spec - we ignore it for simplicity
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
    // format the value
    auto format(const Vec2& v, format_context& ctx) const {
        return std::format_to(ctx.out(), "({},{})", v.x, v.y);
    }
};

int main() {
    Vec2 v{3,4};
    std::cout << std::format("Vec2: {}", v) << '\n';
}
```

The specialization lives in the same namespace as `std` (the only exception allowed by the standard). It enables the type to be used with `std::format`, `std::print`, and any other formatting facility that forwards to the `std::formatter` trait.

```cpp
{{#include ../../examples/ch20/formatter_specialization.cpp}}
```
### Why specialise instead of overloading?

Overloading `operator<<` works only for stream‑based APIs. `std::format` follows a *type‑centric* design: the formatter is a **customisation point object (CPO)** that the library calls. By providing a specialization, you integrate with the whole formatting ecosystem without pulling in iostreams.

The `parse` member decodes the part of the format string that follows the colon, and `format` writes the value. Inheriting from an existing formatter such as `std::formatter<std::string>` is a shortcut when you want default spec handling. For a type with no natural spec, `parse` just returns the begin iterator. The specialization must be visible in the namespace of the type or of `std`, which is why the standard permits specialising `std::formatter` for user types even though it otherwise forbids adding to `std`.
## Specialising `std::hash`

`std::unordered_map` and `std::unordered_set` hash their keys through `std::hash<Key>`. A user type has no default, so to use one as a key you specialise `std::hash`:

```cpp
struct Key { int id; std::string name; };

template <>
struct std::hash<Key> {
    std::size_t operator()(const Key& k) const noexcept {
        std::size_t h1 = std::hash<int>{}(k.id);
        std::size_t h2 = std::hash<std::string>{}(k.name);
        return h1 ^ (h2 << 1);
    }
};
```

The specialization must be a complete type with an `operator()` returning `std::size_t`. Combine the hashes of the members with a shift and XOR so the result depends on both fields. Equality must stay consistent with the hash: two keys that compare equal must hash equal, or the container misbehaves. The same pattern powers the customization that `std::unordered_map` relies on for every key type.

Because the hash and the equality operator must agree, define them together. If you change the equality later, update the hash in the same change or lookups return wrong results silently. The standard library also lets you supply a custom hasher or comparator as template arguments to `unordered_map`, so a bespoke type can avoid touching `std::hash` entirely when its needs are unusual.
## ADL and hidden friends

Argument-dependent lookup (ADL) finds functions in the namespaces of their arguments. When `a == b` is written, the compiler looks for `operator==` not only in the enclosing scope but also in the namespaces of `a` and `b`. A *hidden friend* is an `operator==` defined inside the class body. It is reachable only through ADL, so it never pollutes the global namespace and cannot be called without the right argument types.

```cpp
struct Point {
    int x, y;
    friend bool operator==(const Point& a, const Point& b) = default;
};
```

Because the friend is defined inline, it is a hidden friend and ADL is the only mechanism that finds it. This keeps the operator close to the type, prevents accidental calls on unrelated types, and gives the best diagnostics: a call with a mismatched operand names `Point` rather than surfacing an unrelated overload. The same reasoning applies to any operator used only with its own operand types.


To summarize, the library can combine concepts, specializations, variable templates, and customization point objects to provide a clear, layered customization strategy that keeps generic code simple and concrete overrides focused.
## Try this

Create a small `struct Color { uint8_t r,g,b }` and write a `std::formatter<Color>` that formats the colour as a hex string `#RRGGBB`. Verify the output with `std::format`.