std::format_kind(3)

💅 NAME

std::format_kind — bestie, this is literally std::format_kind, from the C++ Standard Library ✨ (yes that's the manual name, we're fancy here)

---

✨ Synopsis

Okay so first things first: it lives in the header <format> 🎀

Here's overload (1), since C++23:

template< class R >
inline constexpr /* unspecified */ format_kind = /* unspecified */;

And overload (2), also since C++23:

template< ranges::input_range R >
    requires std::same_as<R, std::remove_cvref_t<R>>
inline constexpr range_format format_kind<R> = /* see description */;

The variable template format_kind picks out an appropriate std::range_format for a range R 🦋 Like, it's the vibe-checker that tells the formatter "okay is this a map, a set, a sequence, or a big nope?"

🌸 So how is std::format_kind<R> actually defined?

Bestie, it goes exactly like this, no cap:

• If std::same_as<std::remove_cvref_t<ranges::range_reference_t<R>>, R> is true, then std::format_kind<R> is std::range_format::disabled 🙈 (yes, it's giving "I contain myself", we don't format that)
• Otherwise, if R::key_type is valid and denotes a type:
  • If R::mapped_type is valid and denotes a type, let U be std::remove_cvref_t<ranges::range_reference_t<R>>. If either U is a specialization of std::pair or U is a specialization of std::tuple and std::tuple_size_v<U> == 2, then std::format_kind<R> is std::range_format::map 🗺️
  • Otherwise, std::format_kind<R> is std::range_format::set 🍓
• Otherwise, std::format_kind<R> is std::range_format::sequence 🌈

⚠️ Heads up: a program that instantiates a primary template of the format_kind variable template is ill-formed. Like, don't do it. It's not a cute look. 💀

Given a cv-unqualified program-defined type T that models input_range, a program can specialize format_kind for T. Such specializations are usable in constant expressions, and have type const std::range_format 👑

---

🛠️ Possible implementation

Here's how the girlies at cppreference imagine it, verbatim, go off 💅

namespace detail {
    template< typename >
    inline constexpr bool is_pair_or_tuple_2 = false;

    template< typename T, typename U >
    inline constexpr bool is_pair_or_tuple_2<std::pair<T, U>> = true;

    template< typename... Ts >
    inline constexpr bool is_pair_or_tuple_2<std::tuple<Ts...>> =
sizeof...(Ts) == 2;

    template < typename T >
        requires std::is_reference_v<T> || std::is_const_v<T>
    inline constexpr bool is_pair_or_tuple_2<T> =
        is_pair_or_tuple_2<std::remove_cvref_t<T>>; }

template< class R > inline constexpr range_format format_kind = [] {
    static_assert(false, "instantiating a primary template is not
allowed");
    return range_format::disabled; }();

template< ranges::input_range R >
    requires std::same_as<R, std::remove_cvref_t<R>> inline constexpr
range_format format_kind<R> = [] {
    if constexpr
(std::same_as<std::remove_cvref_t<std::ranges::range_reference_t<R>>,
R>)
        return range_format::disabled;
    else if constexpr (requires { typename R::key_type; })
    {
        if constexpr (requires { typename R::mapped_type; } &&
                      detail::is_pair_or_tuple_2<std::ranges::range_reference_t<R>>)
            return range_format::map;
        else
            return range_format::set;
    }
    else
        return range_format::sequence; }();

---

🌟 Example

(the "Run this code" moment, but make it iconic) 🫶

#include <filesystem>
#include <format>
#include <map>
#include <set>
#include <vector>

struct A {};

static_assert(std::format_kind<std::vector<int>> == std::range_format::sequence);
static_assert(std::format_kind<std::map<int>> == std::range_format::map);
static_assert(std::format_kind<std::set<int>> == std::range_format::set);
static_assert(std::format_kind<std::filesystem::path> == std::range_format::disabled);
// ill-formed:
// static_assert(std::format_kind<A> == std::range_format::disabled);

int main() {}

See that std::filesystem::path one? disabled — it ate and left no crumbs, we are NOT formatting that path as a range 😭 And the commented-out A line is commented out for a reason, bestie: ill-formed energy. 🔥

---

👀 See also

• range_format — specifies how a range should be formatted (C++23) (enum) 🧚

---

Okay that's the whole page, mwah 💖 — source/version and date, for the record: http://cppreference.com, 2024.06.10, std::format_kind(3). Slay, go format something. Periodt. 🎀✨