Mick235711's Personal Website

Coroutine-Based Scope Guards

Fri, 23 May 2025 00:00:00 GMT

The Python standard library provides a lot of convenience things, among which one is contextlib.contextmanager, a decorator that allows turning any coroutine generator into a resource:

from contextlib import contextmanager

@contextmanager
def open_file(filename, mode="r"):
    fp = open(filename, mode)
    try:
        yield fp
    finally:
        fp.close()

with open_file("test.txt") as fp:
    fp.write("Hello World!")

Anything before yield will be treated as __enter__, and anything after yield will be treated as __exit__, and with the help of finally we implemented an always-called cleanup block regardless of the exit method (normally or by exception).

In C++, we have RAII, which we can use to implement a scope guard:

template<typename F>
struct scope_guard
{
    F f;
    scope_guard(F f) :f{f} {}
    ~scope_guard() { f(); }
};

{
    auto fp = fopen("test.txt", "r");
    scope_guard _ = [fp] { fclose(fp); };
    // ... use fp ...
}

However, this requires a separation between entry and exit block, which seems less than ideal. In the Python example, the initialization and cleanup phases are nicely grouped together. Let's see if we can do the same thing in C++.

Bare Bones

Let's have an awaitable type that implements the Coroutine framework:

template<class Resource>
class context
{
public:
    class promise_type;

    context(const context&) = delete;
    context(context&& other) noexcept
        : coroutine_{std::exchange(other.coroutine_, {})}
    {}
    context& operator=(this context& self, context other) noexcept
    {
        std::ranges::swap(self.coroutine_, other.coroutine_);
        return self;
    }

    ~context()
    {
        if (coroutine_ && !coroutine_.done()) coroutine_.resume();
    }

private:
    std::coroutine_handle<promise_type> coroutine_ = nullptr;

    explicit context(std::coroutine_handle<promise_type> coro)
        : coroutine_{coro}
    {}
};

Normal stuff, a move-only type that holds a coroutine handle to the promise type.

[!NOTE] The destructor need to resume the coroutine, since we want the cleanup code to run on destruction of the context object.

Now entering the promise type, which contains a pointer to the managed resource, and embedding a noop final awaiter:

template<class Resource>
class context<Resource>::promise_type
{
public:
    friend class context;

    context get_return_object(this promise_type& self) noexcept
    {
        return context{std::coroutine_handle<promise_type>::from_promise(self)};
    }

    static std::suspend_never initial_suspend() noexcept { return {}; }
    static std::suspend_never final_suspend() noexcept { return {}; }

    std::suspend_always yield_value(this promise_type& self, const Resource& val) noexcept
    {
        self.value_ = std::addressof(val);
        return {};
    }

    void await_transform() = delete;

    static void return_void() noexcept {}
    static void unhandled_exception() { throw; }

private:
    const Resource* value_ = nullptr;
};

Notice that initial_suspend returns suspend_never, since we want the initialization code to run immediately after the construction of the context object. Finally, some convenience method that access the stored value from the context:

const Resource& operator*(this const context& self)
{
    return *self.coroutine_.promise().value_;
}
const Resource& get(this const context& self) { return *self; }
const Resource* operator->(this const context& self) { return &*self; }

With that, we have a working context manager:

// NOTE: pass-by-value to avoid coroutine dangling the reference
context<FILE*> open_file(std::string file_name)
{
    auto fp = fopen(file_name.c_str(), "r");
    std::println("Opened file: {}", file_name);
    co_yield fp;
    fclose(fp);
    std::println("Closed file: {}", file_name);
}

void use()
{
    std::println("Entering block");
    {
        auto context = open_file("/tmp/test.txt");
        auto fp = *context;
        std::println("Get file fd: {}", fileno(fp));
    }
    std::println("Exiting block");
}

Calling use() outputs:

Entering block
Opened file: /tmp/test.txt
Get file fd: 3
Closed file: /tmp/test.txt
Exiting block

Great! We now have a way to bundle the initialization and cleanup code neatly in a function together.

Recursive Awaitable

The get()/operator* is still a pain to write; can we do better with co_awaiting the context?

On face value, it may seem impossible, since we essentially need to reverse what co_await usually do. Usually, we use co_await to await the finish of some async operations in the inner function; but here, we want to execute the inner function first, and then await for the outer function to finish, and finally run the rest of the inner function. It is like doing a co_await from the inner function to the outside.

Fortunately, C++20 Coroutines provides enough customization point to implement this reverse behavior. However, it is just factually impossible to execute the cleanup code at the end of the current block, as there is nothing to RAII on (the result of co_await expression will be the resource itself for convenience). Thus, we need to execute the cleanup code (rest of the inner function) at the final suspension point of the outer function.

Let's start by writing an awaiter:

awaiter context::operator co_await(this context&& self) noexcept
{
    self.resume_ = false;
    return awaiter{self.coroutine_};
}

template<class Resource>
class context<Resource>::awaiter
{
public:
    friend class context;

    static bool await_ready() noexcept { return true; }
    static void await_suspend(std::coroutine_handle<>) noexcept {}
    const Resource& await_resume(this awaiter& self) noexcept
    {
        return *self.coroutine_.promise().value_;
    }

private:
    std::coroutine_handle<promise_type> coroutine_ = nullptr;

    explicit awaiter(std::coroutine_handle<promise_type> coro)
        : coroutine_{coro}
    {}
};

Nothing fancy here, just a normal awaiter storing the inner coroutine handle, and await_resume() returns the stored value inside the inner coroutine handle's promise type. This value will then be used as the result of the co_await expression, eliminating the need for operator*/get(). We don't need to do anything during suspension, so just let await_ready() return true to skip the suspension phase is ideal.

To use co_await, we still need an outer task type, which need to coordinate with the awaiter to store the inner coroutine handle:

class context_task
{
public:
    class promise_type
    {
    private:
        struct final_awaiter
        {
            static bool await_ready() noexcept { return false; }
            template <class Promise>
            static std::coroutine_handle<> await_suspend(std::coroutine_handle<Promise> coro) noexcept
            {
                // Symmetric transfer into the stored inner coroutine
                auto cont = coro.promise().continuation_;
                if (cont) return cont;
                return std::noop_coroutine();
            }
            static void await_resume() noexcept {}
        };

    public:
        context_task get_return_object(this promise_type& self) noexcept
        {
            return context_task{std::coroutine_handle<promise_type>::from_promise(self)};
        }
        static std::suspend_never initial_suspend() noexcept { return {}; }
        static final_awaiter final_suspend() noexcept { return {}; }
        static void return_void() noexcept {}
        static void unhandled_exception() { throw; }

        template<typename Resource>
        context<Resource>&& await_transform(this promise_type& self, context<Resource>&& ctx) noexcept
        {
            self.continuation_ = ctx.coroutine_;
            return std::move(ctx);
        }

    private:
        std::coroutine_handle<> continuation_ = nullptr;
    };

    context_task(const context_task&) = delete;
    context_task(context_task&& other) noexcept
        : coroutine_{std::exchange(other.coroutine_, {})}
    {}
    context_task& operator=(this context_task& self, context_task other) noexcept
    {
        std::ranges::swap(self.coroutine_, other.coroutine_);
        return self;
    }

    ~context_task()
    {
        if (coroutine_) coroutine_.destroy();
    }

private:
    std::coroutine_handle<promise_type> coroutine_ = nullptr;

    explicit context_task(std::coroutine_handle<promise_type> coro)
        : coroutine_{coro}
    {}
};

Several things are notable for this outer task type. Apart from the normal move operation, destructor, and coroutine handle business that we see in every coroutine types, we also wrote a custom final_awaiter to execute cleanup at the final suspension point, whose await_suspend method will utilize symmetric transfer to cheaply transfer to the inner coroutine to execute the cleanup code. This inner coroutine's handle is stored during the await_transform call inside the operator co_await machinery.

With this new task type, we can use the context manager without needing to get() anything:

my::context_task use2()
{
    std::println("Entering block 2");
    {
        auto fp = co_await open_file("/tmp/test.txt");
        std::println("Get file fd: {}", fileno(fp));
    }
    std::println("Exiting block 2");
}

/*
Output:
Entering block 2
Opened file: /tmp/test.txt
Get file fd: 3
Exiting block 2
Closed file: /tmp/test.txt
*/

Here, fp is already our stored resource type, neat! (Notice that the file is only closed after use2() finishes, not at the end of the fp scope; but this is acceptable for most usages.)

Error Handling

Of course, the above bare bones implementation ignores a lot of errors that might occur:

What will happen if the initialization code throws an exception or co_returns early?
What will happen if the cleanup code throws an exception?
What will happen if the code co_yields zero times or more than one times?

Premature Return

Our current code does not handle premature return at all; calling co_return without doing any yielding will instantly crash the code.

Exception Handling

When exception occurs in the initialization part, it is fine; throw; inside the uncaught_exception() function will propagate that exception to the caller, who can handle it normally. The interesting case is when the cleanup portion throws an exception:

For the normal RAII case, exception is throw in context's destructor (because that's where the inner coroutine is resumed), which will normally results in std::terminate. To fix this you need to add noexcept(false) to the destructor, and then you can handle the exception as if it is thrown at the end of the resource block.
For the recursive await case, you can just handle the exception as if it is thrown at the closing brace of the outer function. This does mean that you need to handle it at the caller of the outer function.

Multiple Yields

Our current code also does not handle multiple co_yields; everything after the second co_yield will be ignored as the coroutine handle will be destroyed after the second suspension (which is treated as final suspension, regardless of whether it really is final suspension).

Handling of premature return and multiple yields is thus left as an exercise to the readers.

Performance

Well, there is no escape. This is C++, we care about performance. (If you don't, shouldn't you be down the road where there is a language that have this functionality built-in?)

Let's put up Quick Bench and see the results: <img src="/upload/coroutine-scope-guard/quick-bench.png" alt="Quick Bench Results">

Well... not good. This is tested under Clang 17 + libstdc++ (-O3). Given that Clang optimize coroutines much better than GCC does, I'd say this is the best result we can get.

As perhaps expected, recursive await is a ~50% slowdown compared to normal RAII, and the latter is 23x slower than a simple scope guard. Well, you wouldn't use scope guards in a critical hot loop, anyway, right? Maybe it is fine, maybe not. This is just intended as a toy experiment, nothing more.

Fun With Deducing This, SMFs and = delete

Tue, 07 Jan 2025 00:00:00 GMT

Deducing This is a new way of writing C++ member functions, which was introduced in C++23. This feature allows you to explicitly write the normally-implicit object argument (aka this) in the argument list, just like Python's self argument:

struct S
{
    int value;
    void fun(int r) { value = r; } // normal member
    void fun2(this const S& self, int r) { self.value = r; } // deducing this
};

S s;
s.fun(4);
s.fun2(5); // usage is the same

As you can see, the syntax for DT is to prepend this on the first argument, which will be treated as the object argument that appears before . or ->. This is essentially a weakened form of Uniform Function-Call Syntax (UFCS), since DT essentially allows specifically-marked static non-member functions (as implemented behind the scenes) to be called with the member syntax.

However, this post's purpose is not to explore the detail of Deducing This. Instead, it tries to answer a seemingly obvious question: can we write special member functions (SMFs) with Deducing This? If so, can they be = defaulted? This simple question have surprisingly non-trivial answers and incites several compiler bugs and inconsistent behavior across the board!

Terminology

Before we explore the interaction between Deducing This and SMFs, we must first clarify an often misunderstood term: what counts as special member functions?

Special Member Functions

Traditionally, special member functions refer to the functions that will be automatically declared by the compiler for a class, including:

Default constructors
Copy constructors
Move constructors
Copy assignment operators
Move assignment operators
Prospective destructors

[!TIP] The reason that all the constructors and operators are in plural form, and destructors is prepended by "prospective", is because of C++20 Concepts. With requires clauses, you can have several "prospective" destructors for a class, but only one will be available at any given time to act as the "real" destructor.

These (except the default constructors) are also the functions affected by "Rule of Five", which describes the customs and idioms related to defining those functions for a class (refer to the linked page for more information).

Special Member Functions is a term defined by the standard, so the definition of them seems to be crystal clear, right?

Not so fast! What is the exact signature required for a constructor to be considered a SMF? (For example, is the copy-and-swap assignment operator X& operator=(X) considered copy assignment or move assignment?) What about default arguments? What about templates? Nothing is that simple in C++!

Let's look at each special member function in detail.

Default Constructors and Destructors

This is the easiest case. A constructor is a default constructor if and only if:

Each parameter that is not a pack have a default argument.

That's it! (Standard) What this means essentially is that as long as the constructor can be called with no arguments (A()), it is a default constructor.

struct A
{
    A(); // default constructor
    A(int x = 2, int y = 3); // also a default constructor
    template<typename T = int> A(T x = 2); // also a default constructor
    template<typename... Ts> A(Ts... args); // also a default constructor
    template<typename... Ts> A(); // also a default constructor

    A(int a, int b = 2); // not a default constructor
    template<typename T> A(); // also not
};

[!NOTE] The access specifier, noexcept, explicit, requires, or constexpr/consteval specifier will not affect whether a constructor is a SMF, same below.

Of course, the implicitly generated default constructor (will be generated if no constructor is declared) always have the form:

A() = default;

(the constexpr and noexcept-ness will be deduced by the member/base's default constructors; same below)

A destructor for the class is a member declared with the ~A() syntax (with optional preceding specifier and noexcept/requires). It cannot be declared in any other form, so this is the only requirement. If no destructor and move operations is defined for a class, one will be implicitly generated with the form:

~A() = default;

Copy/Move Constructors

Copy/Move constructors are called when an object is constructed by copying/moving another object. The standard specified that a constructor for class A will be identified as a copy/move constructor if and only if:

It is not a template.
Its first parameter is [cv] A& (for copy) / [cv] A&& (for move).
All non-first parameters have default arguments.

[!NOTE] [cv] refers to any combinations of const and volatile, same below.

Again, this essentially means that the compiler will treat a constructor as SMF based on its callability with one argument, instead of its declared number of arguments.

struct A
{
    A(const A&); // copy constructor
    A(A&); // also (used by auto_ptr<T> to indicate stole semantics)
    A(const volatile A&, int x = 2); // also

    A(A&&); // move constructor
    A(const A&&) // also (although very weird)
    A(volatile A&&, double x = 2.0); // also

    template<typename T = int>
    A(const A&); // not a copy constructor
    A(A&&, int x); // not a move constructor
};

If no copy constructor is defined for a class, a copy constructor will be implicitly generated with the form

A(const A&) = default; // normal
A(A&) = default; // only if a subobject (member or base) have a copy constructor with argument [volatile] A&

If no copy/move operations and destructors are defined for a class, a move constructor will be implicitly generated with the form

A(A&&) = default;

[!NOTE] A critical difference here is the criteria of implicit generation. If a move operation is declared, the copy constructor will still be generated; it will just be declared as = delete. However, if a copy/move operation or a destructor is declared, the move constructor will not be generated at all, falling silently back to copying.

Copy/Move Assignment

[!TIP] Note that operator= can only be declared as a member function, so we don't need to deal with operator overload form shenanigans here.

Copy/Move assignment are called when an object is assigned by lvalue/rvalue of the same type. The standard specified that a declared operator= member function for class A will be identified as a copy/move assignment if and only if:

It is not a template.
Its first non-object parameter is A or [cv] A& (for copy) / [cv] A&& (for move).

[!NOTE] Operator overloads, except for operator() and operator[], cannot have default arguments, so that item does not apply here.

struct A
{
    A& operator=(const A&); // copy assignment
    A& operator=(A&); // also (used by auto_ptr<T> to indicate stole semantics)
    int operator=(const volatile A&) const &; // also

    A& operator=(A&&) &; // move assignment
    double operator=(const A&&) const &&; // also (although very weird)

    template<typename T = int>
    A& operator=(const A&); // not a copy assignment
};

[!TIP] Return types, const, volatile, and ref-qualifiers also does not affect the validity of a copy/move assignment operator.

If no copy assignment operator is defined for a class, a copy assignment operator will be implicitly generated with the form

A& operator=(const A&) = default; // normal
A& operator=(A&) = default; // only if a subobject (member or base) have a copy assignment operator with non-object argument [volatile] A&

If no copy/move operations and destructors are defined for a class, a move assignment operator will be implicitly generated with the form

A& operator=(A&&) = default;

`= default`

Compared to SMFs which was a thing since the inception of C++, = default is a relatively "new" (with 14 years of age already!) thing. Essentially, it requests the compiler to "do as if this thing had been implicitly generated". You can explicitly request the default function body by using = default as the function body:

struct A {}; // SMFs implicitly generated
struct B
{
    B() = default; // implemented as-if it is implicitly generated
    B& operator=(B&&) & = default; // implemented as-if it is implicitly generated
};

Besides the textual benefit of writing out implicit functions explicitly, = default also allows you to make small modifications to the implicit signatures of SMFs, as demonstrated by the use of ref-qualifiers above. However, the possible modifications are restricted by the standard explicitly. Only the following difference are permitted for = default functions compared to the implicitly generated signatures:

They may have different noexcept specifications.
For non-constructors, ref-qualifiers can be different.
If the implicit signature have a non-object parameter of type const A&, the explicit signature can have a non-object parameter of type A&.
The explicit signature can be written in Deducing This, provided that the type of the object parameter (the first one, prepended by this) must also be a reference to A.

struct A
{
    A() noexcept = default; // fine, Rule 1
    A& operator=(const A&) noexcept & = default; // fine, Rule 1 + Rule 2
    A(A&) = default; // fine, Rule 3
    int operator=(const A&) = default; // error, not a permitted difference
    A(int x = 2) = default; // error, not a permitted difference
};

In this sense, functions that can be = defaulted can be said to be a more strictly restricted version of SMF signatures that are valid... or can they?

Actually, these two sets are disjoint! Besides SMFs, there are other functions that can be = defaulted: comparison operators.

The full story for comparison is too long to be described in this post, but interested readers can consult here for a detailed description. For this post, it is sufficient to note that

A defaulted <=> or = (primary comparisons) means memberwise application of the operator.
A defaulted other operator (secondary comparisons) means rewriting into one of primary comparison operators. For example, a < b will default to rewriting into (a <=> b) < 0.

The criteria for a defaulted comparison operator, regardless of which operator is being declared, is as follows:

It is not a template.
It is either a non-static member function or a friend (non-member) function.
Must have two (incl. explicit/implicit object parameter) parameters (this is restricted by the operator overload syntax) of the same type. The type must be A or const A&.
Must return bool if the operator is not <=>. If declaring <=>, the return type must either be auto (exactly), a comparison category type, or a type that is convertible from all the <=> result of subobjects.

struct A
{
    int x;
    bool operator==(const A&) const = default; // fine, const A& + const A&
    bool operator<(const A&) = default; // error, first argument (implicit) is A&
    friend bool operator>(A, A) = default; // fine

    auto operator<=>(const A&) const = default; // fine
    friend std::any operator<=>(A, A) = default; // fine
    int operator<=>(const A&) const = default; // error, return type of x <=> x not convertible to int
};

[!CAUTION] The fact that operators other than <=> cannot use auto in lieu of bool or auto& in lieu of A& is inconsistent, and there is a proposal to fix that, so this behavior is likely to change in a future standard.

Deducing This

Now onto the main part of this post: what does all of this have to do with Deducing This? Of course, since it is a new (or dare I say better?) way of writing member functions, we should use it to write special member functions!

What Does The Standard Say?

Surprisingly little at first! The author of DT seems to not consider the interaction with SMFs and comparison functions at all in the initial proposal, and thus the C++23 standard initially does not have any regulations regarding whether SMFs and comparison operators's validity when written in DT form.

This omission was later identified, and resolved by the adoption of CWG 2586. Two key modification are made as a result of this issue:

The last rule regarding Deducing This is added to the = default criteria above; and
The "two parameters" in the comparison operator rule is clarified to mean two parameters including the explicit/implicit object parameter. In other words, bool operator==(const C&) const and bool operator==(this const C&, const C&) both have two parameters of type const C&.

However, standard is just a document, what does the implementations say about the matter?

Implementation Divergence

Let's see! (All results are obtained from the trunk versions of compilers as of January 2025)

[!NOTE] Since DT cannot be used on constructors or destructors, the only valid forms are on copy/move assignment operators and comparison operators.

<thead> <tr> <td class="legend">Form</td> <td class="line">Standard</td> <td class="line">GCC</td> <td class="line">Clang</td> <td class="line">MSVC</td> <td class="line">EDG</td> <td class="line">Link</td> <td class="line">Comments</td> </tr> </thead>

<tbody> <tr> <td></td> <td class="semititle line" colspan="7">Copy Assignment</td> </tr>

<tr> <td class="legend"><code>A& operator=(this A&, const A&);</code></td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="no tooltip">❌Welp, it seems that MSVC does not implement CWG 2586 at all...</td> <td class="yes">✅</td> <td class="line"><a href="https://godbolt.org/z/o51EserWq">Godbolt</a></td> <td class="line">Normal Copy Assignment</td> </tr>

<tr> <td class="legend"><code>A& operator=(this A&, A&);</code></td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="no tooltip">❌Same as above, erroneously generate an implicit copy assignment operator and do resolution based on that</td> <td class="yes">✅</td> <td class="line"><a href="https://godbolt.org/z/hEh8z8GnE">Godbolt</a></td> <td class="line">Stealing Copy Assignment</td> </tr>

<tr> <td class="legend"><code>A& operator=(this A&, A);</code></td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="no tooltip">❌Same as above, ambiguous between the implicitly generated one and CAS</td> <td class="yes">✅</td> <td class="line"><a href="https://godbolt.org/z/ra1r4jY9b">Godbolt</a></td> <td class="line">CAS Copy Assignment</td> </tr>

<tr> <td class="legend"><code>A& operator=(this const A&, const A&);</code></td> <td class="yes tooltip" style="z-index: 1000;">✅There is a note in CWG 2586 that pointed out that it is weird for this to be considered a copy assignment; however as of now it is the status quo in the standard.</td> <td class="no tooltip">❌Silently calls the implicitly generated one</td> <td class="yes">✅</td> <td class="no tooltip">❌Silently calls the implicitly generated one</td> <td class="mixed">?</td> <td class="line"><a href="https://godbolt.org/z/WhYGooPE3">Godbolt</a></td> <td class="line">Copy Assignment With <code>const A&</code> Object Param</td> </tr>

<tr> <td class="legend"><code>A& operator=(this A, const A&);</code></td> <td class="yes">✅</td> <td class="no tooltip">❌Ambiguous with the implicitly generated one</td> <td class="yes">✅</td> <td class="no tooltip">❌Ambiguous with the implicitly generated one</td> <td class="mixed">?</td> <td class="line"><a href="https://godbolt.org/z/1bTbzdsPs">Godbolt</a></td> <td class="line">Copy Assignment With <code>A</code> Object Param</td> </tr>

<tr> <td class="legend"><code>A& operator=(this int, const A&);</code></td> <td class="yes">✅</td> <td class="no tooltip">❌Silently calls the implicitly generated one</td> <td class="yes">✅</td> <td class="no tooltip">❌Silently calls the implicitly generated one</td> <td class="no tooltip">❌Somehow generated an invalid redeclaration error</td> <td class="line"><a href="https://godbolt.org/z/Mz7TeaGrx">Godbolt</a></td> <td class="line">Copy Assignment With Unrelated Object Param</td> </tr>

<tr> <td class="legend"><code>A& operator=(this auto&&, const A&);</code></td> <td class="yes tooltip">❌Must not be a template</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="line"><a href="https://godbolt.org/z/9881PM6T8">Godbolt</a></td> <td class="line">Copy Assignment With Templated Object Param</td> </tr>

<tr> <td class="legend"><code>A& operator=(this A&, const A&) = default;</code></td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="no tooltip">❌Currently it seems that MSVC just rejects defaulting functions with DT</td> <td class="no tooltip">❌EDG complains about signature only</td> <td class="line"><a href="https://godbolt.org/z/aEvKhMejY">Godbolt</a></td> <td class="line" rowspan="7">Above With <code>= default</code></td> </tr>

<tr> <td class="legend"><code>A& operator=(this A&, A&) = default;</code></td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="no">❌</td> <td class="no">❌</td> <td class="line"><a href="https://godbolt.org/z/hjxMMzn8s">Godbolt</a></td> </tr>

<tr> <td class="legend"><code>A& operator=(this A&, A) = default;</code></td> <td class="yes tooltip" style="z-index: 1002;">❌Not an allowed signature for defaulting</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="no tooltip">❌Reject only because it cannot handle defaulting DT at all</td> <td class="yes">❌</td> <td class="line"><a href="https://godbolt.org/z/bY635q4cx">Godbolt</a></td> </tr>

<tr> <td class="legend"><code>A& operator=(this const A&, const A&) = default;</code></td> <td class="yes tooltip" style="z-index: 1001;">✅The last rule for defaulting above specifies that any kind of reference to A is acceptable</td> <td class="no tooltip">❌Ill-formed</td> <td class="no tooltip">❌Default as deleted</td> <td class="no tooltip">❌Ill-formed</td> <td class="no tooltip">❌Ill-formed</td> <td class="line"><a href="https://godbolt.org/z/8anavTsze">Godbolt</a></td> </tr>

<tr> <td class="legend"><code>A& operator=(this A, const A&) = default;</code></td> <td class="yes tooltip" style="z-index: 1000;">❌Not a reference to A, which <a href="https://eel.is/c++draft/dcl.fct.def.default#2.5">should</a> be default as deleted</td> <td class="almost tooltip">❌Ill-formed</td> <td class="yes tooltip">❌Default as deleted</td> <td class="almost tooltip">❌Ill-formed</td> <td class="almost tooltip">❌Ill-formed</td> <td class="line"><a href="https://godbolt.org/z/frrT8vhqj">Godbolt</a></td> </tr>

<tr> <td class="legend"><code>A& operator=(this int, const A&) = default;</code></td> <td class="yes">❌</td> <td class="almost tooltip">❌Ill-formed</td> <td class="yes tooltip">❌Default as deleted</td> <td class="almost tooltip">❌Ill-formed</td> <td class="almost tooltip">❌Ill-formed</td> <td class="line"><a href="https://godbolt.org/z/WMKrW91ch">Godbolt</a></td> </tr>

<tr> <td class="legend"><code>A& operator=(this auto&&, const A&) = default;</code></td> <td class="yes tooltip">❌Must not be a template</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="line"><a href="https://godbolt.org/z/EK9175Yv8">Godbolt</a></td> </tr>

<tr> <td></td> <td class="semititle line" colspan="7">Move Assignment</td> </tr>

<tr> <td class="legend"><code>A& operator=(this A&, A&&);</code></td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="no tooltip">❌Erroneously generate an implicit move assignment operator and do resolution based on that</td> <td class="yes">✅</td> <td class="line"><a href="https://godbolt.org/z/89TojWb7f">Godbolt</a></td> <td class="line">Normal Move Assignment</td> </tr>

<tr> <td class="legend"><code>A& operator=(this A&, const A&&);</code></td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="no">❌</td> <td class="yes">✅</td> <td class="line"><a href="https://godbolt.org/z/qh9G38xET">Godbolt</a></td> <td class="line">Weird Move Assignment</td> </tr>

<tr> <td class="legend"><code>A& operator=(this const A&, A&&);</code></td> <td class="yes tooltip" style="z-index: 1000;">✅There is a note in CWG 2586 that pointed out that it is weird for this to be considered a move assignment; however as of now it is the status quo in the standard.</td> <td class="no tooltip">❌Silently calls the implicitly generated one</td> <td class="no tooltip">❌Ambiguous with the implicitly generated one</td> <td class="no tooltip">❌Silently calls the implicitly generated one</td> <td class="yes">✅</td> <td class="line"><a href="https://godbolt.org/z/z71hfK9WT">Godbolt</a></td> <td class="line">Move Assignment With <code>const A&</code> Object Param</td> </tr>

<tr> <td class="legend"><code>A& operator=(this A&&, A&&);</code></td> <td class="yes">✅</td> <td class="no tooltip">❌Ambiguous with the implicitly generated one</td> <td class="yes">✅</td> <td class="no tooltip">❌Ambiguous with the implicitly generated one</td> <td class="yes">✅</td> <td class="line"><a href="https://godbolt.org/z/a31jsj7WG">Godbolt</a></td> <td class="line">Move Assignment With <code>A&&</code> Object Param</td> </tr>

<tr> <td class="legend"><code>A& operator=(this int, const A&);</code></td> <td class="yes">✅</td> <td class="no tooltip">❌Silently calls the implicitly generated one</td> <td class="no tooltip">❌Conflicts with copy assignment</td> <td class="no tooltip">❌Silently calls the implicitly generated one</td> <td class="no tooltip">❌Conflicts with copy assignment</td> <td class="line"><a href="https://godbolt.org/z/vz3vfP9rY">Godbolt</a></td> <td class="line">Move Assignment With Unrelated Object Param</td> </tr>

<tr> <td class="legend"><code>A& operator=(this auto&&, A&&);</code></td> <td class="yes tooltip">❌Must not be a template</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="line"><a href="https://godbolt.org/z/eon5f8x9v">Godbolt</a></td> <td class="line">Move Assignment With Templated Object Param</td> </tr>

<tr> <td class="legend"><code>A& operator=(this A&, A&&) = default;</code></td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="no tooltip">❌Currently it seems that MSVC just rejects defaulting functions with DT</td> <td class="no tooltip">❌EDG complains about signature only</td> <td class="line"><a href="https://godbolt.org/z/fa13cqanz">Godbolt</a></td> <td class="line" rowspan="6">Above With <code>= default</code></td> </tr>

<tr> <td class="legend"><code>A& operator=(this A&, const A&&) = default;</code></td> <td class="yes tooltip" style="z-index: 1002;">❌Not a permitted deviation; only stripping const is allowed; <a href="https://eel.is/c++draft/dcl.fct.def.default#2.5">should</a> be default as deleted</td> <td class="yes tooltip">❌Default as deleted</td> <td class="yes tooltip">❌Default as deleted</td> <td class="almost tooltip">❌Ill-formed</td> <td class="almost tooltip">❌Ill-formed</td> <td class="line"><a href="https://godbolt.org/z/nPqnha7Pd">Godbolt</a></td> </tr>

<tr> <td class="legend"><code>A& operator=(this const A&, A&&) = default;</code></td> <td class="yes tooltip" style="z-index: 1001;">✅The last rule for defaulting above specifies that any kind of reference to A is acceptable</td> <td class="no tooltip">❌Ill-formed</td> <td class="no tooltip">❌Default as deleted</td> <td class="no tooltip">❌Ill-formed</td> <td class="no tooltip">❌Ill-formed</td> <td class="line"><a href="https://godbolt.org/z/rfxqPPa9n">Godbolt</a></td> </tr>

<tr> <td class="legend"><code>A& operator=(this A&&, A&&) = default;</code></td> <td class="yes">✅</td> <td class="almost tooltip">❌Ill-formed</td> <td class="yes tooltip">❌Default as deleted</td> <td class="almost tooltip">❌Ill-formed</td> <td class="almost tooltip">❌Ill-formed</td> <td class="line"><a href="https://godbolt.org/z/zv9hKeb57">Godbolt</a></td> </tr>

<tr> <td class="legend"><code>A& operator=(this int, A&&) = default;</code></td> <td class="yes">❌</td> <td class="almost tooltip">❌Ill-formed</td> <td class="yes tooltip">❌Default as deleted</td> <td class="almost tooltip">❌Ill-formed</td> <td class="almost tooltip">❌Ill-formed</td> <td class="line"><a href="https://godbolt.org/z/cja4WcsWY">Godbolt</a></td> </tr>

<tr> <td class="legend"><code>A& operator=(this auto&&, A&&) = default;</code></td> <td class="yes tooltip">❌Must not be a template</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="line"><a href="https://godbolt.org/z/K49T9nK4q">Godbolt</a></td> </tr>

<tr> <td></td> <td class="semititle line" colspan="7">Comparison</td> </tr>

<tr> <td class="legend"><code>auto operator<=>(this A, A) = default;</code></td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="no tooltip">❌Refuse to recognize this as a comparison</td> <td class="no tooltip">❌Refuse to default comparison written in DT</td> <td class="line"><a href="https://godbolt.org/z/z45hcEMY7">Godbolt</a></td> <td class="line">Normal Spaceship With <code>A</code></td> </tr>

<tr> <td class="legend"><code>auto operator<=>(this const A&, const A&) = default;</code></td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="yes">✅</td> <td class="no">❌</td> <td class="no">❌</td> <td class="line"><a href="https://godbolt.org/z/Mnfr1zW7f">Godbolt</a></td> <td class="line">Normal Spaceship With <code>const A&</code></td> </tr>

<tr> <td class="legend"><code>auto operator<=>(this const A&, A) = default;</code></td> <td class="yes tooltip">❌Two parameter must be of same type</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="no">❌</td> <td class="no">❌</td> <td class="line"><a href="https://godbolt.org/z/he97vfb71">Godbolt</a></td> <td class="line">Asymmetric Spaceship</td> </tr>

<tr> <td class="legend"><code>auto operator<=>(this A&, A&) = default;</code></td> <td class="yes tooltip">❌Two parameter must be of either A or const A&</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="no">❌</td> <td class="no">❌</td> <td class="line"><a href="https://godbolt.org/z/9jcYhax4z">Godbolt</a></td> <td class="line">Wrong Param Type Spaceship</td> </tr>

<tr> <td class="legend"><code>int operator<=>(this A, A) = default;</code></td> <td class="yes tooltip">❌Must return auto or a category type</td> <td class="no">✅</td> <td class="yes">❌</td> <td class="no">❌</td> <td class="no">❌</td> <td class="line"><a href="https://godbolt.org/z/b6aGWP7zK">Godbolt</a></td> <td class="line">Wrong Return Type Spaceship</td> </tr>

<tr> <td class="legend"><code>int operator==(this A, A) = default;</code></td> <td class="yes tooltip">❌Must return bool</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="no">❌</td> <td class="no">❌</td> <td class="line"><a href="https://godbolt.org/z/66E7vfGM1">Godbolt</a></td> <td class="line">Wrong Return Type Equality</td> </tr>

<tr> <td class="legend"><code>auto operator<=>(this auto, A) = default;</code></td> <td class="yes tooltip">❌Must not be a template</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="yes">❌</td> <td class="line"><a href="https://godbolt.org/z/v66s7jdvr">Godbolt</a></td> <td class="line">Templated Spaceship</td> </tr> </tbody> </table> </div>

Hmmm... Guess let's not use DT on SMFs for now if you want portability...

Comparison of Minecraft Launchers

Tue, 26 Nov 2024 00:00:00 GMT

Being a popular name, Minecraft have billions of players around the world. However, the official launcher really sucks, so there exists a plethora of unofficial, third-party launchers that blews the official one miles away in terms of design and functionality. In this post, I try to compare the functionality of the most popular Minecraft launchers/clients. Due to my inability to use all of the launchers in depth and the inherent subjectivity of the topic, I will not compare the design (aesthetics) and performance of different launchers, only their offered functionality.

Launcher Selection

As of Nov 2024, I think there are ten most popular launchers out there: (italics is the one-line summary that exists on each launcher's official website; these are not my words but theirs.)

Minecraft Official Launcher. Well, the one and only, officially supported, launcher. Even though its bad performance, poor functionality, and lack of customization is the root cause of these different third-party launchers' existence, we still have to admit that this is the most used launcher, and the one that will be used by the beginners after buying the game.

Mod/Modpack Distribution Website Officials:
Modrinth App. The Modrinth App is a unique, open source launcher that allows you to play your favorite mods, and keep them up to date, all in one neat little package. Being the official launcher for the newly popularized mod distribution website Modrinth, this launcher have the best builtin integration with Modrinth mods and modpacks, and is often recommended for modders.
CurseForge App. Despite recent controversy, CurseForge is still the oldest, most comprehensive mod distribution website, and its launcher has the best integration with CurseForge mod and modpacks, so this is still the go-to choice for many.
FTB App. Being the world's largest modpack distributor, Feed The Best's official launcher was, for a quite long time, the only launcher that can download FTB modpacks directly, and it remained a generally okay launcher even to this day with tight integration.

Internationally Popular:
Prism Launcher. An Open Source Minecraft launcher with the ability to manage multiple instances, accounts and mods. Focused on user freedom and free redistributability. This is a fork of PolyMC after one of its main author committed several controversy actions, and PolyMC is a fork of ManyMC, who is a fork of MultiMC. MultiMC used to be the absolute best multi-instance launcher out there, but its development was abandoned in 2023, so multiple forks had emerged. In this post, for the entire MultiMC-series of launcher, I will just use Prism Launcher as a representative of all the MultiMC forks, since it is the most popular one.
ATLauncher. ATLauncher is a simple and easy to use Minecraft Launcher which contains 155 modpacks for you to choose from, as well as the ability to browse and install packs from other platforms including CurseForge, Modrinth and Technic. With built-in integration of many modpacks and download channels, this has become a recent favorite for many Minecraft modders.
GDLauncher. GDLauncher is a simple, yet powerful Minecraft custom launcher with a strong focus on the user experience. With automatic downloads of mods and modpacks from different channels and a builtin Java version manager, this is also a favorite for many people.

Chinese Creation: (Due to Netease's controversy takeover of Minecraft's distribution in China, many talented developer in China had developed fantastic third-party launchers for the international version of Minecraft, many exceeding the design and functionality provided by these mentioned above. However, a weakness is that these often have not-perfect English support.)
HMCL (Hello Minecraft! Launcher). A Minecraft Launcher which is multi-functional, cross-platform and popular. Being one of the oldest launcher developed, it enjoyed unparalleled popularity in China, with many beginner's tutorial directly recommending this launcher. During its early days, pirated play was a focus, but currently it supports official login pretty well.
PCL2 (Plain Craft Launcher 2). A recently-emerged launcher with convenient, sleek UI, and gained popularity very quickly.
BakaXL. BakaXL is distinctive in born. Breaking out the layer concept used by classical launchers, BakaXL is more than satisfying to use. You can use the powerful custom theme feature without any additional purchase, with parallax effect and live wallpaper working together, which is amazing! Originally designed as a client for a specific server, it has since emerged to one of the best-looking launchers out there, with blazing fast speed and modern design (written with Rust + Tauri).

What, Your Favorite Launcher Is Not Here?

This guide does not include launchers that

Only support pirated play of Minecraft. Please buy an official version, it is not expensive.
Have stopped maintaining.
Is a fork of one of the above.
That does not let you create custom instances (such as Technic's official launcher).
Have a limited user base.

The last one is subjective, but I really think these ten is a good representation of the most popular launchers in 2024. If you have any suggestions, feel free to open an issue to add more launchers.

Comparison Table

This table only resembles the then-current functionality as of Nov 2024.

<thead> <tr> <td class="legend" rowspan="3" colspan="2"></td> <td class="line">Official</td> <td class="line" colspan="3">Distribution Official</td> <td class="line" colspan="3">International</td> <td class="line" colspan="3">Chinese</td> </tr>

<tr> <td rowspan="2">Minecraft Launcher</td> <td rowspan="2">Modrinth App</td> <td rowspan="2">CurseForge App</td> <td rowspan="2">FTB App</td> <td rowspan="2">Prism Launcher</td> <td rowspan="2">ATLauncher</td> <td rowspan="2" class="tooltip">GDLauncherThis table focuses on the <a href="https://gdlauncher.com/docs/gdlauncher-vs-gdlauncher-carbon/">Carbon version</a></td> <td rowspan="2">HMCL</td> <td>PCL2</td> <td>BakaXL</td> </tr> <tr> <td> <table class="split"> <tr> <td style="font-size: smaller;">Regular</td> <td class="tooltip" style="font-size: smaller; border-right: 1px solid var(--line-divider); z-index: 1000;">CE<a href="https://github.com/PCL-Community/PCL2-CE">Community Edition</a></td> </tr> </table> </td> <td> <table class="split"> <tr> <td style="font-size: smaller;">v3</td> <td class="tooltip" style="font-size: smaller; border-right: 1px solid var(--line-divider);">v4Just <a href="https://www.bakaxl.com/v4">announced</a>, no snapshot binary available yet</td> </tr> </table> </td> </tr> </thead>

<tr> <td colspan="2"></td> <td class="semititle line" colspan="10">Development & Background</td> </tr>

<tr> <td class="legend" colspan="2">Developer</td> <td>Microsoft</td> <td>Modrinth</td> <td>Curse LLC</td> <td>Feed The Beast</td> <td class="tooltip">CommunityA <a href="https://prismlauncher.org/about/">group</a> of 11 maintainers</td> <td>Community</td> <td>GorillaDevs</td> <td class="tooltip">IndividualMade by huangyuhui</td> <td><table class="split"><tr> <td class="tooltip">IndividualMade by LTCat (龙腾猫跃)</td> <td>Community</td> </tr></table></td> <td class="tooltip">IndividualMade by TT702</td> </tr>

<tr> <td class="legend" colspan="2">Initial release</td> <td class="tooltip">2013The new launcher (v2.x, v3.x) was released in Jul 2019</td> <td>2023</td> <td>2022</td> <td>2022</td> <td class="tooltip">2022 (2014 for MultiMC)Prism Launcher's first forked version (v5.0) released in Oct 2022, before that it is under the name of PolyMC since Mar 2022, when it is itself forked from MultiMC</td> <td>2016</td> <td>2018</td> <td>2015</td> <td><table class="split"><tr> <td>2018</td> <td>2024</td> </tr></table></td> <td>2015</td> </tr>

<tr> <td class="legend" colspan="2">Open Source</td> <td class="no">No</td> <td class="yes"><a href="https://github.com/modrinth/code/blob/main/apps/app/README.md">Yes</a></td> <td class="no">No</td> <td class="yes"><a href="https://github.com/FTBTeam/FTB-App">Yes</a></td> <td class="yes"><a href="https://github.com/PrismLauncher/PrismLauncher">Yes</a></td> <td class="yes"><a href="https://github.com/ATLauncher/ATLauncher">Yes</a></td> <td class="yes"><a href="https://github.com/gorilla-devs/GDLauncher-Carbon">Yes</a></td> <td class="yes"><a href="https://github.com/HMCL-dev/HMCL">Yes</a></td> <td class="line"><table class="split"><tr> <td class="almost tooltip"><a href="https://github.com/Hex-Dragon/PCL2">Kind-of</a>Source code repo is only updated after each stable release</td> <td class="yes"><a href="https://github.com/PCL-Community/PCL2-CE">Yes</a></td> </tr></table></td> <td class="no">No</td> </tr>

<tr> <td class="legend" colspan="2">License</td> <td>N/A</td> <td>GPL-3.0</td> <td>N/A</td> <td>LGPL-2.1</td> <td>GPL-3.0</td> <td>GPL-3.0</td> <td class="tooltip"><a href="https://github.com/gorilla-devs/GDLauncher-Carbon/blob/develop/LICENSE">Custom</a>The legacy version was GPL-3.0</td> <td>GPL-3.0</td> <td><table class="split"><tr> <td><a href="https://github.com/Hex-Dragon/PCL2/blob/main/LICENCE">Custom</a></td> <td><a href="https://github.com/PCL-Community/PCL2-CE/blob/dev/LICENCE">Custom</a></td> </tr></table></td> <td>N/A</td> </tr>

<tr> <td class="legend tooltip" colspan="2">Development BuildsIncluding nightly, beta, ...</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="yes"><a href="https://github.com/FTBTeam/FTB-App/tags">Yes</a></td> <td class="yes tooltip"><a href="https://prismlauncher.org/wiki/development/development-builds/">Yes</a>Per-commit build. Also available as -git packages</td> <td class="yes"><a href="https://atl.pw/launcher-nightly">Yes</a></td> <td class="yes"><a href="https://github.com/gorilla-devs/GDLauncher/releases">Yes</a></td> <td class="yes"><a href="https://hmcl.huangyuhui.net/download/">Yes</a></td> <td class="line"><table class="split"><tr> <td class="mixed"><a href="https://afdian.com/p/0164034c016c11ebafcb52540025c377">Paywalled</a></td> <td class="yes"><a href="https://github.com/PCL-Community/PCL2-CE/releases">Yes</a></td> </tr></table></td> <td class="line"><table class="split"><tr> <td class="yes tooltip"><a href="http://jk-insider.bakaxl.com:8888/job/BakaXL%20Insider%20Parrot/lastSuccessfulBuild/">Yes</a>Already in LTS, no new feature planned</td> <td class="no tooltip">NoInsider preview available for <a href="https://afdian.com/a/TT702">paid members</a></td> </tr></table></td> </tr>

<tr> <td class="legend" colspan="2">Core Language</td> <td>C++</td> <td>Rust</td> <td rowspan="2">Unknown</td> <td>TypeScript</td> <td>C++</td> <td>Java</td> <td class="tooltip">RustThe old version was written in JavaScript</td> <td>Java</td> <td>VB.NET</td> <td><table class="split"><tr> <td>JavaScript</td> <td>Rust</td> </tr></table></td> </tr>

<tr> <td class="legend tooltip" colspan="2">UI FrameworkMany also used Vue, which will not be listed</td> <td>Chromium Embedded Framework</td> <td>Tauri</td> <td>Electron</td> <td>Qt</td> <td>Java Swing</td> <td class="tooltip">SolidJSThe old version was written in Electron</td> <td>JavaFX</td> <td>WPF</td> <td><table class="split"><tr> <td>Electron</td> <td>Tauri</td> </tr></table></td> </tr>

<tr> <td colspan="2"></td> <td class="semititle line" colspan="10">Platform Support</td> </tr>

<tr> <td class="legend" rowspan="3">Windows</td> <td class="legend">64-bit</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend tooltip" style="z-index: 1001;">32-bitLatest Minecraft version that supports 32-bit OS is 1.20.4</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no tooltip">NoMultiMC has 32-bit support</td> <td class="almost tooltip">Should workJAR file provided</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="line"><table class="split"><tr> <td class="almost tooltip">Yes32-bit support works, but <a href="https://github.com/Hex-Dragon/PCL2/issues/3649">no maintenance work is planned</a>. Bugfix reports will be ignored</td> <td class="no">No</td> </tr></table></td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend tooltip" style="z-index: 1000;">ARM 64-bitOfficially supported only after 1.19</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="almost tooltip">Should workJAR file provided</td> <td class="no">No</td> <td class="yes tooltip">YesHMCL extended Minecraft ARM support to 1.8</td> <td class="line"><table class="split"><tr> <td class="no"><a href="https://github.com/Hex-Dragon/PCL2/issues/1960">No</a></td> <td class="yes">Yes</td> </tr></table></td> <td class="line"><table class="split"><tr> <td class="no">No</td> <td class="yes">Yes</td> </tr></table></td> </tr>

<tr> <td class="legend" rowspan="2">macOS</td> <td class="legend">64-bit</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes" rowspan="2">Universal</td> <td class="yes">Yes</td> <td class="yes" rowspan="2">Universal</td> <td class="yes" rowspan="2">Universal JAR</td> <td class="yes" rowspan="2">Universal</td> <td class="yes tooltip" rowspan="2">Universal JARHMCL extended Minecraft ARM support to 1.8 using Rosetta 2</td> <td class="no" rowspan="5"><a href="https://github.com/Hex-Dragon/PCL2/issues/54">No</a></td> <td class="line"><table class="split"><tr> <td class="no">No</td> <td class="mixed">Unknown</td> </tr></table></td> </tr>

<tr> <td class="legend tooltip" style="z-index: 1000;">ARM 64-bitOfficially supported only after 1.19</td> <td class="almost">Rosetta 2</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="line"><table class="split"><tr> <td class="no">No</td> <td class="yes">Yes</td> </tr></table></td> </tr>

<tr> <td class="legend" rowspan="2">Linux</td> <td class="legend">64-bit</td> <td class="almost">DEB+TAR</td> <td class="yes">DEB+RPM</td> <td class="mixed">DEB only</td> <td class="yes">DEB+RPM</td> <td class="mixed">TAR only</td> <td class="yes">DEB+RPM</td> <td class="mixed">AppImage only</td> <td class="yes">JAR</td> <td class="line"><table class="split"><tr> <td class="no">No</td> <td class="yes">Yes</td> </tr></table></td> </tr>

<tr> <td class="legend tooltip" style="z-index: 1000;">ARM 64-bitOfficially supported only after 1.19</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">DEB+RPM</td> <td class="mixed">Flatpak only</td> <td class="almost">JAR</td> <td class="no">No</td> <td class="yes">JAR</td> <td class="line"><table class="split"><tr> <td class="no">No</td> <td class="mixed">Unknown</td> </tr></table></td> </tr>

<tr> <td class="legend tooltip" colspan="2">OtherNo official support</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="mixed">JAR may work</td> <td class="no">No</td> <td class="yes tooltip">JARHMCL <a href="https://github.com/HMCL-dev/HMCL/blob/main/PLATFORM.md">supports</a> ARM32, MIPS64el, RISC-V 64, LoongArch64, and FreeBSD</td> <td class="no">No</td> </tr>

<tr> <td colspan="2"></td> <td class="semititle line tooltip" colspan="10">Distribution ChannelOnly Intel/AMD 64-bit distributions are considered</td> </tr>

<tr> <td class="legend tooltip" colspan="2" style="z-index: 1000;">Portablei.e. no setup and no dependency executable</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes tooltip">YesWindows only; other platform can use JAR</td> <td class="no">No</td> <td class="yes tooltip">YesWindows only; other platform can use JAR</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend" rowspan="4">Windows</td> <td class="legend">Microsoft Store</td> <td class="yes"><a href="https://www.xbox.com/en-SG/games/store/minecraft-launcher/9pgw18npbzv5?ocid=storeforweb">Yes</a></td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend">WinGet</td> <td class="yes"><a href="https://winget.run/pkg/Mojang/MinecraftLauncher">Yes</a></td> <td class="yes"><a href="https://winstall.app/apps/Modrinth.ModrinthApp">Yes</a></td> <td class="yes"><a href="https://winget.run/pkg/Overwolf/CurseForge">Yes</a></td> <td class="yes"><a href="https://winstall.app/apps/FTB.App">Yes</a></td> <td class="yes"><a href="https://winget.run/pkg/PrismLauncher/PrismLauncher">Yes</a></td> <td class="yes"><a href="https://winget.run/pkg/ATLauncher/ATLauncher">Yes</a></td> <td class="yes"><a href="https://winget.run/pkg/GorillaDevs/GDLauncher">Yes</a></td> <td class="yes"><a href="https://winget.run/pkg/huanghongxun/HelloMinecraftLauncher">Yes</a></td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend">Chocolatey</td> <td class="almost"><a href="https://community.chocolatey.org/packages/minecraft-launcher">Unofficial</a></td> <td class="no">No</td> <td class="no">No</td> <td class="almost"><a href="https://community.chocolatey.org/packages/ftb">Unofficial</a></td> <td class="almost"><a href="https://community.chocolatey.org/packages/prismlauncher">Unofficial</a></td> <td class="no">No</td> <td class="almost"><a href="https://community.chocolatey.org/packages/gdlauncher">Unofficial</a></td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend">Scoop</td> <td class="yes tooltip">Yesgames/minecraft</td> <td class="mixed">Unofficial</td> <td class="mixed">Unofficial</td> <td class="no">No</td> <td class="yes tooltip">Yesgames/prismlauncher[-git]</td> <td class="mixed">Unofficial</td> <td class="mixed">Unofficial</td> <td class="mixed">Unofficial</td> <td class="line"><table class="split"><tr> <td class="mixed">Unofficial</td> <td class="no">No</td> </tr></table></td> <td class="no">No</td> </tr>

<tr> <td class="legend primary-legend">macOS</td> <td class="legend">Homebrew</td> <td class="yes"><a href="https://formulae.brew.sh/cask/minecraft">Yes</a></td> <td class="yes"><a href="https://formulae.brew.sh/cask/modrinth">Yes</a></td> <td class="yes"><a href="https://formulae.brew.sh/cask/curseforge">Yes</a></td> <td class="yes"><a href="https://formulae.brew.sh/cask/feed-the-beast">Yes</a></td> <td class="yes"><a href="https://formulae.brew.sh/cask/prismlauncher">Yes</a></td> <td class="yes"><a href="https://formulae.brew.sh/cask/atlauncher">Yes</a></td> <td class="no tooltip">NoThe <a href="https://formulae.brew.sh/cask/gdlauncher">legacy version</a> is available</td> <td class="no">No</td> <td class="line">N/A</td> <td class="line">N/A</td> </tr>

<tr> <td class="legend" rowspan="3">Linux Universal</td> <td class="legend">Flathub</td> <td class="mixed"><a href="https://flathub.org/apps/com.mojang.Minecraft">Unofficial</a></td> <td class="yes tooltip"><a href="https://flathub.org/apps/com.modrinth.ModrinthApp">YesAlthough unverified, recommended by the official website</a></td> <td class="no">No</td> <td class="no">No</td> <td class="yes"><a href="https://flathub.org/apps/org.prismlauncher.PrismLauncher">Yes</a></td> <td class="yes"><a href="https://flathub.org/apps/com.atlauncher.ATLauncher">Yes</a></td> <td class="mixed"><a href="https://flathub.org/apps/io.gdevs.GDLauncher">Unofficial</a></td> <td class="no">No</td> <td class="line" rowspan="3">N/A</td> <td class="line" rowspan="3">N/A</td> </tr>

<tr> <td class="legend">AppImage</td> <td class="mixed"><a href="https://portable-linux-apps.github.io/apps/minecraft-launcher.html">AppMan</a></td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="mixed"><a href="https://portable-linux-apps.github.io/apps/hmcl.html">AppMan</a></td> </tr>

<tr> <td class="legend">Snap</td> <td class="mixed"><a href="https://snapcraft.io/mc-installer">Unofficial</a></td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="notreally"><a href="https://snapcraft.io/gdlauncher">Abandoned</a></td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend" rowspan="10">Linux Distros</td> <td class="legend">Alpine</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="almost"><a href="https://pkgs.alpinelinux.org/package/edge/community/x86_64/prismlauncher">Community</a></td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="line" rowspan="10">N/A</td> <td class="line" rowspan="10">N/A</td> </tr>

<tr> <td class="legend tooltip" style="z-index: 1001;">Archincl. Manjaro</td> <td class="almost tooltip" style="z-index: 1000;"><a href="https://aur.archlinux.org/packages/minecraft-launcher">AUR</a>Officially recommended</td> <td class="mixed"><a href="https://aur.archlinux.org/packages/modrinth-app">AUR</a></td> <td class="mixed"><a href="https://aur.archlinux.org/packages/curseforge">AUR</a></td> <td class="mixed"><a href="https://aur.archlinux.org/packages/ftb-app">AUR</a></td> <td class="yes"><a href="https://archlinux.org/packages/extra/x86_64/prismlauncher/">Yes</a></td> <td class="mixed"><a href="https://aur.archlinux.org/packages/atlauncher">AUR</a></td> <td class="mixed"><a href="https://aur.archlinux.org/packages/gdlauncher">AUR</a></td> <td class="mixed"><a href="https://aur.archlinux.org/packages/hmcl">AUR</a></td> </tr>

<tr> <td class="legend tooltip">Fedoraincl. CentOS Stream/RHEL</td> <td class="mixed"><a href="https://github.com/terrapkg/packages/tree/frawhide/anda/games/minecraft-java">Terra</a></td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="mixed"><a href="https://copr.fedorainfracloud.org/coprs/g3tchoo/prismlauncher/">COPR</a></td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend tooltip">Debianincl. Ubuntu</td> <td class="mixed"><a href="https://mpr.makedeb.org/packages/minecraft-launcher">MPR</a></td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="mixed"><a href="https://mpr.makedeb.org/packages/prismlauncher">MPR</a></td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend">Gentoo</td> <td class="yes"><a href="https://packages.gentoo.org/packages/games-action/minecraft-launcher">Yes</a></td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes"><a href="https://packages.gentoo.org/packages/games-action/prismlauncher">Yes</a></td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend">NixOS</td> <td class="yes"><a href="https://search.nixos.org/packages?query=minecraft-launcher">Yes</a></td> <td class="yes"><a href="https://search.nixos.org/packages?query=modrinth-app">Yes</a></td> <td class="no">No</td> <td class="no">No</td> <td class="yes"><a href="https://search.nixos.org/packages?query=prismlauncher">Yes</a></td> <td class="yes"><a href="https://search.nixos.org/packages?query=atlauncher">Yes</a></td> <td class="no">No</td> <td class="yes"><a href="https://search.nixos.org/packages?query=hmcl">Yes</a></td> </tr>

<tr> <td class="legend tooltip">openSUSEincl. SLE</td> <td class="almost"><a href="https://build.opensuse.org/package/show/games/minecraft-launcher">Games</a></td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="mixed"><a href="https://build.opensuse.org/package/show/home:getchoo/prismlauncher">OBS</a></td> <td class="no">No</td> <td class="no">No</td> <td class="mixed"><a href="https://build.opensuse.org/package/show/home:Psheng/HMCL">OBS</a></td> </tr>

<tr> <td class="legend">Slackware</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="mixed"><a href="https://slackbuilds.org/repository/15.0/games/PrismLauncher/">SlackBuilds</a></td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend">Void</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes tooltip">YesPrismLauncher</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td colspan="2"></td> <td class="semititle line" colspan="10">Basics</td> </tr>

<tr> <td class="legend" rowspan="6">Minecraft Versions</td> <td class="legend">Releases</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend">Snapshots</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend tooltip" style="z-index: 1002;">BetasDec 2010 (b1.0) - Sep 2011 (b1.8.1)</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend tooltip" style="z-index: 1001;">AlphasMay 2009 (rd-132211) - Dec 2010 (a1.2.6)</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend tooltip" style="z-index: 1000;">Experimentse.g. 1.14-16 combat experiment, 1.18-19 experiment snapshot</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend" colspan="2">Version Release Notes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend" rowspan="4">Java</td> <td class="legend">Bundled</td> <td class="yes tooltip">YesBundled with Microsoft-built OpenJDK</td> <td class="no">No</td> <td class="notreally tooltip">DelegatedUsed the official launcher's Java</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend">Auto Detect</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend">Auto Download</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="almost tooltip">YesAutomatically downloads Adoptium JDK at startup, regardless of whether you have Java installed</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend tooltip" style="z-index: 1000;">Auto MatchIn general, it is recommended to use Java 8 for 1.16-, Java 17 for 1.17-1.20.4, and Java 21 for 1.20.5+</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td colspan="2"></td> <td class="semititle line" colspan="10">Accounts</td> </tr>

<tr> <td class="legend" rowspan="3">Singleplayer</td> <td class="legend">Microsoft</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="almost tooltip">YesRequires connection code</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="almost tooltip">YesRequires connection code</td> <td class="almost tooltip">YesRequires connection code</td> <td class="almost tooltip">YesRequires connection code</td> <td class="almost tooltip">YesRequires connection code</td> </tr>

<tr> <td class="legend">Offline</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend tooltip" style="z-index: 1001;">Piratedi.e. offline without valid account</td> <td class="yes">No</td> <td class="yes">No</td> <td class="yes">No</td> <td class="yes">No</td> <td class="yes">No</td> <td class="yes">No</td> <td class="yes">No</td> <td class="mixed tooltip">In ChinaOutside mainland China, the launcher will require a valid account before allowing offline play</td> <td class="mixed tooltip">In ChinaOutside mainland China, the launcher will require a valid account before allowing offline play</td> <td class="mixed tooltip">In ChinaOutside mainland China, the launcher will require a valid account before allowing offline play</td> </tr>

<tr> <td class="legend tooltip" colspan="2" style="z-index: 1000;">Quick PlayOnly available for 1.20+</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="notreally tooltip">SomewhatSupport a beta "quick launch" mode that skips the official launcher, but cannot directly join worlds</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend" colspan="2">Skin Management</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td colspan="2"></td> <td class="semititle line" colspan="10">Modding</td> </tr>

<tr> <td class="legend" rowspan="7">Mod Loader Auto Install</td> <td class="legend">Forge</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend tooltip" style="z-index: 1005;">NeoForgeFork of Forge, only available for 1.20.1+</td> <td class="no">No</td> <td class="almost tooltip">YesCrash/hang when unsupported version selected</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend tooltip" style="z-index: 1004;">FabricOnly available for 1.14+</td> <td class="no">No</td> <td class="almost tooltip">YesCrash/hang when unsupported version selected</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend tooltip" style="z-index: 1003;">Legacy FabricFork of Fabric that supports version prior to 1.14</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend tooltip" style="z-index: 1002;">QuiltOnly available for 1.14+</td> <td class="no">No</td> <td class="almost tooltip">YesCrash/hang when unsupported version selected</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend tooltip" style="z-index: 1001;">LiteLoaderDiscontinued. Only available for 1.6.2-1.12.2</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="notreally tooltip">NoListed as "unsupported yet"</td> </tr>

<tr> <td class="legend tooltip" style="z-index: 1000;">OptiFineNot a mod loader, but essential for some shaders</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend" rowspan="2">Mod Download</td> <td class="legend">Modrinth</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend">CurseForge</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes tooltip">YesUse website opening to bypass blocked mods</td> <td class="yes tooltip">YesUse website opening to bypass blocked mods</td> <td class="yes tooltip">YesBypass granted by CurseForge</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend" rowspan="2">Resource Pack Download</td> <td class="legend">Modrinth</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="line"><table class="split"><tr> <td class="no">No</td> <td class="yes">Yes</td> </tr></table></td> <td class="no">No</td> </tr>

<tr> <td class="legend">CurseForge</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="line"><table class="split"><tr> <td class="no">No</td> <td class="yes">Yes</td> </tr></table></td> <td class="no">No</td> </tr>

<tr> <td class="legend" rowspan="2">Shader Pack Download</td> <td class="legend">Modrinth</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="line"><table class="split"><tr> <td class="no">No</td> <td class="yes">Yes</td> </tr></table></td> <td class="no">No</td> </tr>

<tr> <td class="legend">CurseForge</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="line"><table class="split"><tr> <td class="no">No</td> <td class="yes">Yes</td> </tr></table></td> <td class="no">No</td> </tr>

<tr> <td class="legend" colspan="2">Mod Version Auto-Match</td> <td class="line" rowspan="2">N/A</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend" colspan="2">Mod Dependency</td> <td class="almost tooltip">Install onlyDisable mods will not warn about dependency</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes tooltip">Yes<a href="https://github.com/PrismLauncher/PrismLauncher/pull/3738">Coming in v11</a></td> <td class="almost tooltip">Install onlyDisable mods will not warn about dependency</td> <td class="almost tooltip">Install onlyDisable mods will not warn about dependency</td> <td class="almost tooltip">Install onlyDisable mods will not warn about dependency</td> <td class="almost tooltip">Install onlyDisable mods will not warn about dependency</td> <td class="almost tooltip">Install onlyDisable mods will not warn about dependency</td> </tr>

<tr> <td class="legend" rowspan="2">Datapack Download</td> <td class="legend">Modrinth</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend">CurseForge</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend" colspan="2">CurseForge World Download</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend" rowspan="5">Modpack Download</td> <td class="legend">Modrinth</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend">CurseForge</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes tooltip">YesURL / Select</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend">FTB</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes tooltip">Yes<a href="https://github.com/PrismLauncher/PrismLauncher/pull/3559">Coming in v11</a></td> <td class="yes tooltip">YesFTB modpack downloading was restored in Nov 2024</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend">Technic</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend">ATLauncher</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="almost">Experimental</td> <td class="yes tooltip">YesURL / ID / Select</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend" rowspan="2">Auto Update</td> <td class="legend">Mod(pack)</td> <td class="line" rowspan="2">N/A</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="mixed">Mod only</td> <td class="no">No</td> </tr>

<tr> <td class="legend">Resource/Shader</td> <td class="no tooltip">NoUpdater ignores non-mods</td> <td class="yes">Yes</td> <td class="line">N/A</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="line">N/A</td> <td class="no">No</td> <td class="line"><table class="split"><tr> <td>N/A</td> <td class="no">No</td> </tr></table></td> <td class="line">N/A</td> </tr>

<tr> <td colspan="2"></td> <td class="semititle line" colspan="10">Functionality</td> </tr>

<tr> <td class="legend" colspan="2">Multi-Language Support</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="notreally tooltip">WIPAvailable in <a href="https://github.com/Hex-Dragon/PCL2/discussions/4580">development builds</a></td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend" colspan="2">In-Game Overlay</td> <td class="no">No</td> <td class="no">No</td> <td class="yes tooltip">Yesvia Overwolf</td> <td class="yes tooltip">Yesvia Overwolf</td> <td class="mixed tooltip">Linux onlyvia MangoHUD</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend" colspan="2">Instance Separation</td> <td class="notreally tooltip">ManualPossible by manually selecting different directories</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> </tr>

<tr> <td class="legend" colspan="2">Instance Grouping</td> <td class="no">No</td> <td class="yes tooltip">YesVia setting categories</td> <td class="no">No</td> <td class="yes tooltip">YesVia setting categories</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes tooltip">YesVia bookmark</td> <td class="no">No</td> </tr>

<tr> <td class="legend" colspan="2">Instance Backup</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend" colspan="2">One-Click Instance Launch</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes tooltip">YesCan create shortcut for instances on desktop</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend tooltip" colspan="2" style="z-index: 1001;">Directory OpenerEasy/one-click access to mods, shareds, ... folders</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend tooltip" colspan="2" style="z-index: 1000;">World Managemente.g. Rename without launch the game, MCEdit, ...</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="line"><table class="split"><tr> <td class="no">No</td> <td class="yes">Yes</td> </tr></table></td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend" colspan="2">Screenshot Management</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="line"><table class="split"><tr> <td class="no">No</td> <td class="yes">Yes</td> </tr></table></td> <td class="no">No</td> </tr>

<tr> <td class="legend" colspan="2">Proxy</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="almost">Beta</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend" colspan="2">Customized Font</td> <td class="mixed">Size only</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="line"><table class="split"><tr> <td class="no"><a href="https://github.com/Hex-Dragon/PCL2/issues/366">No</a></td> <td class="yes">Yes</td> </tr></table></td> <td class="no">No</td> </tr>

<tr> <td class="legend" colspan="2">Themes</td> <td class="no">No</td> <td class="mixed tooltip">PresetHave preset light / dark / OLED themes, no custom theme support</td> <td class="mixed tooltip">PaywalledClassic / Light is free, other themes need premium</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="mixed tooltip">PresetHave 4 presets, no custom theme support</td> <td class="yes">Yes</td> <td><table class="split"><tr> <td class="mixed">Paywalled</td> <td class="yes">Yes</td> </tr></table></td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend" colspan="2">Background</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="mixed">Have Cat</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend tooltip" colspan="2">UtilitiesNetwork Checker, ...</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> </tr>

<tr> <td colspan="2"></td> <td class="semititle line" colspan="10">Advanced</td> </tr>

<tr> <td class="legend" rowspan="7">Instance Import / Export</td> <td class="legend tooltip">Modrinthmrpack</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="mixed">Import only</td> <td class="mixed">Import only</td> <td class="mixed">Import only</td> </tr>

<tr> <td class="legend tooltip">CurseForgeZIP</td> <td class="no">No</td> <td class="mixed tooltip">Import onlyCan only import from CurseForge App</td> <td class="yes">Yes</td> <td class="mixed">Import only</td> <td class="yes tooltip">YesZIP / URL</td> <td class="yes tooltip">YesZIP / URL</td> <td class="yes tooltip">YesZIP / URL</td> <td class="mixed">Import only</td> <td class="mixed">Import only</td> <td class="mixed">Import only</td> </tr>

<tr> <td class="legend tooltip">FTBshare code</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend tooltip">TechnicZIP</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="mixed">Import only</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend tooltip">MultiMCZIP</td> <td class="no">No</td> <td class="mixed tooltip">Import onlyCan import instance from MultiMC / GDLauncher / ATLauncher</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="mixed">Export only</td> <td class="no">No</td> <td class="mixed">Import only</td> </tr>

<tr> <td class="legend tooltip">ATLauncherZIP</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend tooltip">MCBBSv2, ZIP</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend" colspan="2">Command Line Interface</td> <td class="yes"><a href="https://minecraft.fandom.com/wiki/Minecraft_Launcher#Command_line_usage">Yes</a></td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes"><a href="https://prismlauncher.org/wiki/getting-started/command-line-interface/">Yes</a></td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend" colspan="2">JVM Param / Memory Limit</td> <td class="almost tooltip">YesNo memory limit support, possible by passing -Xmx/-Xms</td> <td class="yes">Yes</td> <td class="almost tooltip">YesBuilt-in memory limit support but no parameter support, possible through official launcher</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend" colspan="2">Environmental Variables</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend tooltip" colspan="2" style="z-index: 1000;">APIPastebin, Modrinth/CurseForge API key, ...</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes tooltip">YesMineTogether</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> </tr>

<tr> <td class="legend" colspan="2">Log Console</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="notreally tooltip">StaticLogs shown only on error</td> </tr>

<tr> <td class="legend" colspan="2">Log Analyze</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="yes">Yes</td> </tr>

<tr> <td class="legend tooltip" colspan="2" style="z-index: 1000;">Window Settingsprocess priority, window title, ...</td> <td class="no">No</td> <td class="mixed tooltip">PartialSupports fullscreen and width / height spec</td> <td class="mixed tooltip">PartialSupports fullscreen and width / height spec</td> <td class="no">No</td> <td class="mixed tooltip">PartialSupports fullscreen and width / height spec</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="yes">Yes</td> <td class="mixed tooltip">PartialSupports fullscreen and width/height spec</td> </tr>

<tr> <td class="legend" colspan="2">NBT Analyze</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="no">No</td> <td class="yes">Yes</td> <td class="no">No</td> <td class="no">No</td> </tr> </tbody>

<tr> <td colspan="2"></td> <td class="semititle line" colspan="10">Summary</td> </tr>

<tr> <td class="legend tooltip" colspan="2" style="z-index: 1000;">Total ScoreYes = 1, Almost = 0.8, Mixed = 0.5, Not really = 0.2, No = 0; Maximum Score: 100</td> <td class="no">32.7</td> <td class="mixed">42.2</td> <td class="no">30.7</td> <td class="mixed">39.2</td> <td class="yes">76.4</td> <td class="yes">60.9</td> <td class="mixed">35.9</td> <td class="yes">55.6</td> <td class="line"><table class="split"><tr> <td class="mixed">37.9</td> <td class="mixed">45.8</td> </tr></table></td> <td class="line"><table class="split"><tr> <td class="no">34.5</td> <td class="mixed">37.5</td> </tr></table></td> </tr>

</table> </div>

Notes:

This table does not consider multiplayer/server-related functionalities (server opening/management, hosting, ...) due to me being unfamiliar with servers. An equally comprehensive comparison table here can be used for that.
The BakaXL column contains only the information for v3 for now (except the announced mutli-platform support). After v4 released I will update this column.

Screenshots

Several screenshots, mostly from official websites, to give a sense on what the UI for each launcher looks like.

<figure class="image screenshot"> <img src="/upload/minecraft-launcher-comparison/official-launcher.webp" alt="Official Launcher"> <figcaption>Official Launcher</figcaption> </figure>

<figure class="image screenshot"> <img src="/upload/minecraft-launcher-comparison/modrinth.webp" alt="Modrinth App"> <figcaption>Modrinth App v0.8.9</figcaption> </figure>

<figure class="image screenshot"> <img src="/upload/minecraft-launcher-comparison/curseforge.webp" alt="Modrinth App"> <figcaption>CurseForge App v1.265.0</figcaption> </figure>

<figure class="image screenshot"> <img src="/upload/minecraft-launcher-comparison/prism-launcher.webp" alt="Prism Launcher"> <figcaption>Prism Launcher v9.1</figcaption> </figure>

<figure class="image screenshot"> <img src="/upload/minecraft-launcher-comparison/atlauncher.webp" alt="ATLauncher"> <figcaption>ATLauncher v3.4.38.0</figcaption> </figure>

<figure class="image screenshot"> <img src="/upload/minecraft-launcher-comparison/gdlauncher.webp" alt="GDLauncher"> <figcaption>GDLauncher v2.0.20</figcaption> </figure>

<figure class="image screenshot"> <img src="/upload/minecraft-launcher-comparison/bakaxl.png" alt="BakaXL"> <figcaption>BakaXL v3.5.1.0</figcaption> </figure>

Star History Charts

Here is the GitHub star history graph for some of the launchers above: <figure class="image star-count"> <a href="https://star-history.com/#modrinth/code&FTBTeam/FTB-App&MultiMC/Launcher&PrismLauncher/PrismLauncher&ATLauncher/ATLauncher&gorilla-devs/GDLauncher&HMCL-dev/HMCL&Hex-Dragon/PCL2&PCL-Community/PCL2-CE&BakaXL-Launcher/BakaXL&Date"> <img src="https://api.star-history.com/svg?repos=modrinth/code,FTBTeam/FTB-App,MultiMC/Launcher,PrismLauncher/PrismLauncher,ATLauncher/ATLauncher,gorilla-devs/GDLauncher,HMCL-dev/HMCL,Hex-Dragon/PCL2,PCL-Community/PCL2-CE,BakaXL-Launcher/BakaXL&type=Date" alt="Star History Chart"> </a> </figure>

Notes:

PCL2 and BakaXL are not fully open-sourced, so their star counts are not representative.
GDLauncher's star count is for the legacy version, the Carbon version is too new to get a representative count.
MultiMC has stopped development after 2023, hence the difference in trend.
Modrinth's repo contains both the code for the app and the entire website.

The Definitive Guide to Operator Overloading in C++

Tue, 30 Apr 2024 00:00:00 GMT

Operator overloading has always been one of the most integral parts that makes C++, well, C++. From the nearly-regular overload of operator= for copy and move assignments to the IOStream’s (mis)use of operator<< and >> for I/O, which every C++ programmer learns on the first day of the class, no one can deny that without operator overloading, many common idioms and syntaxes we are already accustomed to will no longer be possible.

Yet the topic of operator overloading has always been a complex one, with intricacies that are not easy to understand and explore, and confusion and arguments on the best way to overload operators have prevailed ever since C++98. Furthermore, to make matters worse, each edition of C++ tweaked more and more operators to make them more friendly and also added more and more novel operators that we can overload:

C++11 introduced the overloadable operator ""udl (User-Defined Literals, we will treat it as an operator in this article since its function name contains operator) and also introduced explicit conversion operators to obsolete the Safe Bool Idiom.
C++20 introduced operator<=> (the spaceship) to obsolete five of the six comparison operators while also introducing the confusingly complex operator co_await that we can also overload.
C++23 introduced a static version of operator() and operator[] and made the latter N-arg overloadable, changing decades of customs and perceptions of those operators.

What are the most canonical forms of overloading each operator? What are the usual idioms and protocols you must follow? Most importantly, what idiom prevailed in the C++23-era world, and what idiom had been made obsolete? Even with several excellent guides written on the topics, they are either too old or don’t cover every operator’s intricacies. This guide is meant to answer all of those questions once and for all.

All of the contents will be based on the finalized C++23 standard.

Basic Terminology

Basics of Operator Overloading

So, what is operator overloading? As its name suggests, operator overloading basically gives you a way of customizing the behavior of operators. However, it should be made clear that this is not a way to change the meaning of operators like 1 + 2, but to give meaning to the otherwise-meaningless expression like p1 + p2, where p1 and p2 are objects of your custom class Point. Since the compiler doesn’t know how to add two Point objects, it simply refuses to compile unless you tell the compiler what to do by overloading the + operator on Points.

So, how do you tell the compiler? For any operator you want to overload, say +, there are two different syntaxes to overload the operator: member and non-member.

struct Point
{
    Point operator+(const Point& rhs) const { /* ... */ } // Member
    Point func(const Point& rhs) const;
};
Point operator+(const Point& lhs, const Point& rhs) { /* ... */ } // Non-member

After specifying one of those two forms, the compiler will then treat p1 + p2 as a pure syntactic sugar: If a member operator+ is found, p1 + p2 is rewritten into p1.operator+(p2) and executed, and you can access p1 as this, p2 as rhs in the function body. If a non-member is found, then p1 + p2 is rewritten into operator+(p1, p2), and you can access p1 and p2 as lhs and rhs, respectively.

One subtle thing to notice here is that operator+ is (in some sense) not a magic name. It is literally just a function name, appearing where typically function names are found. In fact, you can even call it like a regular function, so p1.operator+(p2) is actually valid C++ code. Therefore, defining an operator overload is literally just defining a member or non-member function, and the only magic is the sugar of rewriting p1 + p2 into a function call form.

Since operator+, like func, is a normal function, all the usual privileges and restrictions of member and non-member functions apply. For example, you can add const, volatile, &, or any other valid qualifiers on regular member functions to the operator functions. You can make them templates, add requires, etc. Also, you can overload operator+, and the compiler will make an overload resolution as usual when dealing with p1 + p2.

Of course, some requirements do exist on operator functions, so they are not precisely equivalent to ordinary functions. These requirements are:

Each operator has its arity and membership requirements, so a binary operator like / can only be a function with two arguments. Writing operator/(int, int, int) is a hard error.
If implemented as a non-member, at least one argument must be of (possibly reference to) a type that is dependent on at least one user-defined type. This effectively means that you cannot simply change what 1 + 2 means by overloading operator+(int, int); you can only overload operators for non-builtin types.
Operator functions may not have default arguments, except for operator() and operator[]. (Also, all operators except those two are either unary or binary, so they must have one or two arguments.)
If implemented as a member, operator functions may not be static, again, except for operator() and operator[].

However, except for those minor requirements, they behave entirely like normal functions. Especially notice that there are absolutely no requirements on what the return type and argument types must be (except for operator->, but that will be covered in its own section later), so you can definitely write an operator+ that takes two BigInts and returns a std::string. Also, no requirements are put on the implementation of operator functions, so it is also possible to write an operator+ on your BigInt class such that a + b actually does subtraction.

However, one thing needs to be especially remembered when doing operator overloading:

Just because you can do something doesn’t mean you should!

In general, you really shouldn’t write surprise operators like that. Each operator has its own established meaning and relationships, and you should really respect them. a + b should do what addition usually does for that class. In this sense, std::string::operator+ is actually a misuse since there is not really an established meaning of what adding two strings should do in a mathematical sense (the current semantics, concatenation, is not even communicative!). While you may argue that + for string means concatenation is so widespread and so universally adopted that it can be carved out as an exception, just as in Java, where no general operator overloading is allowed, but String still has +. (Even though I would argue that, again, it is better provided as an ordinary function that can have richer meaning, like slicing the second string, and there exist popular languages that chose not to abuse +.)

However, even if you made that argument, another classical misuse of operator overloading in the STL cannot be explained away: IOStream’s use of << and >> for input and output. There, the grounds are much weaker: there is no precedent, and other languages haven’t adopted these operators (even C++ itself had been moving away from << and >> by encouraging the use of std::print family), and the original meaning of those operators (bitwise shift) has absolutely nothing to do with I/O. In retrospect, the decision to overload << and >> for IOStreams is probably just meant to be a demonstration of the power of operator overloading, just like vector<bool>, deployed as an experiment. Well, we can only accept that STL can and has made many mistakes, many of them more severe than this, and move on with life.

In conclusion, with the freedom of operator overloading, you can really do extraordinary things, like C++20 Ranges’ use of |, and DSLs like Boost::Spirit. However, before wielding that power, be cautious and always follow those established guidelines:

Don’t do it. In 95% of the cases, you don’t need operator overloading and just want to show off. In the vast majority of cases, introducing a named regular function can express the meaning more clearly, give you more power (such as the possibility of having more arguments), and bring less confusion. So, unless you have very clear and robust motivation, refrain from overloading any operators.
Whenever the meaning of an operator is not obviously clear and undisputed, it should not be overloaded. For example, what should + between vectors mean? You may be tempted to say concatenation, with the precedence of string, but there is certainly no strong motivation or clear, established meaning on that operator (for example, it can also mean element-wise addition, just like what valarray and numpy.array does). Therefore, you shouldn’t overload it, even though it might be tempting. Instead, provide a named function, just like what STL eventually does.
Always stick to the operator’s well-known semantics. This is an extension of 2, but it’s so important that it merits mentioning again. Don’t use “surprise operators” that make a + b do subtraction; you will only confuse your users.
Always provide all out of a set of related operations. This is a more subtle one, but nonetheless, it is still essential to follow. If the user can do a < b, they will expect that they can do a > b. Even though the compiler does not forbid you to write a class that only supports <, you should always provide the full set, and make sure their behavior is consistent (i.e., a < b whenever b > a).

Just because you can do something doesn’t mean you should!

Transversing the Operator Zoo

Now that you know the basic syntax and guidelines of operator overloading, a natural question to ask is what operator we can overload. The first clarification here needed is that in C++, unlike some other languages, you cannot create new operators, so you cannot just write operator** and expect the compiler to suddenly start accepting a ** b. (Though, if you try really hard, you can make it work since a ** b is parsed as a * (*b). But again, you really shouldn’t rely on those kind of tricks. How hard is providing a pow()?)

That leaves the already-usable operators. A thing to mention here is that not all operators in the core language consist only of punctuations; examples are sizeof and typeid, which are technically unary operators since they can apply to objects. However, all of those “text” operators cannot be overloaded, so we will not consider them operators in this guide. However, there is one notable exception: swap. Even though swap is not even a keyword and doesn’t really have any meaning in the core language, it is used and relied on so heavily in the standard library that I will make an exception and consider it as an overloadable binary “operator” in this guide. We will see the reason for this declaration more clearly in its section.

Now that is resolved, among the remaining (“real”) operators, there are only four that cannot be overloaded: . (object member access), .* (object member access through pointers), :: (namespace access), and ?: (ternary/condition operator). Of those four “home-restricted”, their reasons are a little different. You obviously cannot overload :: due to the inability to pass a namespace name to a function, but there are not really any technical reasons for ?: not to be overloadable. The committee admitted that the only reason ?: is not overloadable is that it is the only ternary operator in the standard, and he does not want to cave an exception for the allowance of a three-parameter operator?: when all other operators are restricted to take one or two arguments (except (), and later [], but they are unique in more than this respect, as seen above). Recently, there have been some attempts to persuade WG21 (the ISO C++ standards committee) to allow operator?: in the context of natural SIMD conditionals that may benefit significantly from this operator.

As for . and .*, the story is much more interesting and revealing. The urge to overload operator., the dot operator, to finally allow for a perfect wrapper class that can forward every method to an inner object (perhaps a perfect strong type alias or a locking guard that provides a lock for each method invocation), had been overwhelming in the last 20 years, and multiple proposals had been put forward to allow exactly that. However, this “smart reference” (a la smart pointers) operator had been one of the most contentious topics in WG21 history due to issues like the clashing between the wrapper class’s own member function and operator., and whether a + b should invoke operator. on a if it is translated to a.operator+(b), and so on. In the end, the topic has been left unresolved on the platform for a few years now (the most recent attempt seems to be in 2016).

Committee shenanigans aside, except those four operators, C++ has allowed nearly every existing operator to be overloaded, including some surprising ones like -> (pointer member access), ->* (pointer member access through pointer), and , (yes, you can overload comma!). Still, remember the motto!

Just because you can do something doesn’t mean you should!

In total, C++ allows a staggering 39 different punctuation tokens to be overloaded, combined with non-punctuation overloadable, including operator T (converting operator), operator ""s (user-defined literal), operator co_await, four allocating operators, and swap (the only one in the list not using the operator keyword), there are a total of 47 overloadable operators defined in the standard. (Now you know why this guide is so long, huh?) Grouping by their arity, we can classify them as three different kinds, which dictates their overloading syntax in terms of number of arguments allowed:

Unary operators: +, -, *, &, ~ (bitwise not), !, ++, --, ->, co_await, operator T, operator ""s, new, new[], delete, delete[]
Binary operators: +, -, *, /, %, ^ (bitwise xor), &, |, &&, ||, <<, >>, =, +=, -=, *=, /=, %=, ^=, &=, |=, <<=, >>=, ==, !=, <, >, <=, >=, <=>, ,, ->*, swap
N-ary operators: () and [] (again special, these can take any number of arguments, including zero)

Take focus on the fact that some tokens appear in multiple listings! In some cases, the two forms are linked; for example, unary - is expected to do negation, so basically, -x is equivalent to 0 - x, which uses binary -. In other cases, the two forms are completely unrelated, such as unary * means pointer dereferencing, and binary * indicates multiplication. In the rest of the guide, to distinguish two forms, I will use u+ u- u* u& to refer to their unary forms, while b+ b- b* b& will refer to their binary forms.

Another subtlety is that two operators are secretly expanding inside the unary operator’s category! ++ and -- have two forms: prefix and postfix (all other unary operators are only prefixes). This means that you can make ++a and a++ do entirely different things! (Once again, you really shouldn’t; these are expected to be equivalent except for their return value. Remember the motto.) In the rest of the guide, if I want to distinguish them clearly, I will use ++p and --p to refer to their prefix forms and p++ and p-- to refer to their postfix forms. As for how do you distinguish them in code when both are unary? Read their section to find out!

(Finally, alert readers may point out that -> should be a binary operator since it is used like ptr->member(). This is not a mistake; welcome to the weird world of Arrow! Read its section to find out why it is a unary operator and a bizarre one at that.)

Basic Idioms

Before we embark on the journey to survey every single operator’s canonical forms and rules, we need to know about some general idioms that apply to nearly every operator overloading function.

Deducing This: A Retrospective and A Mistake Unfixed

For example, how exactly do you write a member operator function?

This may sound trivially nonsense, but it’s not. In C++23, a new way to write member functions, Deducing This, is introduced into the standard. Specifically, this feature allows you to explicitly write the normally-implicit object argument (aka this) in the argument list, just like Python’s self argument. The syntax is to prepend this on the first argument:

struct S
{
    int value;
    void fun(int r) { value = r; } // normal member
    void fun2(this const S& self, int r) { self.value = r; } // deducing this
};

S s;
s.fun(4);
s.fun2(5); // usage is the same

Some non-obvious details regarding those kinds of “deducing this” member functions need to be resolved. First of all, implicit and explicit access to this is disabled in those functions; you cannot just write value or write this->value and expect it to work. Instead, you need to access the members via self (notice that this name is just an argument name and can be anything, not just self). Secondly, I actually sorta lied when saying Deducing This is a new way of writing member functions. The best way to understand this is to again think DT as a syntactic sugar for an equivalent function by deleting this and prepending static:

struct S
{
    void fun(this const S& self, int r);
    // equivalent to:
    static void fun(const S& self, int r);
};

Then, the compiler simply transforms s.fun(5) to a call of S::fun(s, 5) whenever the overload resolution selects a DT function. This makes sense since we don’t have a this pointer inside the function, making it ABI equivalent to a static function with better performance.

Now, what are the benefits of using DT, you may ask? At first glance, this new form just adds more keystrokes and reduces the convenience of implicit this. However, there are three main advantages of using DT.

First of all, since DT members are just equivalent to a static member function, there is no rule whatsoever as to what the first argument’s type must be. For normal member functions, the implicit object argument’s type can be S&, S&&, const S&, or const S&& depending on the cv- and ref-qualifier at the end of the declaration, but it must be a reference. There is no such requirement on DT member functions:

struct S
{
    void fun(); // implicit object argument is S& (sorta, see below)
    void fun2() const; // implicit object argument is const S&

    void fun3(this S&); // equivalent (sorta, see below) to fun
    void fun4(this const S&); // equivalent to fun2

    void fun5(this S); // pass by value! impossible to write for normal members
};

Passing the implicit object by value has many benefits, including better performance due to avoiding implicit pointer access when writing members for small classes like string_view that fits in registers and the possibility of a simple sorted()-like function that returns a modified version of self without modifying in-place.

But more importantly, there is no reason why a (static or not) member function cannot be a template. What makes DT special? Its first argument can also be templated!

struct S
{
    T value;
    T& fun() { return value; }
    const T& fun() const { return value; } // common overload set to serve both kinds of this

    template<typename U>
    auto& fun(this U&& self) { return self.value; } // only need to write once!
};

Using a forwarding reference (sometimes in conjunction with std::forward[_like]), we can collapse the two or four duplicate overloads needed to handle different const-ness into one templated member, and the right overload will be instantiated when needed.

The second important advantage of DT is the possibility of exposing the this pointer in a lambda. Since lambdas are basically syntactic sugars for anonymous classes with an operator() overload, we cannot normally use this to refer to that anonymous class because of this-related captures. However, with DT syntax, we now have a way to refer to the lambda object inside itself:

auto fac = [](this auto fac, int n)
{ return n <= 1 ? 1 : n * fac(n - 1); }
fac(5); // 120

Besides the obvious recursive lambda, this also enables us to write a better overloading lambda wrapper. See the original proposal for details.

The third advantage is not actually mentioned in the proposal at all and is a very less-known fact of normal member functions in C++. It is so less known that the standard itself made mistakes in this aspect, and this advantage is actually very relevant to why using DT to overload operators is a good idea. What is the weird quirk, you may ask? Basically, the above text (and the standard)’s reference to the “normal, non-const member function’s implicit object argument is of type S&” is a lie. Only lvalues of type S will be accepted for a normal function taking an S& argument. However, for normal non-const member functions, both lvalue and rvalues are accepted!

struct S { void fun(); };
void fun2(S&);

int main()
{
    S s;
    s.fun(); // okay
    fun2(s); // okay
    S{}.fun(); // prvalue, okay
    fun2(S{}); // prvalue, error!
}

You see, the implicit object argument of non-const member functions is actually the first instance of a “universal reference” in C++ standard that can accept both lvalues and rvalues, introduced way before C++11 forwarding references are a thing. This quirk does not apply to const member functions because a normal function with const S& arguments can already accept both lvalues and rvalues, making them truly equivalent.

What does this quirk have to do with operator overloading? Remember, operator functions are just normal functions with a special name, so all the properties of a regular member function apply. This has two important implications:

Asymmetry of Two Forms: In nearly all regards, the compiler treats an operator’s member and non-member forms equivalently; a + b will search and make overload resolutions with both forms and rewrite accordingly. However, this quirk means that if you write operator+= as a member (without defense, see below), it will accept rvalues as the left-hand operand, making S{} += 2 valid. That statement will be invalid if you implement operator+= as a non-member.
Rvalue Modification: This might be somewhat obvious since S{} += 2, or in general, modifying an rvalue, which is most likely a temporary expression, is usually not a great idea. The modification result is most likely discarded, so write S{} + 2 is probably clearer. The standard library itself made this mistake: all of its operator=s are member functions without defense, so nonsense expressions like std::string{} = std::string{} are actually valid.

You may wonder who actually writes expressions like that, modifying clearly temporary values. Well, maybe not directly, but you should remember that misspelling == as = is a very common mistake:

std::optional<int> getOptional();
int getInt();

if (getOptional() = 2) // oops, meant to be ==
if (getInt() = 2) // protected! compile error

Built-in types like int do not have overloaded operators, so operator= on ints does not accept rvalues as LHS, and the above mistake is actually protected. However, regarding std::optional (or any other STL types), even though getOptional() returns a prvalue, you can still write an assignment like that, and all major compilers compile successfully, albeit with a warning. (Apparently, MSVC does not even warn about this…)

Now, a defense against this quirk exists, which is the ref-qualifier feature introduced in C++11. This feature allows you to append & or && after a member function to constraint whether the function only accepts lvalue this or rvalue this:

struct S
{
    void fun();
    void fun2() &;
    void fun3() &&;
};

S getS();

int main()
{
    S s;
    s.fun(); // okay
    s.fun2(); // lvalue, okay
    s.fun3(); // error!

    getS().fun(); // okay (quirk)
    getS().fun2(); // error! (good)
    getS().fun3(); // rvalue, okay
}

This not only gives you a way to express a member function with implicit object argument as S&&, but appending & also gives you feature parity with a normal S& argument. Now, struct S { void fun() &; }; is indeed equivalent to void fun(S&);, minus calling syntax. (However, now struct S { void fun() const &; }; is again not equivalent to void fun(const S&);, instead being a non-expressible “const true lvalue reference” that only accepts lvalue. Isn’t C++ fantastic? 😜)

Applying this feature to operator overloading, we can now guard against modifying rvalues, and achieving symmetry:

struct S
{
    S& operator=(int) &; // <- notice the &
};
S s;
S getS();
s = 2; // okay
getS() = 2; // error, good

Unfortunately, ref-qualifiers is probably one of the least known features of C++11, with little to no adoption both inside and outside the STL. There had been a proposal in the C++11 cycle requesting WG21 to change all existing standard library types to use an operator= with & qualifier and eventually modify the automatic generation rules to force that as default. However, due to the sheer amount of breakage this may cause, without any surprise, that proposal is not accepted. To maintain consistency, new library types introduced after C++11 still haven’t adopted any operator= with a qualifier, resulting in our unsatisfactory contemporary status.

But now, we may have a cure for that disease: Deducing This. One of the main reasons &-qualified members had not seen great adoption is due to its asymmetry: you have to remember to add & for non-const members, but also remember not to add & for const members to achieve feature parity. However, DT has no such asymmetry: due to its equivalence with static functions, void fun(this S&) is, so obviously, equivalent to normal void fun(S&), and void fun(this const S&) is also just equivalent to normal void fun(const S&). Even better, since DT uses normal function declarations syntax, there is literally no way to write the quirky “universal reference” or “const true lvalue reference” in DT members, so there are no bad defaults here; you have to write out the type physically. By simply writing all (non-virtual, for now) members (including operator overloads) in DT form, you already achieved the rvalue modification prevention goal without intentionally doing anything!

So, in conclusion, for modifying operators that probably should be written as non-const member functions (see below section for why), the canonical form is to either write it in Deducing This form or to append the & qualifier. This way, both symmetry and prevention of rvalue modification can be achieved.

struct S
{
    S& operator=(this S&, const S&); // canonical and preferred
    S& operator=(const S&) &; // canonical
    S& operator=(const S&); // not recommended
};

(Of course, if your operator does want to allow modification on rvalues, you can write it as a normal member (or preferably a DT member with forwarding reference); maybe the Builder pattern’s operator= can be one example.)

Hidden Friends and the Barton-Nackman Trick

Now that we know the canonical forms for member function implementation of operator overloading, what about the non-member implementation? There, no symmetry problem occurs since both arguments are treated equally. However, another problem arose, necessitating the introduction of another commonly used implementation technique of non-member functions: the Hidden Friend Idiom.

To understand hidden friends, we first must understand a friend declaration. Traditionally, friend declarations are used to intentionally loosen a class’s encapsulation in a controlled manner. For example, you may have a CRTP base class that you want to access some private method to aid implementation, which you do not want to expose to the outside world:

template<typename Derived>
struct provide_work
{
    void work() { static_cast<Derived*>(this)->doWork(); /* do some logging */ }
};

struct concrete_class : private provide_work<concrete_class>
{
    friend class provide_work<concrete_class>;
private:
    void doWork();
};

doWork() is an internal function without logging, so you may not want to expose it to the outside world. However, since the CRTP base class usually uses private inheritance due to the nature of the composition, that cast inside work() doesn’t actually work unless you make it see the inheritance through a friend declaration.

[!TIP] This example works much better if you use Deducing This, in which you simply write void work(this const auto&) and don’t worry about friends anymore.) friend declarations can apply to both classes (like above) and non-member functions (like friend void fun();), and in both cases, the mentioned class/function will gain access to the private members of concrete_class.

However, in modern C++, friend declarations are increasingly less necessary due to the focus on reducing coupling between classes and also strengthening encapsulation. Those relationships are usually much better expressed by utilizing a class’s public API, maybe through a hidden base class. However, another (unintended?) use of friend declarations has risen in popularity in recent years and has gradually become one of the most important use cases of the friend keyword: the Hidden Friend Idiom.

Now, what is a hidden friend? Basically, when using friend to befriend a function, simply put that function’s definition right after the friend declaration (define the function in-line), and you get a hidden friend.

struct S
{
    S(int);
    friend void fun(S s) // hidden friend!
    {
        // implement fun(), can use private parts of S here
    }
};
S s;
fun(s); // okay
fun(2); // error!
fun(S(2)); // okay
::fun(s); // error!

A hidden friend like this is still a non-member function, albeit residing inside the definition of a class. However, precisely because the function only has a declaration inside a class scope, it is hidden against all normal lookup methods. Thus, it cannot be found from normal qualified lookup (like ::fun(s)).

However, how is fun(s) valid then? This is because hidden friends can only be found via one special rule in the lookup family: Argument-Dependent Lookup (ADL). ADL is an exception in the unqualified lookup phase that is actually invented specifically to convenience operator overloading. Basically, for ADL to happen, three conditions must be met:

The lookup performed must be an unqualified lookup (without namespace prefix); ::fun(s) or N::fun(s) will not invoke ADL.
Normal unqualified lookup must only find functions. This precludes the following scenario: (cannot “overload” function with non-function variables)

namespace N { struct S {}; void fun(S); template<typename> struct Mem; }
int fun;
N::S s;
fun(s); // no ADL here, hard error

Finally, at least one argument must be of (possibly a pointer or reference to) a class type.

When all the conditions are met, ADL specifies that a list of associated entities is compiled for each (class type or pointer to or reference to a class type) argument to the function. The rules for finding associated entities are a bit complex, but in general, the following are included:

If a pointer or reference, associated entities of the referred type
If a class type, then the class itself, all direct or indirect base classes, and all nested classes if the class is a nested type.
In addition, if a templated class type, associated entities of all type parameters

This is not the full list of rules, but it is sufficient for this guide’s purpose. Notice especially that the second rule is not recursive: if N::S derives from M::P, then M is not an associated namespace for s. However, M is an associated namespace for N::Mem<M::P>.

After finding all the associated entities, the associated namespace is constructed by finding the innermost enclosing namespace for each entity. Then, ADL will search all the associated namespaces, as well as all hidden friends within the associated entities. What this all means is that ADL will find two more kinds of “distant” function declarations not found by normal unqualified lookup:

All function declarations residing in the same namespace as one of the associated entities; and
All the hidden friends in associated entities

namespace M
{
    struct S
    {
        friend void fun(S);
    };
    void fun2(S);
}
N::S s;
fun(s); // okay, #2
fun2(s); // okay, #1

Alerted readers may ask, why is ADL a special rule invented specifically for operator overloading? Well, you see, again, operator functions are just normal functions with special names, and they can be found by ADL, too. This is especially suitable for operators because we almost never call them by the normal function syntax but instead choose to write a + b, which always tries to find operator+ through unqualified lookup, so all the namespace-level and hidden friend operator+ for a and b will be found. This is specifically to enable people to write operator functions inside the class’s own scope or enclosing namespace without polluting the global namespace. In fact, in the early days of C++ standardization, ADL only occurred when calling the operator through that syntactic sugar and was only extended to all functions in 1996, very late in the standardization cycle.

Now we know when hidden friends are found, why are they useful in terms of operator overloading? Writing operator functions as hidden friends at least have three advantages. First, hidden friends greatly reduce the overload set, thus delivering significantly better compiling time and (most importantly) diagnostics. You see, if you write a normal non-member operator+, it will get picked up every time everyone writes a + b, no matter what type a or b has. Hidden friends can only be found via ADL, so at least one of a or b must have a relevant type to your operator+’s enclosing class. Otherwise, it will not be shown in the overload set (which the compiler often prints in full whenever some a + b goes wrong).

Secondly, hidden friends reside physically within the class scope. Yes, this is an advantage because operators are most definitely deeply tied to a class’s semantics and should form a class’s public API. If you define a non-member operator just at namespace scope, it may be separated arbitrarily from the class definition, thus making it hard to find and harder to link to the class. Also, a side note is that hidden friends also contribute to the feature-parity between non-members and member forms of operator overloading since hidden friends are still friends and can access the class’s private parts. This may arguably be a good or bad thing since many operators can be implemented fully from public API, and making more friends is generally seen as weakening the encapsulation. However, since member operator functions can (obviously) already access the private parts, I would argue that all operators of a class should be “seen as” members and should have equal access.

Finally, one of the most important advantages of using hidden friends for operator functions, and the trick that makes it indispensable in operator overloading, is the fact that hidden friends will enable the use of the Barton-Nackman trick. If your class is actually templated (say, overloading operator+ for Rational<T>), then there is a very important distinction between hidden friends and ordinary non-members:

template<typename T>
struct Rational
{
    Rational(T); // implicit conversion from T

    // hidden friend
    friend Rational operator+(const Rational&, const Rational&);
};

// normal non-member
template<typename T>
Rational<T> operator+(const Rational<T>&, const Rational<T>&);

Have you found the distinction? The hidden friend is actually not a template function! This is a boon granted by being inside the Rationl<T> class scope: you don’t need to template the operator to refer to any kind of Rational; you only have to implement for the current Rational<T> (can be shortened to simply Rational inside the class scope, as seen above). And each invocation of r1 + r2 will synthesize a non-template operator+ from r1 and r2’s class scope.

This distinction had profound implications for the usability of the operator: templated functions only do substitution; they never consider any kind of casting.

Rational<int> r1, r2;
r1 + r2; // okay for both form
r1 + 2; // okay for hidden friend, error (!) for non-member

Why does r1 + 2 fail for a non-member declaration? Because it is a template, the compiler tries to match 2 (aka int) against const Rational<T>& for the second argument and finds that no T can satisfy this equivalence; thus, the declaration is discarded. In the hidden friend case, since operator+ is not a template, no substitution is needed; the compiler knows that it must try to convert 2 to some object of Rational<int>, so the constructor is selected.

This trick, the fact that hidden friends can strip away the template-ness of operators, is known as the Barton-Nackman trick and is the premier reason why operator overloading for templated classes is usually always done in member form or hidden friend form. (Though the most common knowledge of this trick probably stems from Item 46 of the famous Effective C++ book, where the same example of Rational<T> is given.)

However, the other two advantages remain even for non-templated classes. This is why I recommend in this guide that all operator overloading be done in member form or hidden friend form if a non-member is preferred. It leads to better compiling time, better diagnostics, better grouping, and API documentation, and enables conversion in templates. What’s there not to love?

You Must Type It Three Times: SFINAE Woes

Now, we venture into some more advanced topics, like the concept of SFINAE-friendly, which you should consider for each of your overloaded operators.

[!IMPORTANT] The answer to "Should I make my operator SFINAE-friendly?" is no 99% of the time, both because making it friendly is a bit complex and the advantage is only applicable in a very specific group of types. Most users don’t really need to care about this section. If you don’t know what SFINAE is at all, then you don’t need to read this section, as it will not really affect you.

So, what is SFINAE-friendly? This term refers to the fact that your type perfectly forwards SFINAE-ness. For a friendlier example, let’s again consider the example of Rational<T>. But this time, we will assume that there is a widely adopted concept multipliable that tests if your type is multipliable simply by testing if t * u is valid; and someone had written a function to choose different algorithm based on the multipliability of your type.

template<typename T>
concept multipliable = requires (T t, T u) { t * u; };

template<multipliable T>
T fun(T t) { /* some specific impl */ return t * t; }

template<typename T>
T fun(T t) { /* some general impl */ return t; }

Now, assume that there is some wrapper on ints that only allows addition, not multiplication (perhaps because there is some invariant that it must hold, and it may require too much effort to maintain in multiplication):

template<typename T>
struct Rational
{
    T n, d;
    friend Rational operator+(const Rational&, const Rational&) { /* ... */ }
    friend Rational operator*(const Rational& lhs, const Rational& rhs)
    {
        return Rational{lhs.n * rhs.n, lhs.d * rhs.d};
    }
};

struct Number
{
    int value;
    friend Number operator+(Number, Number);
    // no operator* defined
};

Now, on the surface, this is a very natural implementation of operator*, right? It uses hidden friends as recommended (though everything below applied to regular non-members and members, too) and simply returns an object with the calculated multiplication result. However, take a look at the following result! (Compiler Explorer)

int main()
{
    Rational<int> ri{1, 2};
    ri + ri; // good
    ri * ri; // good
    Rational<Number> rn{Number{3}, Number{4}};
    rn + rn; // good, rn * rn will obviously error out
    static_assert(multipliable<Rational<int>>); // good
    static_assert(!multipliable<Number>); // good
    static_assert(multipliable<Rational<Number>>); // ???
    fun(ri); // good, returns ri * ri
    fun(Number{3}); // good, returns Number{3} itself
    fun(rn); // hard error!
}

Why is Rational<Number> multipliable? And why is fun(rn) a hard error?

Actually, the answer to the second question directly results from the answer to the first question. It is because multipliable<Rational<Number>> is satisfied, such that the specific overload for fun is selected, and evaluating t * t inside the body results in a hard error. So why is multipliable satisfied in the first place? The answer is that Rational<T>’s operator* is not SFINAE-friendly.

For a function to be SFINAE-friendly, it must perfectly forward the SFINAE-ness, meaning that when lhs.n * rhs.n is invalid; the entire operator* declaration should be SFINAE-away. However, as currently declared, operator* for Rational<T> is always present in the overload set, and simply testing for the validness of rn * rn will always succeed since you are only asking if operator* exists. However, calling that expression instantiated the operator and the lhs.n * rhs.n line simply results in a hard error. Then how do we make it SFINAE-friendly? The solution is to forward SFINAE-ness by adding a requires clause:

template<typename T>
struct Rational
{
    // ...
    friend Rational operator*(const Rational& lhs, const Rational& rhs)
    requires requires (T t, T u) { t * u; }
    {
        return Rational{lhs.n * rhs.n, lhs.d * rhs.d};
    }
};
// Before C++20, this is typically done by
// friend auto operator*(const Rational& lhs, const Rational& rhs) -> decltype(lhs.n * rhs.n, void(), Rational{})
// simply doing a SFINAE test in the return type

(Or, in this case, requires multipliable<T> will do it.) Now, since operator* is only present if and only if t * u is valid, in the case of Rational<Number>, the operator* is simply not present in the overload set, and multipliable will now report false as rn * rn is no longer valid.

So, when is this technique actually useful? Actually, SFINAE-friendliness is only required in very limited cases, mostly dealing with TMP code. You only need to make your operator SFINAE-friendly if you actively need multipliable to detect your operator* status correctly; in most cases, there is no such concept to deal with, or the user is not expecting Rational<Number> to actually report its status transparently. Coupled with the fact that making functions SFINAE-friendly requires some non-trivial and non-obvious TMP work like the above requires clause, it is generally not recommended to just slap those kinds of requirements on the operators. Only if you are sure that your operator absolutely needs SFINAE-friendliness do you then do it.

One example of those kinds of needs in the STL is in the context of C++20 Ranges. A very important concept for any range is the range properties, like sized_range<R>. This concept basically tells you if your range is sized (i.e., can report its size in O(1) time) and is achieved by simply detecting if ranges::size(r) is valid (and also provides an opt-out in the form of disable_sized_range<R>). Then, each range adaptor like views::transform in the standard will then only provide the size() member function if and only if the underlying range is sized, making sized_range<transform_view<R, F>> always equal to sized_range<R>. This is a critical requirement for those adaptors to calculate/forward the range properties correctly, so filter_view::size() is made SFINAE-friendly.

SFINAE-friendly also has some interesting implications in the context of perfect forwarding call wrappers, which will be discussed in the section for overloading operator(). Otherwise, this guide will not mention SFINAE-friendly again, and all canonical forms will assume that friendliness is not required. Please append the requires clause as needed.

Now that we know about some general idioms that apply to all operators, we went on to some choices that apply to some specific operators and their implications. Then, a classification of overloadable operators will be present, and the rest of the guide will focus on overloading specific operators.

Choices and Classification

Member or Hidden Friend? A Difficult Choice

Now that we know member operator functions should either be implemented via Deducing This or (sometimes) have a ref-qualifier attached, and non-member operator functions should nearly always be implemented via Hidden Friends, the question remains: Which form should we choose? Member or non-member (hidden friends)?

For some of the overloadable operators, the standard has made this choice for us:

Operators (), [], ->, =, and operator T (conversion) must be overloaded via the member form.
Operator swap and operator ""s (UDL) must be overloaded via the non-member form.
When (mis)used as Input/Output operators, operators << and >> must be overloaded via the non-member form.

For all other scenarios, there is no restriction: you can choose freely between the member form and the non-member form. However, again, there exists a canonical form (a custom) for which operators should be members, as a non-member operator+= just seems weird, while a member operator+ seems equally weird.

In general, the rule of thumb here is that whenever the operator is unary, or binary and needs to modify its left-hand operand, it should be overloaded as a member; otherwise (binary and non-modifying), it should be a non-member. Notice here that this rule technically says nothing — there is no regulation requiring your operator+= to modify the left-hand operand. However, again, remember the motto. Your operators should all be following what the builtin ones do; += on ints (and other builtin types) performs the operation a = a + b, and thus you should follow that convention.

The operators that are customarily left-hand modifying, and thus nearly always overloaded as members include:

All the compound assignment operator @=, where @ is one of + - * / % & | ^ << >>. These are the most obvious bunch, since operator= had already been required to be a member, and those are closely tied to = since you should always make a @= b and a = a @ b equivalent.
The increment and decrement operator ++ and -- (both forms). These also modify their arguments, and since ++a is equivalent to a += 1 (at least I hope you make it so), they belong in the same category.
All the unary operators. These include u+, u-, u*, u&, !, ~, and co_await. Although those do not (usually) modify their arguments, the unary-ness makes them tied closely to the argument and thus suitable for being a member.

All other operators should be overloaded as non-members. The reasoning for the existence of those rules is that left-modifying operators are naturally asymmetrical towards their two arguments and also tie more closely to the LHS since it needs to modify the argument. Therefore, they should use an asymmetrical syntax, namely overload as a member function. Other binary, non-modifying operators often treat their arguments equally (there are exceptions to this, like ->*) and expect the same treatment (conversion, etc.) to happen to both operators, which member functions cannot provide. As for why non-modifying unary operators are recommended to members, too, that’s probably just a customary thing since non-member operator* just seems too weird.

The Big Classification

Finally, after all the preludes, the general introduction stops here. The rest of the guide will be tailored to each operator, as their similarities and general principles have already been introduced, and the rest of the text will introduce each operator’s intricacies and conventions in detail. However, before we can start our journey for real, we still need to classify all the operators into several groups since each operator group still has some generality that can be introduced together (such as compound assignment operators @= are practically following the same principle, even though @ can be different).

There are many different ways to classify operators:

By arity:

Unary: u+, u-, …
Binary: b+, b-, …
N-ary: (), []
N/A (Can’t talk about arity): Conversion operator T (technically unary, but too different to count) and UDL operator ""s

By membership-ness:

Required to be members: (), [], ->, =, operator T (conversion)
Usually members: u*, +=, …
Usually non-members: b+, b-, …
Required to be non-members: swap, <<, >> (as I/O), operator ""s (UDL)

However, in this guide, the operators will be classified through how often you should overload them (ordered from most frequently to least):

The Good Four: =, <=>, ==, swap. Those are the only operators that you should consider overloading for all classes. All other operators below this category are only meant to be overloaded for specialized kinds of classes, not universally.

[!IMPORTANT] This does not mean that you should always overload these operators since the first rule for operator overloading is still Don’t Do It!. Only comparatively, those are the most commonly overloaded operators.

The Functors: (). The call operator is so special and common that it deserves its own group.
The Pointer and Iterator: u*, ->, ->*, [], ++, and -- (all forms). You should consider overloading these operators only for pointer-like or iterator-like classes. Notice that increment and decrement appear twice; that’s because they have completely different meanings here and below.
UDLs: operator ""s. This is very interesting and sufficiently different from all other operators that it deserves its own group. Definitely take a read, though; it may be more commonly useable than you think!
The Arithmetic: These are the operators you should consider overloading only for number-like classes. Multiple subgroups exist: (still ordered by often-ness)
- Normal Arithmetic: b+, b-, b*, /, %. These should be considered for most number-like classes.
- Weirdos: u+ and u-. Whenever b+ and b- are overloaded, these should be, too, but they are still weird.
- Increment/Decrement: ++, -- (all forms). In general, most classes that are closed on b+ and b- should consider these.
- Bitwise Arithmetic: |, b&, ~, >>, <<. These should only be considered for number-like classes for which a bitwise interface makes sense.
Coroutine: co_await. This is also special and deserves its own group. However, you, as a user, probably never need to overload this operator.
The Bad Nine: u&, &&, ||, ,, all new/delete forms, and operator T (conversion). Here lies the evil ones. Under normal circumstances, you should never overload these operators at all, no matter what kind of class you are dealing with.
Irrelevant: <, >, <=, >=, !=, !. These are the lowest category, however, not because they are evil or anything. It’s just that overloading those operators is completely pointless, and you should not bother with any of those since it doesn’t matter at all in functionality.

The rest of the guide will follow this classification (not in order, click the above links to jump), so please just jump to the corresponding operator group you want to learn about. Let the journey in the operator zoo finally begin!

The Good Four

Simple Assignment: `operator=`

TLDR

// canonical forms
T& operator=(this T&, const T&); // best
T& operator=(const T&) &; // also okay
T& operator=(this T&, T&&) noexcept; // best
T& operator=(T&&) & noexcept; // also okay

// forms that are useful in specific circumstances
T& operator=(this T&, T) noexcept;
T& operator=(T) & noexcept;
template<typename U>
T& operator=(this T&, /* const U& or const T<U>& or ... */);

The Basics

Ah, =, the most commonly overloaded operator, and also the operator with one of the most complex stories, guidelines, and mechanisms behind it. It is so special, yet so commonplace, presented in nearly every single class that many people do not even realize its complexity. This operator is tied so deeply into value semantics, one of the core characteristics of C++, such that understanding = is probably all they need to know about operator overloading for 90% of the people. In fact, operator= is the only operator that the compiler will automatically synthesize for you, even without you writing anything! Their importance can be seen in this special treatment.

One thing to be clear here: even though operator= is a binary operator and has to be overloaded in the member form, there are absolutely no restrictions on its argument type and return type; you can write Y X::operator=(Z) const volatile && and the compiler will not say anything. However, if you write some specific forms of operator= overloads, then the compiler will treat them specially. Those special forms are: (assuming we are overloading operator= inside class X)

If the argument type is X or cv X& (where cv is any combination of const and volatile), then this overload is a copy assignment operator.
If the argument type is cv X&&, then this overload is a move assignment operator.

[!NOTE] There are no requirements on the return type, and a class can have more than one copy/move assignment operator since multiple forms are possible, and they can be overloaded.

The importance of these two operators is shown in their names: whenever a copy assignment happens, one copy assignment operator will be invoked; whenever a move assignment happens, one move assignment operator will be invoked. You may think this is obvious nonsense, but beware: not all use of = triggers operator=!

A a;
A a2 = a; // NOT a copy assignment
a2 = a; // a copy assignment
A a3 = std::move(a); // NOT a move assignment
a3 = std::move(a); // a move assignment
const A ca;
a3 = std::move(ca); // (usually) NOT a move assignment

The reason for this distinction is the liberal allowance of =’s appearance in copy initialization; the syntax T some_obj = other and T some_obj = {other} (and array versions of these) both invoke a constructor, not an operator=. Similarly, T some_obj = {a, b, c} is a copy-list-initialization, and also do not invoke an operator=. Such distinction is unfortunate; fortunately, these are all the special rules with regards to =, and all other uses of = actually do invoke a suitable operator= following the ordinary overload resolution rules. From the above example, we can see that operator= is invoked whenever you want to copy/move the contents of one object into another preexisting object, hence the name of those forms. Since a copy assignment operator, by definition, copies the contents of another object into this one, it does not modify the other object and does modify the this object. Thus, its parameter type should be const T&, and its object parameter type should be T&, thus leading to the two canonical forms shown above. (See the above sections for why we use & as the ref-qualifier instead of omitting it, as seen in most tutorials you may have seen before.)

This topic leads to another trap regarding operator=: std::move does not actually move anything, which highlights how poor a name that function has. In fact, the only thing std::move does is a cast to rvalue, which on the surface seems to have nothing to do with move at all! In fact, the term “move assignment operator” is, in reality, just a custom; we are assuming rvalue means short-liveness, and thus an operator= that only accepts rvalue operators can assume that its parameter will not be used later (either because of its lifetime is actually short, or because as a custom the caller use rvalues to signal they will not use the parameter anymore), and thus can steal the value of the parameter instead of copying it. Such an assumption often leads to much better performance compared to copying:

// Example vector implementation
template<typename T>
class vector
{
private:
    T* data;
    size_t size, capacity; // actually, the most common implementation is 3 pointers

public:
    /* ... */
    vector& operator=(this vector& self, vector&& other) noexcept
    {
        /* ... destroy self's data array ... */
        self.data = other.data;
        self.size = other.size;
        self.capacity = other.capacity;
    }
};

Here, apart from the destruction of self’s pointer, all the move assignment operator has to do is copy some pointer and integer values, thus achieving O(1) effectiveness, which is inherently not possible for copying.

With this knowledge, we can understand why the above a3 = std::move(ca) is not a move assignment operation. std::move cast the right-hand expression to be of type const A&&, which is an rvalue but is also const, which prohibits the canonical move assignment operator to be called. The reason that the canonical version used non-const rvalue references is that it needs to steal the value from other, thus needing to modify it. In such cases, the call will be silently degrading to a copy assignment by the overload resolution rules (const A&& cannot be bound to A&&, but can be bound to const A&, as const-ness cannot be silently stripped), thus often resulting in worse performance. (This is also a good argument against const all the things.)

However, astute readers will throw a question at me after reading the above paragraph: using rvalues to mean short-liveness is just a custom, not a rule! The language has no enforcement on this custom, which means that the signature of the move assignment is a lie! Indeed, value category is not lifetime. It is true that temporary values are often rvalues, but often is not always, and the reverse is also not true:

void fun(std::string s)
{
    std::string s1 = "Hello", s2;
    s2 = std::move(s1); // (1) Actually long-lived rvalues
    std::println("{}", s1); // OOPS, read from moved-from objects

    s2 = s; // (2) Actually short-lived lvalues
    // OOPS, a copy, even though s will be discarded after the next line anyway
    std::println("{}", s2);
}

The (1) case is unfortunate in that an rvalue actually referenced a long-lived object (s1) that is used after the move assignment, resulting in reading from a moved-from object that gets an unspecified (but valid) value. Such a read is potentially dangerous if the logic after still expects s1 to retain its original value. The (2) case is also unfortunate, in that even though s is not used after the assignment and will end its lifetime very soon, since it is a lvalue, the assignment must perform a copy, even though a move would suffice. Both cases exposed that rvalue actually has nothing to do with short-liveness. Thus, the signature of the move assignment will indeed cause inconvenience in some cases.

A full solution to those two cases requires connecting lifetime with value categories more firmly in C++. For example, for (1), the solution will be to introduce destructive moves, where moved-from objects cannot be used at all, thus preventing the danger. For (2), the solution would be to treat the definite last use of variables as rvalues automatically, thus eliminating this potential inefficiency. In fact, the language is already slowly moving in this direction in a small but crucial case: the return statement.

std::string fun()
{
    std::string s;
    return s; // If no NRVO occurs, then a guaranteed move construction here; no copy!
}

Even though s is definitely a lvalue here, the language requires that such a direct return statement for local variables must treat its argument as an rvalue since C++23, since this is definitely the last use of the local variable. This is called “implicit move” and has been an optimization well-known to the compilers since C++11. However, such treatment has not expanded to other definite last uses (yet?), and even if it does, cases where the variable is not the last use but its value is not needed anymore (such as dead stores) will still not be optimized, demonstrating the weakness in the rvalue abstraction.

The (1) case is more difficult and dangerous since it caused unexpected behavior instead of just a performance reduction. For this reason, the language introduced std::move to explicitly signal the creation of rvalues, and to inform the writer that the variable’s value better not be used after this statement. This custom is not enforced, nor is it perfect, but that’s what we are now, and the status quo is unlikely to change anymore. Just beware of this weak equality between rvalue and short-liveness and move on with life, then.

Automatic Generation Rules: The Rule of Three, The Rule of Five, and The Rule of Zero

Back on topic. I said earlier that operator= is the only operator that will be generated by the compiler even if you don’t write anything. A natural question arises: when will the compiler generate them, and what does the generated version do?

The second question is easier to answer:

If the class in question is a normal class, the generated version of operator= will do the same operation memberwise.
If the class in question is a union, the generated version of operator= will do a copy of the object representation (in other words, copy all the bytes of the object, as if by std::memmove).

There are two nuances worth pointing out with this seemingly simple description. First, the definition of member is not just data members but subobjects. The difference between those two terms is that the latter also includes the direct bases of a class since, in the C++ object representation, the base subobjects come first before any data members. (Astute readers may ask about what will happen for virtual indirect bases that are inherited multiple times, as they are guaranteed to only appear once in the object representation, but their construction requires coordination from even indirect subclasses. The answer is simple: whether their subobjects are assigned one time or multiple times in the implementation of the implicitly-defined assignment operators is unspecified. Sigh) The term “subobjects” also refers to each element of an array member and not the array itself, which guarantees the correct generation of default copy/move assignment for array members since built-in array types do not have an assignment operator at all.

Another nuance with regards to unions is what is not said in the second bulletin: The only thing the automatically generated operator=s for a union will do is copy the bytes; notably, no calls to the data members’ operator= will happen! This is obviously a problem since non-trivial data members are non-trivial because their operator= does different things than just copying the bytes. For instance, std::vector’s copy assignment operator needs to allocate a new buffer in case the current buffer is not large enough, copy over the elements, and adjust the size/capacity pointer/member. If only the bytes are copied over, two std::vectors will refer to the same memory, which will result in a guaranteed double-deletion. It is for this reason that we say C++ unions are unsafe, and you need some auxiliary structure to keep track of the active member and overload the operator=s to call the appropriate underlying operator= is a necessity unless you only have trivial members. (Or, better yet, use a safe wrapper that handles these chores for you, such as std::variant.)

The questions of when will the compiler generate operator=s for you are a lot more complicated to answer. Obviously, if you are not writing a copy/move assignment operator, the compiler will generate one for you, right? Wrong! The rule for when the copy and move assignment operators are generated are encoded in the so-called Rule of Three and Rule of Five, where the former applies to C++98/03, and the latter applies to C++11 and later:

Rule of Three: If you declare any of a copy constructor, copy assignment operator, or destructor, you should declare all three
Rule of Five: If you declare any of a copy constructor, move constructor, copy assignment operator, move assignment operator, or destructor, you should declare all five

Now, the rules aren’t that simple: Declaring a copy constructor won’t affect the generation of a copy assignment operator (and vice versa), and declaring a destructor won’t affect the generation of a copy constructor or a copy assignment operator. However, for all other relationships (basically, those interacting with move operations, which C++11 can fix right away), the Rule of Five does apply, and the above irregularities are actually deprecated behavior. Therefore, personally, I recommend just treating the rule as-if by Rule of Five: if you declare any one of the five special member functions, all five will not be automatically generated. It is not the truth, but close enough to be a guideline to follow.

The reasoning behind Rule of Five and C++11’s forceful enforcement of it is due to an acronym commonly thrown around by C++ enthusiasts: RAII or Resource Acquisition Is Initialization. Now, this acronym is actually wrong; the behavior/principle that people actually mean when they say RAII is Resource Release Is Destruction, but RRID is not a good acronym, so we came up with RAII. The driving principle behind this idea is to treat C++ destructors as resource releasers:

struct LockGuard
{
    std::mutex m;
    ~LockGuard() { m.unlock(); }
};

{
    std::mutex m; m.lock();
    LockGuard lk{m};
    /* ... no matter what happens here, even under an exception, the mutex is always unlocked */
}

Such resource management classes (or “RAII classes”) are the cornerstone of modern C++ resource management, and countless examples of these kinds of classes have found their way into the standard (std::lock_guard, smart pointer, std::jthread, IOStreams, …) and third-party libraries. They serve the same function as finally clauses in other languages serve: to ensure resource release always happens, no matter which exit path the code takes.

One crucial question to be answered for RAII classes is how their copying behavior is. A lot of choices exist, and each of them has its own benefits, drawbacks, and use cases such that no one is the preferred approach. For instance, you can do:

Unique Ownership: The easiest way out. Just forbid copying and only allow moving (in some rare cases, you can even disallow moving if there is no suitable empty state). For memory resources, this is std::unique_ptr.
Deep-Copying: If the underlying resource is not unique, just copy the resource on every copy of the management class. For memory resources, this is std::indirect or std::polymorphic (C++26).
Reference Counting: One of the more complex approaches. Keep a carefully protected shared counter of the number of copies for each resource, and only release if the copy goes down to zero. This often requires intrusive bookkeeping or heap allocation while also requiring careful protection of concurrent modifications to the counter (through atomics or locks), and thus is much more heavyweight and more flexible than the above approaches. For memory resources, this is std::shared_ptr or boost::intrusive_ptr.
Shared Ownership: If we can do a safe shared counter, why not share the entire resource? This requires coordination from the resource itself, such as the presence of concurrent queues or locks to safely handle concurrent requests and also some way of handling multiple releases. This essentially combines management classes into the resource itself. The management class can be a simple observer/view that has trivial copying.

All of these require different operator= behavior. For unique ownership, normally you want to not generate operator=; for the rest, you want the generation of operator= but with vastly different behavior. For instance, shared ownership management classes can do with the default memberwise behavior, but for reference counting, that would be a disaster. It is precisely because of the lack of a preferred approach that Rule of Five exists: If you are writing a destructor, you are probably writing a RAII class, and in that case, you should write out the behavior of copy/move operations directly and explicitly; automatic generation is usually wrong. Reversely, if you are customizing copy/move operations, you are probably managing some kind of resources, and you should write a destructor to be an RAII class.

Rule of Five is great and does prevent a lot of mistakes; however, writing classes under this rule is really annoying:

class Widget
{
private:
    SomeResource resource;

public:
    // I'm managing resources; let's make this a RAII class
    ~Widget() { resource.release(); }

    // OOPS, that disable move operations; I want the shared ownership behavior, where defaulted copy/move suffice
    Widget(Widget&&) noexcept = default;
    Widget& operator=(Widget&&) & noexcept = default;

    // OOPS, those now disable copy operations
    Widget(const Widget&) = default;
    Widget& operator=(const Widget&) & = default;
};

Although it is correct to force you to always write out the intention explicitly, people are still lazy. In that case, I have a better rule to follow when overloading operator= as a special member function:

Rule of Zero: If you declare any of a copy constructor, move constructor, copy assignment operator, move assignment operator, or destructor, you should declare all five; however, normal classes shouldn’t define any of them; leave these to a (preferably standard) class specifically dealing with ownships.

class Widget
{
private:
    std::unique_ptr<SomeResource, decltype([](auto& r) { r.release(); })> resource;

public:
    // No need for a destructor!
    // Therefore, no need to manually restore move!
};

Once you factor out the handling of ownership into its own class, you’ll suddenly find that the automatically generated version Just Works. What a relief! Even better, as listed above, many common ownership handling classes have a standard version that handles everything for you, so ideally, you don’t ever need to write those five special members at all! This is why it is called the Rule of Zero.

[!NOTE] Even though things like unique_ptr handles memory resources, they all supported some form of custom deleters that allows you to handle arbitrary release behaviors; of course, it’s better to use more specific classes that have a better interface, such as preferring std::fstream over std::unique_ptr<FILE>)

None of us lives in an ideal world, but at least you should factor out your ownership logic into its own (preferably generic) class and enjoy Rule of Zero for the rest.

When Compiler Fails: Defaulted as deleted, and why it matters

Copy-and-Swap Idiom: When and How

More Idioms

Copy-and-Move Idiom

Implementing Constructors by Assignment

A Nightmare Operator: Deal with `optional<T&>`

`operator=` That Is Not Copy/Move Assignment: Irrelevant or Optimization?

Templated `operator=`

Virtual `operator=`: Genius or Trap?

`const operator=`: When Is A Contradiction Useful?

`swap`: An Operator Disguised

The Basics: Importance of A `noexcept swap`

ADL `swap` and `ranges::swap`: Incomplete Solution

Member or Non-Member or Hidden Friend? A War Story

Comparison Crash Course: `operator<=>` and `operator==` (and other five)

The Basics: Primary and Secondary Comparison

Comparison Result Types and Functions

Rewritten Candidates and Reverse Rewrite

The Default Situation and The Great Separation

Spaceship Idioms: Ignoring, Reversing

Functors: Overloading `operator()`

`static`, `const`, Lambda, `mutable`, Oh My!

Stateful and Pure Functors with Standard Algorithms

Perfect-Forwarding Functors: `= delete` and Deducing This

Arithmetic Operators

Compound Assignment: `operator@=`

Simple Arithmetic: `b+ b- b* / %`

The Basics

By-Value or Symmetry: Pick Your Poison

Bitwise Arithmetic: `| b& ~ >> <<`

Increment/Decrement: A Dilemma

Prefix: `operator++()` and `operator--()`

Postfix: `operator++(int)` and `operator--(int)`

The Weirdo: Unary `operator+()` and `operator-()`

Input/Output Operator

`operator>>` as Stream Extractor

The Basics

Dealing with Failure

`operator<<` as Stream Inserter

The Basics

Formatting Nightmare

Migrate to `std::formatter<T>`

Simulating a Pointer

One-and-a-Fake Unary: `operator*()` and `operator->()`

The Basics: Core Pointer

Shallow or Deep `const`?

The Unorthodox Arrow

The Forgotten Sister: `operator->*`

A Changed Friend: `operator[]`

The Basics: `const`-Coercing Subscript and Deducing This

Deploying an Multidimensional `operator[]`

Coroutine Internals: Overloading `operator co_await`

Understanding Awaiter and Awaitable

Decoding a Coroutine

Implementing `std::lazy<T>`

The Bad Nine

Defending Against the Dark Unary `operator&`

`&&` and `||`: Before and After C++17

Overloading `new` and `delete`: Explained

Why, When, and How

Global or Class-Scope?

Placement `new` and `nothrow new`

New Handler and the Memory Loop

Placement `delete`: The Weirdest Operator in the Standard

Overloading `new[]` and `delete[]`

A Wild Comma Ride

Conversion Operators: The Good, The Bad, and The Irrelevant

The One Good Conversion: `explicit operator bool()`

Other Niche Cases

An Irrelevant `!`

User-Defined Literal: Hidden Pearl of C++

The Basics: UDL Classification and Overloading

Integral UDL

Floating-Point UDL

Character UDL

String UDL

Templated UDL and the `constexpr std::string` Dilemma

Operator Overloading in the STL: A Glimpse

The Great Comparison Revolution

Iterator Special: Cornerstone of STL Algorithms

The Basics: Evolution of Iterator Category in the STL

`u*`, `->` and `++`: Disguised Core

`--`, `+=`, `-=`, and `[]`: Extending the Basic Iterator

Comparison For Iterators: A War Story

Sentinel: Revolution on the Old STL

Postfix `++ --` in C++20: A Rebellion

`explicit operator bool` for Ranges: A Twist

`u*`: Nullable, Pointer or Optional?

Deprecating and Decreasing `operator->`

`operator+` For `std::string`: A Mistake? Nightmare with `string_view`?

Standard Functors: Mistakes We Cannot Fix

Three Generations of `std::less`

Three Generations of `std::function`

The Power of The `std::bind` Family

A Survey of Bad Operators

Implicit Comparisons

`operator&&` and `operator||`

UDL in the STL

The Future of Operator Overloading

`operator?:`: A Cure for SIMD?

The Great Search For Dot

Overloadable `operator^^`: Customising Reflection

A Pipeline-Rewrite Operator: `|>`

A Control-Flow Operator: `??`

A Implication Arrow: A Herculean Task

A War Story on Pattern Matching and Operators (`is`, `as`, `match`, ...)

Basics: What Is PM And Why Should You Care?

Chaining vs Composition: The PM Debate in C++26

Generalized `match` and `is`: Converging Solutions

Prefix UDL: String Interpolation and More

Future of Operator Rewriting: Shooting An Arrow At The Star

MORE Rewriting! What's Not To Like?

Rewriting `->` and `->*`: War Signal From Library

Rewriting Arithmetic: How Far?

Chained Comparison: A Dream Revisited

Range Properties of the Standard Range Adaptors

Tue, 20 Sep 2022 00:00:00 GMT

Enumerate the basic usages and properties of C++20-26 Range Adaptors.

In this post, "range adaptors" refer to both range factories (algorithm that produce range, can only be the starting point of a pipeline, like views::single) and (real) range adaptors (algorithm that takes a range and return an adapted range, like views::filter). In C++20 standard, following the adoption of Ranges TS, the standard adopted 18 range adaptors:

5 factories: empty, single, iota, istream, counted
13 (real) adaptors: all, filter, transform, take, take_while, drop, drop_while, join, lazy_split, split, common, reverse, elements (keys/values are aliases)

Of course, this is only a small subset of what is provided in range-v3 (over 100 adaptors). C++23 greatly expanded range support in multiple ways, including the addition of 14 more adaptors:

4 new factories: zip, zip_transform, cartesian_product, repeat
10 new (real) adaptors: as_rvalue, join_with, as_const, enumerate, adjacent, adjacent_transform (pairwise are aliases), chunk, slide, chunk_by, stride

and C++26 is expected to provide even more (concat and maybe being the most expected ones).

Each adaptor has its own use case, feature, and limitations. Especially, each adaptors has its own accepted range properties, and the output range's properties also differ. These properties limitations are often not documented, in standard or elsewhere, making determine those properties a pain. Therefore, this post serves as an expansion upon the excellent post by Barry Revzin, adding more range adaptors and adding more properties so that the reference is more complete.

This post still follows the same convention set in the above linked post (W w meaning type and value, [T] means range with refernece type T, (A, B) means tuple<A, B>, A -> B means function taking A and returning B), and the properties surveyed are the original ones (reference, category, common, sized, const-iterable, borrowed) plus an additional one: constant (also, value type is included for convenience). A range being a constant range simply means that its iterator are constant iterator, i.e. we cannot modify its elements using its iterators, so const vector<int> is a constant range but vector<int> is not. Notice that all of those 7 categories can be detected by concepts:

reference: ranges::range_reference_t<R>
value type: ranges::range_value_t<R>
category: ranges::input_range<R> to ranges::contiguous_range<R>
common: ranges::common_range<R>
sized: ranges::sized_range<R>
const-iterable: ranges::range<const R>
borrowed: ranges::borrowed_range<R>
constant: ranges::constant_range<R> (C++23)

[!IMPORTANT] In the C++20 Ranges world, value type and reference type are two entirely different beast. Reference type is the type returned by operator*, and also the type that you interact with more commonly (ranges in this post is referred to as [T], where T is its reference type), basically you can think reference type as the element type (it is not necessarily a language reference). Value type is often a cvr-unqualified type that serves as "value of the same type of the element", which is commonly just reference type minus cvref qualifiers, but not necessarily (value type and reference type can be completely unrelated, as long as they have a common reference).

All of the original descriptions and properties are copied here, credit belongs to the original author.

C++20 Range Adaptors

Factories

`views::empty<T>: [T&]`

Produces an empty range of type T.

constraint: T is an object type
reference: T&
value type: T
category: contiguous
common: always
sized: always (0)
const-iterable: always
borrowed: always
constant: when T is const-qualified

`views::single(t: T) -> [T&]`

Produce a range that only contains a single value: t.

constraint: T is an object type
reference: T&
value type: T
category: contiguous
common: always
sized: always (1)
const-iterable: always
borrowed: never
constant: never (single_view<T> is only instantiated with decayed type)

`views::iota(beg: B[, end: E]) -> [B]`

Produce a range that start at beg, and incrementing forever (when there is only one argument) or until beg == end (exclude end as usual).

>>> iota(0)
[0, 1, 2, ...]
>>> iota(0, 5)
[0, 1, 2, 3, 4]
>>> iota(beg, end)
[beg, beg + 1, beg + 2, ..., end - 1]

[!TIP] Note that B and E can be any type, not just integral

constraint: B is copyable and weakly_incrementable (support pre/postfix ++ and have difference type) and E is semiregular (copyable and default initializable). Also, beg == end, beg != end (and reverse) are valid.
reference: B (prvalue range!)
value type: B
category:
- if B is advanceable (beg += n, beg -= n, beg + n, n + beg, beg - n, beg - beg are all valid, and B is totally ordered), random access.
- otherwise, if B is decrementable (support pre/postfix --), then bidirectional
- otherwise, if B is incrementable (regular and beg++ returns B), then forward
- otherwise, input.
common: when B and E are the same type
sized: the range is not infinity (there is a bound provided) and either:
- the range is common and random access, or
- both B and E are integer-like types, or
- E is a sized sentinel for B.
const-iterable: always
borrowed: always (iterator owns the current value)
constant: when B is a non-class type (like int)

`views::istream<T>(in: In) -> [T&]`

Produce a range of T such that elements are read by in >> t (read one element per increment).

constraint: T is movable and default initializable, and In is derived from basic_istream
reference: T&
value type: T
category: input
common: never (iterator are move-only, so not a C++17 input iterator anyway)
sized: never
const-iterable: never
borrowed: never
constant: never (T must be movable so it must not be const-qualified)

`views::counted(it: It, n: N) -> [*It]`

This is not a real range adaptor (there is no counted_view). Instead, it is an adaptor that adapt the range represented as [it, it + n) (begin + count) as the standard iterator-sentinel model. It adapts by construct a std::span or ranges::subrange.

constraint: n >= 0 and N must be convertible to the difference type of It.
reference: same as It's reference type
value type: same as It's value type
category: same as It's category (preserve contiguous)
common: if It is at least random access
sized: always
const-iterable: always
borrowed: always (counted_iterator owns the iterator and the count)
constant: when It is a constant iterator

Real Adaptors

`views::all(r: [T]) -> [T]`

Still, views::all is a semi-range adaptor; there is no all_view. Essentially, views::all(r) is a view of all the elements in r, which it done wrapping by either return auto(r) directly (if r is already a view), wrap in ref_view (if r is a lvalue), or wrap in owning_view otherwise. Therefore, all of views::all(r)'s range properties are exactly identical to that of r's.

`views::filter(r: [T], f: T -> bool) -> [T]`

(Includes DR changes brought by P3725R3 in the C++26 cycle.)

Produce a new range that only preserve elements of r that let f(e) evaluate to true.

>>> filter([1, 2, 3, 4], e => e % 2 == 0)
[2, 4]

constraint: F is copy-constructible, an object type, and is invocable by T and value_type&, and return a value that is contextually convertible to bool
reference: T
value type: same as r's value type
category: at most bidirectional
common: when r is common
sized: never
const-iterable: when r is input and not forward
borrowed: never
constant: when r is constant

`views::transform(r: [T], f: T -> U) -> [U]`

Return a new range such that each element is f(e) (where e is each element in r). Commonly called map in other languages.

>>> transform(["aa", "bb", "cc", "dd"], e => e[0])
['a', 'b', 'c', 'd']

constraint: F is move-constructible, an object type, and is invocable by T
reference: U
value type: remove_cvref_t
category: at most random access
common: when r is common
sized: when r is sized
const-iterable: when r is const-iterable and f is const-invocable
borrowed: never
constant: when U is a value of non-class type (like prvalue range of int) or a const reference (l/rvalue both applies)

`views::take(r: [T], n: N) -> [T]`

Produce a new range consists of the first n elements of r. If r has less than n elements, contains all of r's elements.

>>> take([1, 2, 3, 4], 2)
[1, 2]
>>> take([1, 2, 3, 4], 8)
[1, 2, 3, 4]

[!NOTE] views::take will produce r's type whenever possible (for example, empty_view passed in will return an empty_view).

constraint: n >= 0 and N is convertible to r's difference type
reference: T
value type: same as r's value type
category: same as r (preserve contiguous)
common: when r is sized and random access
sized: when r is sized
const-iterable: when r is const-iterable
borrowed: when r is borrowed
constant: when r is constant

`views::take_while(r: [T], f: T -> bool) -> [T]`

Produce a new range that includes all the element of r that makes f(e) evaluates to true until it first evaluates to false. (i.e. filter but stop when first false)

>>> take_while([1, 2, 3, 1, 2, 3], e => e < 3)
[1, 2]

constraint: F is an object type and is const-invocable by T and value_type&, and return a value that is contextually convertible to bool
reference: T
value type: same as r's value type
category: same as r (preserve contiguous)
common: never (begin() must return an iterator-to-r, so end() cannot reuse that iterator type)
sized: never
const-iterable: when r is const-iterable and f is const-invocable by the reference and lvalue of value type of as_const(r)
borrowed: never
constant: when r is constant

`views::drop(r: [T], n: N) -> [T]`

Produce a new range consists of the all but the first n elements of r. If r has less than n elements, produce an empty range.

>>> drop([1, 2, 3, 4], 2)
[3, 4]
>>> drop([1, 2, 3, 4], 8)
[]

[!NOTE] views::drop will produce r's type whenever possible (for example, empty_view passed in will return an empty_view).

constraint: n >= 0 and N is convertible to r's difference type
reference: T
value type: same as r's value type
category: same as r (preserve contiguous)
common: when r is common
sized: when r is sized
const-iterable: when r is const-iterable
borrowed: when r is borrowed
constant: when r is constant

`views::drop_while(r: [T], f: T -> bool) -> [T]`

Produce a new range that excludes the element of r until the first element that makes f(e) evaluates to false. (i.e. drop but stop when first false)

>>> drop_while([1, 2, 3, 1, 2, 3], e => e < 3)
[3, 1, 2, 3]

constraint: F is an object type and is const-invocable by T and value_type&, and return a value that is contextually convertible to bool
reference: T
value type: same as r's value type
category: same as r (preserve contiguous)
common: when r is common
sized: when R's sentinel is a sized sentinel for R's iterator

[!NOTE] In common case this requires common & random access range, but not necessarily; the requirement is s - i and i - s are valid and return the difference type.

const-iterable: never
borrowed: when r is borrowed
constant: when r is constant

`views::join(r: [[T]]) -> [T]`

Join together a range of several range-of-Ts into a single range-of-T. Commonly called flatten in other languages.

>>> join([[1, 2], [3], [4, 5, 6]])
[1, 2, 3, 4, 5, 6]

constraint: r and R's reference type ([T]) are both input ranges
reference: T
value type: same as [T]'s value type (the value type of inner range)
category:
- If r is a range of glvalue ranges, then at most bidirectional based on inner range's category
- Otherwise (range of prvalue ranges), input
common: when both r and inner range are forward and common, and r is a range of glvalue ranges
sized: never
const-iterable: when r is const-iterable and is a range of glvalue ranges
borrowed: never
constant: when inner range is constant

`views::lazy_split(r: [T], p: T | [T]) -> [[T]]`

(The fixed version after C++20 DR P2210R2) Produce a range that splits a range of T into a range of several range-of-Ts based on delimeter (which can be a single element or a continuous subrange).

>>> lazy_split("a bc def", ' ')
["a", "bc", "def"]
>>> lazy_split("a||b|c||d", "||")
["a", "b|c", "d"]
>>> lazy_split("abcd", "")  # when size = 0, just split at every element
["a", "b", "c", "d"]

lazy_split is maximally lazy, and it will never touch any element until you increment to the element (i.e. will not compute any "next pattern position"), and thus support input ranges. However, the tradeoff is that the resulting inner range can only be at most forward, as you don't really know you are at the end until you increment here.

constraint: p is either a forward range or convertible to the value type of R. Also, when r is only an input range, p must be a sized range with size 0 or 1 (nothing or a single element). (The reference type and lvalues of values of P and R also must be inter-comparable)
reference: [T] (lazy_split_view::value_type, a range with reference type T)
value type: outer range same as reference, inner range same as r's value type
category: both outer range and inner range is at most forward based on R's category (for a stronger inner range, see views::split)
common: outer range when r is forward and common, inner range never
sized: (both outer and inner range) never
const-iterable: outer range when r is const-iterable and both R and const R are forward ranges; inner range always
borrowed: (both outer and inner range) never
constant: outer range never, inner range when r is constant

`views::split(r: [T], p: T | [T]) -> [[T]]`

>>> split("a bc def", ' ')
["a", "bc", "def"]
>>> split("a||b|c||d", "||")
["a", "b|c", "d"]
>>> split("abcd", "")  # when size = 0, just split at every element
["a", "b", "c", "d"]

split is still lazy, but it eagerly computes the start of next subrange when iterating, thus does not support input range but allow subrange to be at most contiguous. (Since input range is rare and most string algorithm require more than forward range, this should be used in most times)

constraint: r must be a forward range (for splitting input range, use lazy_split), p is either a forward range or convertible to the value type of R. (The reference type and lvalues of values of P and R also must be inter-comparable)
reference: [T] (specifically, the reference type is precisely ranges::subrange<iterator_t<R>>)
value type: same as reference type (inner range's value type same as r's)
category: outer range forward, inner range same as r (preserve contiguous)
common: outer range when r is common, inner range always
sized: outer range never, inner range when r's sentinel is a sized sentinel (common case is when r is random access)
const-iterable: outer range never, inner range when r is const-iterable
borrowed: outer range never, inner range always
constant: outer range never, inner range when r is constant

`views::common(r: [T]) -> [T]`

Produce a range with same element as in r, but ensure that the result is a common range. (Basically exists as a compatibility layer so that pre-C++20 iterator-pair algorithms can use C++20 ranges)

constraint: either r is common, or iterators of R must be copyable
reference: T
value type: same as r's value type
category: if r is common or both random access and sized, then same as r (preserve contiguous); otherwise at most forward
common: always (this is the point of this adaptor)
sized: when r is sized
const-iterable: when r is const-iterable
borrowed: when r is borrowed
constant: when r is constant

`views::reverse(r: [T]) -> [T]`

Produce a range that contains the reverse of the elements in r.

>>> reverse([1, 2, 3])
[3, 2, 1]

[!TIP] Note that the reverse of reverse_view is simply the base range itself, and subrange passed-in will return subrange too.

constraint: r is at least bidirectional
reference: T
value type: same as r's value type
category: at most random access
common: always
sized: when r is sized
const-iterable: when r is const-iterable and const R is common
borrowed: when r is borrowed
constant: when r is constant

`views::elements<I: size_t>(r: [(T1, T2, ..., TN)]) -> [TI]`

Produce a range consists of the I-th element of each element (which are tuples). views::keys is equivalent to views::element<0>, and views::values is equivalent to views::element<1>.

>>> r = [("A", 1), ("B", 2)]
>>> elements<1>(r)  # or values(r)
[1, 2]
>>> keys(r)  # or elements<0>(r)
["A", "B"]

constraint: r's reference type T = (T1, T2, ..., TN) (minus reference) and value type are tuple-like types with size larger than I, and either T is a true reference (not prvalue/proxy range), or the I-th type in the tuple is move constructible.
reference: TI (the return type of std::get(e) where e is an element of r), with R's cvref qualifier copied onto
value type: remove_cvref_t<reference>
category: at most random access
common: when r is common
sized: when r is sized
const-iterable: when r is const-iterable
borrowed: when r is borrowed
constant: when r is constant (?)

Other Standard Views

(std::initializer_list<T> is technically a view, but it does not model ranges::view.)

`std::basic_string_view<charT[, traits[, Alloc]]>: [charT&]`

A lightweight view of a constant contiguous sequence of charTs (i.e. a string). Can view const charT*, std::basic_string, and many more.

constraint: charT must be char-like (non-array trivial standard-layout type), and traits must be a character trait
reference: charT&
value type: charT
category: contiguous
common: always
sized: always
const-iterable: always
borrowed: always
constant: always

`std::span<T[, extent: size_t]>: [T&]`

A lightweight view of a contiguous sequence of Ts). Can view T*, so a replacement of traditional T* + length idiom. A span<T> is by default with dynamic extent, and span<T, extent> is a view of fixed size.

constraint: T must be a complete object type that is not abstract.
reference: T&
value type: remove_cvref_t<T>
category: contiguous
common: always
sized: always
const-iterable: always
borrowed: always
constant: when T is const-qualified

C++23 Range Adaptors

These are the range adaptors available in C++23 DIS.

Factories

`views::zip(r1: [T1], r2: [T2], ...) -> [(T1, T2, ...)]`

Produce a new range that is r1, r2, ... zipped together; i.e. a range of tuple of each corresponding elements in each of the argument ranges.

>>> zip([1, 2, 3], [4, 5, 6])
[(1, 4), (2, 5), (3, 6)]
>>> zip([1, 2], ["A", "B"], [1.0, 2.0])
[(1, "A", 1.0), (2, "B", 2.0)]
>>> zip()
[]  # empty view with type tuple<>

constraint: all the ranges are input
reference: tuple<T1, T2, ...> (note that TI is the reference type)
value type: tuple<range_value_t<R1>, ...> (not the reference type minus reference)
category: the weakest category in all of r1, r2, ..., and also at most random access
common: when either of following is true:
- there is only one range (zip(r)) and this range is common, or
- the zip_view is not bidirectional (i.e. at most forward), and all of r1, r2, ... are common, or
- all of r1, r2, ... are both random access and sized
sized: when all of r1, r2, ... are sized
const-iterable: when all of r1, r2, ... are const-iterable
borrowed: when all of r1, r2, ... are borrowed
constant: when all of r1, r2, ... are constant

`views::zip_transform(f: (T1, T2, ...) -> U, r1: [T1], r2: [T2], ...) -> [U]`

Produce a new range in which each element is f(e1, e2, ...) where e1, e2 is the corresponding element of r1, r2, ... respectfully.

>>> zip_transform(f, [1, 2, 3], [4, 5, 6])
[f(1, 4), f(2, 5), f(3, 6)]
>>> zip_transform((a, b, c) => to_string(a) + b + to_string(c), [1, 2], ["A", "B"], [1.0, 2.0])
["1A1.0", "2B2.0"]
>>> zip_transform(f)
[]  # empty view with the type of result of f()

constraint: F is move constructible and is an object type, is invocable by T1, T2, ..., and all the ranges are input
reference: U
value type: remove_cvref_t
category: if f(e1, e2, ...) does not return a lvalue reference, input; otherwise the weakest category in all of r1, r2, ..., and also at most random access
common: when zip(r1, r2, ...) is common
sized: when all of r1, r2, ... are sized
const-iterable: when all of r1, r2, ... are const-iterable and f is const-invocable
borrowed: never
constant: when the result of f(e1, e2, ...) is a non-class or std::tuple (pr)value, or when it returns a constant reference

`views::cartesian_product(r1: [T1], r2: [T2], ...) -> [(T1, T2, ...)]`

Produce a new range that is r1, r2, ... cartesian producted together; i.e. a range of tuple of every possible pair of elements in each of the argument ranges.

>>> cartesian_product([1, 2, 3], [4, 5, 6])
[(1, 4), (1, 5), (1, 6), (2, 4), (2, 5), (2, 6), (3, 4), (3, 5), (3, 6)]
>>> cartesian_product([1, 2], ["A", "B"], [1.0, 2.0])
[(1, "A", 1.0), (1, "A", 2.0), (1, "B", 1.0), (1, "B", 2.0),
 (2, "A", 1.0), (2, "A", 2.0), (2, "B", 1.0), (2, "B", 2.0)]
>>> cartesian_product()
[()]  # views::single(std::tuple<>{})

constraint: all of r2, r3, ... (all ranges except the first one) are forward
reference: tuple<T1, T2, ...> (note that TI is the reference type)
value type: tuple<range_value_t<R1>, ...> (not the reference type minus reference)
category:
- if the first range r1 is random access, and all other ranges are both random access and sized, then random access
- otherwise, if the first range r1 is bidirectional, and all other ranges are either both bidirectional and common, or both random access and sized, then bidirectional
- otherwise, if the first range r1 is forward, then forward
- otherwise, input
common: when r1 is common, or is both sized and random access
sized: when all of r1, r2, ... are sized
const-iterable: when all of r1, r2, ... are const-iterable
borrowed: never
constant: when all of r1, r2, ... are constant

`views::repeat(t: T[, n: N]) -> [const T&]`

Produce a range that repeats the same value t either infinitely (when there is only one argument), or for n times.

>>> repeat(2)
[2, 2, 2, ...]
>>> repeat(2, 5)
[2, 2, 2, 2, 2]

constraint: T is move constructible and is an object type; N (if provided) is a semiregular integer-like type
reference: const T&
value type: T
category: random access
common: when the resulting range is not infinite (i.e. when n is provided)
sized: when the resulting range is not infinite (i.e. when n is provided)
const-iterable: always
borrowed: never
constant: always

Real Adaptors

`views::as_rvalue(r: [T]) -> [T&&]`

Produce a range with same element as in r, but ensure that the result is a range of rvalue reference. (Basically, did a std::move on each element so that you can then move every element from the view into some container or things like that)

constraint: r is an input range
reference: range_rvalue_reference_t<R> (which normally is the result type of std::move(*r.begin()) so basically T&&, but you can customize it by ranges::iter_move)
value type: same as r's value type
category: at most random access (the original intent is that as_rvalue_view should be input-only, but later P2520R0 changed as_rvalue_view to now be up to random access)
common: when r is common
sized: when r is sized
const-iterable: when r is const-iterable
borrowed: when r is borrowed
constant: when r is constant

`views::join_with(r: [[T]], p: U | [U]) -> [common_reference_t<T, U>]`

Join together a range of several range-of-Ts into a single range-of-T, with p inserted between each parts. This is the reverse of views::split.

>>> join_with([[1, 2], [3], [4, 5, 6]], 3)
[1, 2, 3, 3, 3, 4, 5, 6]
>>> join_with([[1, 2], [3], [4, 5, 6]], [3, 4])
[1, 2, 3, 4, 3, 3, 4, 4, 5, 6]

constraint: r and R's reference type ([T]) are both input ranges, p is either a forward range or convertible to the value type of R. (inner range and p's value and reference type must also have common reference)
reference: common_reference_t<T, U>
value type: the common_type_t of inner range and p's value type
category:
- If r is a range of prvalue ranges, then input
- Otherwise (r is a range of glvalue ranges), and if r is bidirectional, and inner range and p are both bidirectional and common, then bidirectional
- Otherwise, if r and inner range are both forward, then forward
- Otherwise, input
common: when both r and inner range are forward and common, and r is a range of glvalue ranges
sized: never
const-iterable: when both r and p are const-iterable and r is a range of glvalue ranges
borrowed: never
constant: when inner range and p are both constant

`views::as_const(r: [T]) -> [T]`

Produce a range with same element as in r, but ensure that the result's element cannot be modified (i.e. a constant range). (Basically, did a std::as_const on each element so that you cannot modify them, albeit with a much more complicated algorithm that avoid wrapping if at all possible by delegate to std::as_const)

constraint: r is an input range
reference: range_const_reference_t<R> (assuming r's value type is just remove_cvref_t of its reference, then for a range of T&, just const T&; for a range of T&&, just const T&&; for a range of prvalue T, just T)
value type: same as r's value type
category: same as r's category (preserve contiguous)
common: when r is common
sized: when r is sized
const-iterable: when r is const-iterable
borrowed: when r is borrowed
constant: always

`views::enumerate(r: [T]) -> [(N, T)]`

Produce a range such that each of the original elements of r is accompanied by its index in r.

>>> enumerate([1, 3, 6])
[(0, 1), (1, 3), (2, 6)]

(Notice that the index type N is range_difference_t<R>)

constraint: r is an input range, and T is move constructible.
reference: tuple<N, T>
value type: tuple<N, range_value_t<R>> (not the reference type minus reference)
category: at most random access
common: when r is common and sized
sized: when r is sized
const-iterable: when r is const-iterable
borrowed: when r is borrowed
constant: when r is constant

`views::adjacent<N: size_t>(r: [T]) -> [(T, T, ...)]`

Produce a new range where each elements is a tuple of the next consecutive N elements. pairwise is an alias for adjacent<2>. If r has less than N elements, the resulting range is empty.

>>> adjacent<4>([1, 2, 3, 4, 5, 6])
[(1, 2, 3, 4), (2, 3, 4, 5), (3, 4, 5, 6)]
>>> pairwise(["A", "B", "C"])  # or adjacent<2>
[("A", "B"), ("B", "C")]
>>> adjacent<7>([1, 2, 3])
[]  # empty view with type tuple<int&, int&, ...> (repeat 7 times)
>>> adjacent<0>([1, 2, 3, 4, 5, 6])
[]  # empty view with type tuple<>

constraint: r is a forward range and N > 0
reference: tuple<T, T, ...> (repeat N times, note that T is the reference type of r)
value type: tuple<range_value_t<R>, ...> (repeat N times, not the reference type minus reference)
category: at most random access
common: when r is common
sized: when r is sized
const-iterable: when r is const-iterable
borrowed: when r is borrowed
constant: when r is constant

`views::adjacent_transform<N: size_t>(f: (T, T, ...) -> U, r: [T]) -> [U]`

Produce a new range where each elements is the result of f(e1, e2, ...), where e1, e2, ... are the next consecutive N elements. pairwise_transform is an alias for adjacent_transform<2>. If r has less than N elements, the resulting range is empty.

>>> adjacent_transform<4>(f, [1, 2, 3, 4, 5, 6])
[f(1, 2, 3, 4), f(2, 3, 4, 5), f(3, 4, 5, 6)]
>>> adjacent_transform<4>((a, b, c, d) => a + b + c + d, [1, 2, 3, 4, 5, 6])
[10, 14, 18]
>>> pairwise_transform((a, b) => a + b, ["A", "B", "C"])  # or adjacent_transform<2>
["AB", "BC"]
>>> adjacent_transform<0>(f, [1, 2, 3, 4, 5, 6])
[]  # empty view with type of the result of f()

constraint: r is a forward range, N > 0, F is move constructible and is an object type, and invocable by T, T, ... (repeat N times)
reference: U
value type: remove_cvref_t
category: if f(e1, e2, ...) does not return a lvalue reference, then input; otherwise at most random access
common: when r is common
sized: when r is sized
const-iterable: when r is const-iterable and f is const-invocable
borrowed: never
constant: when the result of f(e1, e2, ...) is a non-class or std::tuple (pr)value, or when it returns a constant reference

`views::chunk(r: [T], n: N) -> [[T]]`

Produce a new range-of-range that is the result of dividing r into non-overlapping n-sized chunks (except that last chunk can be smaller than n).

>>> chunk([1, 2, 3, 4, 5], 2)
[[1, 2], [3, 4], [5]]
>>> chunk([1, 2, 3, 4], 8)
[[1, 2, 3, 4]]

constraint: n > 0 and N is convertible to r's difference type
reference: [T] (if r is forward, then actually the reference type is ranges::subrange<iterator_t<R>>)
value type: same as reference type (inner range's value type same as r's)
category: outer range at most random access, inner range same as r (preserve contiguous)
common: outer range when r is common and either both sized and bidirectional, or forward and not bidirectional; inner range when r is common
sized: outer range when r is sized, inner range when r's sentinel is a sized sentinel (common case is when r is random access)
const-iterable: (both outer and inner range) when r is const-iterable and forward
borrowed: outer range when r is borrowed and forward, inner range when r is forward
constant: outer range never, inner range when r is constant

`views::slide(r: [T], n: N) -> [[T]]`

Produce a new range-of-range that is the result of dividing r into overlapping n-sized chunks (basically, the m-th range is a view into the m-th through m+n-1-th elements of r). This is similar to views::adjacent<n> with the difference being that adjacent require a compile-time size and produce range-of-tuples, while views::slide require a runtime size and provide range-of-ranges.

>>> slide([1, 2, 3, 4, 5], 2)
[[1, 2], [2, 3], [3, 4], [4, 5]]
>>> slide([1, 2, 3, 4], 8)
[]

constraint: r is a forward range, n > 0, and N is convertible to r's difference type
reference: [T] (specifically, the reference type is precisely the result type of views::counted(r.begin(), n), which is a span (when r is contiguous) or a ranges::subrange otherwise)
value type: same as reference type (inner range's value type same as r's)
category: outer range at most random access, inner range same as r (preserve contiguous)
common: outer range when r is common or is both random access and sized, inner range when r is random access
sized: outer range when r is sized, inner range always
const-iterable: outer range when r is const-iterable and random access and sized, inner range always
borrowed: outer range when r is borrowed, inner range always
constant: outer range never, inner range when r is constant

`views::chunk_by(r: [T], f: (T, T) -> bool) -> [[T]]`

Produce a new range-of-range such that f is invoked on consecutive elements, and a new group is started when f returns false.

>>> chunk_by([1, 2, 2, 3, 1, 2, 0, 4, 5, 2], (a, b) => a <= b)
[[1, 2, 2, 3], [1, 2], [0, 4, 5], [2]]
>>> chunk_by([1, 2, 2, 3, 1, 2, 0, 4, 5, 2], (a, b) => a >= b)
[[1], [2, 2], [3, 1], [2, 0], [4], [5, 2]]

constraint: r is a forward range, and f is invocable on any combination of T and r's value type (and return a contextually-convertible-to-bool)
reference: [T] (specifically, the reference type is precisely ranges::subrange<iterator_t<R>>)
value type: same as reference type (inner range's value type same as r's)
category: outer range at most bidirectional, inner range same as r (preserve contiguous)
common: outer range when r is common, inner range always
sized: outer range never, inner range when r's sentinel is a sized sentinel (common case is when r is random access)
const-iterable: outer range never, inner range when r is const-iterable
borrowed: outer range never, inner range always
constant: outer range never, inner range when r is constant

`views::stride(r: [T], n: N) -> [T]`

Produce a new range consists of an evenly-spaced subset of r (with space fixed at n).

>>> stride([1, 2, 3, 4], 2)
[1, 3]
>>> stride([1, 2, 3, 4, 5, 6, 7], 3)
[1, 4, 7]

constraint: n > 0 and N is convertible to r's difference type
reference: T
value type: same as r's value type
category: at most random access
common: when r is common and either sized or non-bidirectional
sized: when r is sized
const-iterable: when r is const-iterable
borrowed: when r is borrowed
constant: when r is constant

Other Standard Views

`std::generator<T[, U[, Alloc]]> : [U ? T : T&&]`

Produce a view of all the things you have co_yielded in a coroutine.

std::generator<int> ints(int start = 0) {
    while (true) co_yield start++;
}

void f() {
    std::println("{}", ints(3) | views::take(3)); // [3, 4, 5]
}

constraint: if U is present, it is a cv-unqualified object type and T is either a true reference or copy constructible
reference: if U is present, T; otherwise T&&
value type: if U is present, U; otherwise remove_cvref_t<T>
category: input
common: never
sized: never
const-iterable: never
borrowed: never
constant: when T is a const reference

C++26 Range Adaptors

Factories

`views::concat(r1: [T1], r2: [T2], ...) -> [common_reference_t<T1, T2, ...>]`

Produce a new range that is r1, r2, ... concated head-to-tail together; i.e. a range that starts at the first element of the first range, ends at the last element of the last range, with all range elements sequenced in between respectively in the order of arguments.

>>> concat([1, 2, 3], [4, 5, 6])
[1, 2, 3, 4, 5, 6]
>>> concat([1, 2], [3, 4], [1.0, 2.0])
[1.0, 2.0, 3.0, 4.0, 1.0, 2.0]
# concat() is ill-formed

constraint: all of T1, T2, ... have a common_reference_t, each of which is converted to that common reference type, and all of r1, r2, ...'s value type have a common_type_t
reference: common_reference_t<T1, T2, ...>
value type: common_type_t<range_value_t<R1>, ...> (not the reference type minus reference)
category:
- if all of r1, r2, ... are random access, and all but the last range are common, then random access
- otherwise, if all of r1, r2, ... are bidirectional, and all but the last range are common, then bidirectional
- otherwise, if all of r1, r2, ... are forward, then forward
- otherwise, input
common: when the last range rn is common
sized: when all of r1, r2, ... are sized
const-iterable: when all of r1, r2, ... are const-iterable
borrowed: never (can be made conditionally borrowed, but the space cost is too high)
constant: when all of r1, r2, ... are constant

`views::indices(n: N) -> [N]`

A convenient alias/alternative for views::iota(0uz, ranges::size(r)). Basically, produce a range of 0, 1, ..., n - 1.

>>> indices(5)
[0, 1, 2, 3, 4]

constraint: N must be an integral type
reference: N (prvalue range!)
value type: N
category: random access
common: always
sized: always
const-iterable: always
borrowed: always (iterator owns the current value)
constant: always

Real Adaptors

`views::cache_latest(r: [T]) -> [T&]`

Cache the last element of any range to avoid extra work. For example: r | views::transform(f) | views::filter(g) will call f twice for every element of r when iterating, because filter dereferences twice on each iteration. If you add views::cache_latest between the two adaptor, f will only be called once per element.

constraint: r is an input range
reference: T& (force lvalue reference here)
value type: same as r's value type
category: input
common: never
sized: when r is sized
const-iterable: never
borrowed: never
constant: when r is constant

`views::as_input(r: [T]) -> [T]`

Downgrade any range to an input, non-common range.

Useful to avoid expensive operations that many range algorithm/adaptor perform to preserve higher properties. For example:

views::join's iterator comparison need to do two base iterator comparisons (one for outer and one for inner) for common range, but only one is needed for non-common range.
views::chunk have more expensive algorithm when passed with a forward range: iterating through chunk border will incur a whole pass of all the elements for forward ranges.

[!NOTE] views::as_input will produce r's type whenever possible

constraint: r is an input range
reference: T
value type: same as r's value type
category: input (this is the point of this adaptor)
common: never
sized: when r is sized
const-iterable: when r is const-iterable
borrowed: when r is borrowed
constant: when r is constant

Other Standard Views

`std::optional<T>: [T&]`

In C++26, std::optional<T>, who represents an object that may or may not store a T, is upgraded to model view. The underlying intention is for optional to behave as a container of 0 or 1 elements.

>>> optional<int>()
[]
>>> optional<int>(1)
[1]

reference: T&
value type: remove_cv_t<T>
category: contiguous
common: always
sized: always (0 if disengaged, 1 if engaged)
const-iterable: always
borrowed: never
constant: when T is const-qualified

Future Range Adaptors In Review

Factories

`views::nullable(n: std::maybe<T>) -> [T&]`

(Current design as of P1255R14.)

Produce a new range of 0 or 1 element based on a nullable object.

int* p = new int(3);
nullable(p) // [3]
int* q = nullptr;
nullable(q) // []

constraint: N is copyable, an object type, and models std::maybe (basically dereferencable and contextually convertible to bool). (Or a reference_wrapper of such a type)
reference: T& (the iterator type is actually T*)
value type: T
category: contiguous
common: always
sized: always
const-iterable: always
borrowed: when N is a pointer, a reference_wrapper or a reference
constant: when T is const-qualified

`any_view<V[, Opts[, R[, RR[, Diff]]]]>: [R ? R : V&]`

(Current design as of P3411R6.)

A type-erased view that allows customizing the traversal category and other properties. Useful for hiding the concrete result type of a range pipeline, such as:

ranges::any_view<Widget> getWidgets()
{
    std::vector<Widget> widgets_{ /* ... */ };
    return widgets_ | views::filter(/* ... */) | views::take_while(/* ... */);
}

Here, if you used auto as return type, the return type will be take_while_view<filter_view<vector<Widget>, ...>, ...>, which is not only complicated to spell and mangle, but also exposed internal implementation. Using any_view here hide that nicely.

The Opts template parameter (defaults to any_view_options::input) is a scoped enum that specifies the category, sized, borrowedness and copyability of the resulting any_view:

enum class any_view_options
{
    input = 1,
    forward = 3,
    bidirectional = 7,
    random_access = 15,
    contiguous = 31,
    approximately_sized = 32,
    sized = 96,
    borrowed = 128,
    copyable = 256
} Opts;

Users are expected to bit-or these options to construct the desired composition of properties. RRef specifies the desired range_rvalue_reference_t (defaults to Ref - & + &&).

reference: R (defaults to V& if not specified)
value type: V
category: depends on Opts
common: never
sized: depends on Opts
const-iterable: never
borrowed: depends on Opts
constant: depends on V, R and RRef

`views::null_term(r: *[T]) -> [T]`

(Current design as of P3705R2.)

A view that produces a null-terminated range from an starting iterator. For instance, for const char* long_string, views::null_term(long_string) effectively represents a cstring_view of this NTBS without the overhead of computing the length.

[!TIP] This view is just an alias of subrange(r, std::null_sentinel), where null_sentinel is a simple sentinel providing operator== that forwards to *rng == T().

constraint: r is an iterator with a default initializable value type.
reference: T
value type: same as r's value type
category: same as r (preserve contiguous)
common: never
sized: never
const-iterable: when r is const-iterable
borrowed: never
constant: when r is constant

`views::set_{difference,intersection,union,symmetric_difference}(r1: [T], r2: [U], ...) -> [T] | [U] | ...`

(Current design as of P3741R1.)

These four views performs common set operations between two ranges:

views::set_difference(A, B) returns elements in A that is not in B
views::set_intersection(A, B, ...) returns elements in A that is also in B (and all other ranges provided)
views::set_union(A, B, ...) returns elements that are either in A or in B or both (or either of the other ranges provided)
views::set_symmetric_difference(A, B) returns elements that are either in A or in B, but not both

>>> set_difference([1, 2, 3, 4], [1, 2, 5, 6])
[3, 4]
>>> set_intersection([1, 2, 3, 4], [1, 2, 5, 6], [1, 2, 7, 8])
[1, 2]
>>> set_union([1, 2, 3, 4], [1, 2, 5, 6], [1, 2, 7, 8])
[1, 2, 3, 4, 5, 6, 7, 8]
>>> set_symmetric_difference([1, 2, 3, 4], [1, 2, 5, 6])
[3, 4, 5, 6]

constraint: r1 and r2 (and any additional ranges) are both input ranges; for every pair of provided ranges, their iterator have an indirect strict weak order (basically just have comparison between T an U and their value types). For union and symmetric_difference, also requires that all provided ranges can be concatenated using views::concat
reference: for difference and intersection, T; for union and symmetric_difference, common_reference_t<T, U, ...>
value type: for difference and intersection, same as r1's value type; for union and symmetric_difference, common_type_t<range_value_t<R1>, range_value_t<R2>>
category: at most forward
common: never
sized: never
const-iterable: for set_union, always; for other three, never
borrowed: never
constant: when all provided ranges are constant

Real Adaptors

`views::flat_map(r: [T], f: T -> [U]) -> [U]`

(Current design as of P3211R2.)

Transform the input sequence to a range-of-range, and then join all the ranges. Following P2328, this adaptor can be implemented directly as views::transform(r, f) | views::cache_latest | views::join, but this adaptor is not just an alias for that because a standalone view can cache the transform result and avoid repeated calls without reducing the entire range back to input (which cache_latest would do).

>>> flat_map([0, 1, 2], x => [x, x, x])
[0, 0, 0, 1, 1, 1, 2, 2, 2]

constraint: r and [U] are both input ranges, F is move-constructible, an object type, and is invocable by T
reference: U
value type: same as [U]'s value type (the value type of invocation result)
category:
- If [U] is a glvalue range, then at most bidirectional based on [U]'s category
- Otherwise (range of prvalue ranges), input
common: when both r and [U] are forward and common, and [U] is a glvalue range
sized: never
const-iterable: when r is const-iterable and f is const-invocable, and [U] is a glvalue range
borrowed: when r is borrowed and forward, [U] is borrowed, and F is tidy (i.e. empty and trivially default constructible and trivially destructible)
constant: when [U] is constant

`views::slice(r: [T], m: N, n: N) -> [T]`

(Current design as of P3216R3.)

Produce a new range consists of the m-th to n-th (as usual, left inclusive, right exclusive) elements of r. If r has less than n elements, contains all the elements after the m-th. If r has less than m elements, produce an empty range.

>>> slice([1, 2, 3, 4, 5], 1, 3)
[2, 3]
>>> slice([1, 2, 3, 4, 5], 1, 10)
[2, 3, 4, 5]
>>> slice([1, 2, 3, 4, 5], 10, 12)
[]

[!NOTE] views::slice will produce r's type whenever possible (for example, empty_view passed in will return an empty_view), even if views::slice(r, m, n) is not just an alias for views::take(views::drop(r, m), n - m). (The reason for a dedicated view boils down to performance and support for reserve_hint().)

constraint: n >= m && m >= 0 and N is convertible to r's difference type
reference: T
value type: same as r's value type
category: same as r (preserve contiguous)
common: when r is sized and random access
sized: when r is sized
const-iterable: when r is const-iterable or input and not forward
borrowed: when r is borrowed
constant: when r is constant

`views::unchecked_take(r: [T], n: N) -> [T]`

(Current design as of P3230R3.)

A variation of views::take that assumes there are at least n elements in r. In other words, more efficient in common cases but is UB if you try to take more than length elements.

>>> unchecked_take([1, 2, 3, 4], 2)
[1, 2]

[!NOTE] Note that views::unchecked_take will produce r's type whenever possible (for example, span passed in will return an span). Also note that views::unchecked_take may downgrade infinite ranges to finite ones (views::iota(0) | views::unchecked_take(5) is just views::iota(0, 5), while views::take cannot preserve type when iota_view is not sized).

constraint: n >= 0 && n <= ranges::distance(r) and N is convertible to r's difference type
reference: T
value type: same as r's value type
category: same as r (preserve contiguous)
common: when r is random access
sized: always (n)
const-iterable: when r is const-iterable
borrowed: when r is borrowed
constant: when r is constant

`views::unchecked_drop(r: [T], n: N) -> [T]`

(Current design as of P3230R3.)

A variation of views::drop that assumes there are at least n elements in r. In other words, more efficient in common cases but is UB if you try to drop more than length elements.

>>> unchecked_drop([1, 2, 3, 4], 2)
[3, 4]

[!NOTE] views::unchecked_drop will produce r's type whenever possible (for example, span passed in will return an span). Also note that views::unchecked_drop may process infinite ranges better (views::iota(0) | views::unchecked_drop(5) is just views::iota(5), while views::drop cannot preserve type when iota_view is not sized).

constraint: n >= 0 && n <= ranges::distance(r) and N is convertible to r's difference type
reference: T
value type: same as r's value type
category: same as r (preserve contiguous)
common: when r is common
sized: when r is sized
const-iterable: when r is const-iterable or input and not forward
borrowed: when r is borrowed
constant: when r is constant

`views::take_before(r: [T], p: U) -> [T]`

(Current design as of P3220R3.)

Produce a new range that includes all the element of r until p (inclusive). Similar to views::take_while but using a value instead of a predicate for ending detection. Very useful in cases like importing NTBS ranges with views::take_before(str, '\0').

>>> take_before([1, 2, 3, 4, 5], 3)
[1, 2, 3]
>>> take_before([1, 2, 3, 4, 5], 6)
[1, 2, 3, 4, 5]

constraint: r is an input range, and U is an object type and move constructible and t == u is well-formed for both T and r's value type
reference: T
value type: same as r's value type
category: same as r (preserve contiguous)
common: never (begin() must return an iterator-to-r, so end() cannot reuse that iterator type)
sized: never
const-iterable: when r is const-iterable and U is equality comparable with the reference and lvalue of value type of as_const(r)
borrowed: when T is a scalar type
constant: when r is constant

`views::cycle(r: [T][, n: N]) -> [T]`

(Current design as of P3806R1.)

Produce a new range that repeatedly cycle through all the element of r. The adaptor also supports passing in an optional count parameter to cycle for n times instead of infinity.

>>> cycle([1, 2, 3])
[1, 2, 3, 1, 2, 3, 1, 2, 3, ...]
>>> cycle([1, 2, 3], 2)
[1, 2, 3, 1, 2, 3]
>>> cycle([])
[]

constraint: r is a forward range; N (if provided) is convertible to an implementation-defined signed-integer-like type
reference: T
value type: same as r's value type
category: if r is random access and sized, then random access; otherwise, at most bidirectional
common: when n is provided
sized: when n is provided and r is sized
const-iterable: when r is const-iterable and const R is a forward range
borrowed: never
constant: when r is constant

`views::scan(r: [T], f: (Acc/T | U, T) -> U[, init: Acc]) -> [U]`

(Current design as of P3351R4.)

Produce a new range that takes a range and a function that takes the current element and the current state as parameters. Basically, views::transform with a stateful function. Optionally takes an initial seed to be used as the initial accumulator.

>>> scan([1, 2, 3, 4, 5], (a, b) => a + b)
[1, 3, 6, 10, 15]
>>> scan([1, 2, 3, 4, 5], (a, b) => a + b, 10)
[11, 13, 16, 20, 25]

constraint: F is move-constructible, an object type, and is invocable by either (Acc, T) (if provided initial seed) or (T, T) (if not), while also invocable by (U, T) where U is the return type of F invoking on these parameter types.
reference: U
value type: remove_cvref_t
category: input (due to stashing iterator concerns it cannot be forward)
common: never (iterator need to store accumulator)
sized: when r is sized
const-iterable: when r is const-iterable and f is const-invocable
borrowed: when F is tidy (i.e. empty and trivially default constructible and trivially destructible)
constant: when U is a value of non-class type (like prvalue range of int) or a const reference (l/rvalue both applies)

`views::{from,to}_{little,big}_endian(r: [T]) -> [T]`

(Current design as of P4030R1.)

Produce a new range that converts the endian-ness of the input. If the native endian-ness if big endian, then {from,to}_big_endian is a no-op; otherwise, {from,to}_little_endian is a no-op. When these views are not no-ops, they are a wrapper around views::transform with std::byteswap as the transformer.

>>> to_little_endian([0x12345678])
[0x78563412]  # if the native endian is big

constraint: The value type of r models std::integral
reference: T
value type: remove_cvref_t<T>
category: same as r (preserve contiguous)
common: when r is common
sized: when r is sized
const-iterable: when r is const-iterable
borrowed: never
constant: always

`views::to_utf{8,16,32}[_or_error](r: [T]) -> [Type | expected<Type, utf_transcoding_error>]`

(Current design as of P2728R14.)

Produce a new range that represents the conversion result from r to the specified UTF format. Also provides _or_error variant that returns expected<Type, utf_transcoding_error> to represent the specific error encountered.

>>> to_utf32(u8"🙂")
U"🙂"
>>> to_utf32(u8"🙂" | take(3))
U"�"  # Replacement character when facing invalid code units
>>> to_utf32_or_error(u8"🙂" | take(3))
[unexpected{truncated_utf8_sequence}]

constraint: T is one of cv char{8,16,32}_t
reference: charN_t for to_utfN, expected<charN_t, utf_transcoding_error> for to_utfN_or_error (prvalue range!)
value type: same as reference
category: at most bidirectional
common: when r is common
sized: when r is sized, its value type is char32_t, and using to_utf32
const-iterable: when r is const-iterable and either const R is input and not forward, or r's value type is char32_t
borrowed: when r is borrowed
constant: always

Other Standard Views

`std::filesystem::path_view : [const path_view_component&]`

(Current design as of P1030R8.)

path_view represents a trivially copyable view of explicitly unencoded or encoded character sequences in the format of a native or generic filesystem path. When iterated, it yields a path_view_component that represents a part of a path not separated by path separators.

>>> path_view("/foo/bar")
["foo", "bar"]

reference: const path_view_component&
value type: path_view_component
category: bidirectional
common: always
sized: never
const-iterable: always
borrowed: never
constant: always

`std::basic_cstring_view<charT[, traits[, Alloc]]>: [charT&]`

(Current design as of P3655R3.)

A lightweight view of a constant contiguous sequence of charTs (i.e. a string) with guaranteed null (\0) termination. Can view C strings (null-terminated const charT*), std::basic_string, and many more.

constraint: charT must be char-like (non-array trivial standard-layout type), and traits must be a character trait
reference: charT&
value type: charT
category: contiguous
common: always
sized: always
const-iterable: always
borrowed: always
constant: always

String Interpolation For C++: Going Down The Rabbit Hole

Wed, 10 Aug 2022 00:00:00 GMT

Recently, EWG reviewed P1819R0 Interpolated String Literal, igniting a new round of discussion on the possibility of adding string interpolation into C++. The review results were quite split, and a lot of contentious issues were polled with no consensus in either direction. Therefore, I want to write a post about all the subtle issues in the idea, and conduct a survey on how existing languages handle the issue, to try to converge on an agreed way for C++ to go forward. This is not a proposal, on its own, but may form as a base reading material for future revisions of P1819 or other proposals.

Motivation

What is string interpolation?

The term "string interpolation", at least in this post, refers solely to the feature that allow you to put placeholders inside a string literals, which are replaced with values when evaluating. For example, in Python:

apple = 4
print(f"I have {apple} apples.")  # Output: I have 4 apples.

[!NOTE] In some setting, string interpolation can have an extended meaning in which feature like string concatenation (possibly with 1 + " apple"-like autoboxing) and formatting (std::format and str.format) being included; in this post I want to restrain the term to the most strict meaning.

Why?

Every EWG and LEWG direction poll are worded very interestingly:

Given our time is limited, and our resources are scarce, EWG encourages further work in the direction of PXXXX?

Intentionally, WG21 groups are using these kind of wording to encourage turning down new proposals, as we must be very caution to add new feature into the already-complex-enough-language-mess that is C++. So is there a compelling reason to add yet another kind of string literal into C++?

I think there is.

Being used to these "f-strings" in Python, I found them shine especially bright in the context of debugging and logging. For example:

def connect(ip: str, port: int) -> None:
    print(f"Connecting to {ip}:{port}...")

for i in range(1000):
    print(f"[{i:3}/1000] Result = {result()}...")

# Output:
# [  1/1000] Result = 0.1...
# [  2/1000] Result = 0.3...
# ...

It is also useful in constructing strings that embed other information, such as __repr__/__str__ methods:

class Student:
    def __init__(self, name: str, age: int) -> None:
        self.name, self.age = name, age

    def __repr__(self) -> str:
        return f'<Student {self.name} with age {self.age}>'

But don't we already have `std::format`?

Yes, and I'm also aware that there is proposals to add constexpr formatting capabilities to std::format. However, std::format, as a library feature, does not come close to the user-friendliness and convenience brought by string interpolation. Compare:

std::format("<Student {} with age {}>", name, age);
f"<Student {name} with age {age}>"

I do think that interpolated literals bring the variables and expressions to be replaced directly into the place they belong. In the formatting example, we still need to manually map the positioning of {}s and variables in our mind. It is even worse if we specify positional argument in std::format, as we need to manually re-position all the variables.

Of course, this is not to say that string interpolation is a direct replacement of std::format. There is still the advantage of i18n localized formatted strings, in which we can provide {0} {1} in one language and {1} {0} in another language where grammar were reversed. Another advantage is the ability of repeating positional specifier to repeat a variable.

Both EWGI and EWG had expressed support in a future C++ string interpolation facility, so it is worthwhile to have a look at how other language did it, and find a good way for C++ to process forward.

EWGI (2019-07 Cologne): Spend committee time on this vs other proposals given that time is limited?

SF	F	N	A	SA
3	5	2	2	0

EWG (2022-08-04): Given our time is limited, and our resources are scarce, EWG Encourages further work in the direction of P1819.

SF	F	N	A	SA
3	5	3	0	0

Result: Consensus

Survey

At a glance, string interpolation seems a pretty simple feature: just factor out all the expressions and rewrite to a std::format call, right? However, there are a surprisingly large number of subtle issues involved in this concept, with most of them no clear answer. Therefore, I want to take a practical approach, or what WG21 often describe as "standardizing existing practice"... take a look at all the language that already have string interpolation ability, and look at how they solve the issues.

The language chosen are taken from the string interpolation Wikipedia page, with a total of 27 different languages: ABAP, Bash, Boo, C#, ColdFusion, CoffeeScript, Dart, Groovy, Haxe, JavaScript, Julia, Kotlin, Nemerle, Nim, Nix, ParaSail, Perl, PHP, Python, Ruby, Rust, Scala, Sciter, Swift, Tcl, TypeScript and Visual Basic.

Language	Mode	Syntax	Expression	Format	Link
ABAP	Dynamic (DSL)	`	{...}	`	✅
Bash	Dynamic	`"$..."`, `"${...}"`	❌	Many	Shell Parameter Expansion
Boo	Dynamic	`"$..."`, `"$(...)"`	✅	❌	String Interpolation
C#	Static (VM)	`$"{...}"`	✅	`{...,...:...}`	String Interpolation
ColdFusion	Dynamic	`"#...#"`	✅	❌	Parsed by Server
CoffeeScript	Dynamic	`"#{...}"`	✅	❌	Strings
Dart	Static (VM)	`'$...'`, `'${...}'`	✅	❌	Strings
Groovy	Both	`"$..."`, `"${...}"`	✅	❌	GString Interpolation
Haxe	Static (VM)	`'$...'`, `'${...}'`	✅	❌	String Interpolation
JavaScript	Dynamic	`${...}`	✅	❌	Template Literals
Julia	Dynamic	`"$..."`, `"$(...)"`	✅	❌	String Interpolation
Kotlin	Static (VM)	`"$..."`, `"${...}"`	✅	❌	String Templates
Nemerle	Static (VM)	`$"$..."`, `$"$(...)"`	✅	❌	String Interpolation
Nim	Static	`fmt"{...}"`, `&"{...}"`	✅	`{...[=]:...}`	std/strformat Module
Nix	Dynamic (DSL)	`"${...}"`	✅	❌	Nix Values: Antiquotation
ParaSail	Both	"`(...)`"	✅	❌	ParaSail Reference Manual
Perl	Dynamic	`"$..."`, `"@{...}"`	Only Array	❌	Array Interpolation
PHP	Dynamic	`"$..."`, `"{...}"`	✅	❌	Variable Parsing
Python	Dynamic	`f"{...}"`	✅	`{...[=]!.:...}`	Formatted String Literals
Ruby	Dynamic	`"#{...}"`	✅	❌	String Literals
Rust	Static	`println!("{...}")`	❌	`{...:...}`	Named Parameters
Scala	Static (VM)	`s"$..."`, `s"${...}"`	✅	❌	String Interpolation
Sciter	Dynamic (DSL)	`$fun({...})`	✅	❌	Stringizer Functions
Swift	Static	`"\(...)"`	✅	❌	String Interpolation
Tcl	Dynamic	`"$..."`	❌	❌	Variable Substitution
TypeScript	Dynamic	`${...}`	✅	❌	Same as JavaScript
Visual Basic	Static (VM)	`$"{...}"`	✅	`{...,...:...}`	Interpolated Strings

Syntax Design

Big Picture

First, let's have a look at the general syntax components of a interpolated string literal. They, in general, looks somewhat like this:

f"Other things {myVar:.2} other things"
| ^^^^^^^^^^^^^||||||||||^^^^^^^^^^^^^ string component
|              ^||||||||^ delimeter
|               |||||^^^ formatter
|               ^^^^^ expression
^ introducer

Such literals usually composed of five parts: introducer (some language use special quotation mark like backticks, those count as introducer too), expression, formatter, delimeter, and string component. Often, some parts may be missing (like language that does not support formatting will not have formatter), but in this post we will take a look at each of the components, and their different appearance in each language.

Let's break down the easy part first. The string component is, obviously, the same for all language, these are just regular strings. Other parts are much more complicated, and will be discussed from inside to outside.

Expression

Expression is the part where you specify the variables or expressions that you want to substitute in. There, most language just simply agrees that any expression can be put here, for example:

apple = 3
print(f"I have {apple} apples.")  # I have 3 apples.
print(f"I have {apple + 1} apples.")  # I have 4 apples.

Notice that often, arbitrary expression support is required for convenience of this feature (which is really all it is about, it is just a syntactic sugar), for example apples[0], get_apples() being substituted are very common case that appears in many real-world code. Which is why most language agree that any expression can appear here.

However, some language take a different route: only allow a variable name here, nothing else. Or in C++-speak, only allow a single id-expression here:

let apple = 3;
println!("I have {apple} apples.");  // Okay
println!("I have {apple + 1} apples.");  // Error!

On surface, this seems an arbitrary restriction, and really had prevented some useful use case like subscripting and function call. Natuarally, only a handful of language take this route. In the above table we can see that only Bash, Tcl and Rust have this restriction, while Bash and Tcl are both dynamic scripting language that naturally only support $variable as variable substitution and nothing else. This leaves Rust as the only language that only support variable substitution, and in RFC 2795, the author explained the rationale:

If any expressions beyond identifiers become accepted in format strings, then the RFC author expects that users will inevitably ask "why is my particular expression not accepted?". This could lead to feature creep, and before long perhaps the following might become valid Rust:

println!("hello { if self.foo { &self.person } else { &self.other_person } }");

This no longer seems easily readable to the RFC author.

In short, the reason that Rust does not allow anything above variable name is that allowing arbitrary expression may leads to very complex expression being present, which is a bad style as the string is no longer easily readable. This is a real problem, as many people may have written None-related conditionals in Python:

result = get_int()  # may return int or None
print(f"Got {result if result is not None else 0} as result.")

This had already becoming hard to read, and if we introduce the same syntax into C++, the problem may become worse:

std::optional<int> get_int();
auto result = get_int();
std::println(f"Got { get_int().transform([](auto a){ return a * 2; }).value_or(0) } as result.");

However, I personally don't think that this potential danger is worth discarding the great benefit that allowing get_int(), arr[2] etc had given us. The author of PEP 498 had rightfully pointed out regarding this issue:

While it’s true that very ugly expressions could be included in the f-strings, this PEP takes the position that such uses should be addressed in a linter or code review.

I personally agree that this should just be a Core Guideline issue to not use long placeholders. In EWG review of P1819R0 on 2022-08-04, WG21 also agrees with the decision that a future string interpolation facility in C++ should support arbitrary expression:

EWG encourages more work in the direction of supporting arbitrary expressions, instead of just ID expressions.

SF	F	N	A	SA
4	3	2	0	1

Result: Consensus

So I think that this issue had been solved.

Formatter

The formatter component refer to the additional specifier after the expression, to format it. For example, we can add some specification to make the expression result to have a fixed width:

for i in range(1000):
    print(f"[{i:3}/1000] Hello!")
# Print:
# [  1/1000] Hello!
# [  2/1000] Hello!
# ...

These formatter specifiers had had a long history. Their first common-known appearance is probably the C printf/scanf family of functions, in where type specifier like %d and fill/width specifier like %03d are introduced. Later, Python improved these specifier by changing to a {} format, eliminating the need for always specifying type specifiers, and also changed alignment specifier to a more straightforward <>^ system. This new type of formatter had been adopted by many languages coming forward, including C++ std::format.

However, contrary to the general acceptance of arbitrary expression for the expression part, there are very few languages that actually support formatters in string interpolation. From the above table, we can see that only 6 languages (Bash, C#, Nim, Python, Rust, Visual Basic) support some kind of formatter. There are two main reason for the general reluctancy of formatters:

Formatters often make the interpolation string looks more complicated and hard to read. Similar to the situation of complicated expression, complex formatter can also hinder readability:

vector ints{65192, 65535, 766, 8687, 65524, 14386};
std::println(f"Your IPv6 address is {ints:nd[:]:04x}.");
// Your IPv6 address is fea8:ffff:02fe:21ef:fff4:3832.

Interpolated string literals with formatters are harder to implement than those without. Among the language that does not support formatter, many are reluctant to support it because they didn't even have a str.format-like function, thus do not have any existing facility to utilize formatters. Furthermore, even among those who has formatting functions already, a simple interpolation without formatter, like f"I have {apple} apples", can simply be translated into a concatenation

"I have " + apple + " apples"

which (assuming toString()'s existence or implicit calling of such method) can be an easy task for the compiler. However, with formatter present, either we must resort to Nim's approach to translate to something like

"I have" + std::format("{:02}", apple) + " apples"

Or translate directly into a single big format call:

std::format("I have {:02} apples", apple)

However, both reason does not apply to C++ at all. In C++, we already have the formatting infrastructure provided by std::format, so we can simply support the same format-specifier and all is well. Also, even if we restrict to no-formatter mode, we still cannot use simple concatenation to translate interpolated strings, because in C++ we have no general toString() method at all! std::to_string only works for arithmetic types, so the only general way we can get a string from any object is through std::format("{}", obj), which basically means that the support for formatters is already there, and dropping them will have absolutely no performance gain. As for readability, I support the same argument as ones for the complicated expression concern, namely this is a code review issue, not an issue that prevent us to support even the simplest formatting specifier.

Having decided that C++ have sufficient reason to support formatters, let's have a look at their syntax in existing language. For C# and VB, their .NET format specifiers are not taken from Python, and instead have taken a form that looks like {,[align]:[type][prec]}, so their string interpolation facility also support the same {...,...:...} format. This is, in fact, consistent with Rust, Python and Nim's {...:...} choice, because the only difference is that C# and VB move the [align] part from after the colon to before the colon. Apart from these standard specifiers, there are a few creative additions for Python and Nim. Python allow a !s, !r or !a specifier to appear immediately before the colon, whose effect is to call str(), repr() or ascii() before formatting. In PEP 498, the author actually admitted that this is just for compatibility with str.format, and on their own are redundant specifiers:

The !s, !r, and !a conversions are not strictly required. Because arbitrary expressions are allowed inside the f-strings, [...] However, !s, !r, and !a are supported by this PEP in order to minimize the differences with str.format(). !s, !r, and !a are required in str.format() because it does not allow the execution of arbitrary expressions.

Therefore, since in C++ we don't have such tradition in std::format, and there is no general string-conversion function like str() anyway, I see no reason to introduce !... part into C++ interpolated strings. However, another addition introduced by both Python and Nim, the = part before the colon, is more interesting. The effect of such a = is to introduce a debugging format, in which the expression text will be displayed alongside its value:

a = 3
print(f"I have {a=}")  # I have a=3
print(f"I have {a = }")  # I have a = 3
print(f"I have {a  =:02}")  # I have a  =03

Basically, this is a shorthand for the common practice of var = value trick in debugging prints. In my personal opinion, I think that this specifier is very appealing, but at the same time it can be added later, after general interpolation is introduced (in Python, = is added two versions after f-strings anyway). Also, this specifier has its own problem in C++ (will be described below in the issues section), so I suggest holding off its addition into separate proposal.

In conclusion, I suggest that C++ string interpolation facility should support format-specifiers, as they are naturally supported as a result of the implementation strategy, and also the formatter format should (for now) simply be {...:...}, the same as std::format. The Python/Nim = specifier can be added later in a separate proposal, once its issues are solved. (Technically, given WG21's favor for minimal proposals these days, support for formatters can also be added later, as colons are not used much in C++ expressions; however I felt like that would be too minimal for a first proposal).

Delimeter

Delimeters are a natural requirement to the proposed interpolation syntax, especially for those language that support interpolating arbitrary expressions. Even for those that only support interpolating variables, the possibility of ambiguity still calls for a need of delimeter:

fruit=apple
echo "I want some $fruit"  # I want some apple
echo "I want some $fruits"  # I want some (unknown variable not displayed)
echo "I want some ${fruit}s"  # I want some apples

However, there is a catch: many languages (including Bash) support both a mode without delimeter and a mode with one, to give more convenience to the user. The general rule here is that without a delimeter, the expression part will start from the introducer and match greedily, often only stop when meeting a whitespace or end of string. So in the above example, $fruit can work but $fruits cannot. These languages with two modes are recorded as none plus some delimeter type below, where none signals the $fruit case without delimeter.

As for the delimeter themselves, there are many choice:

None + {}: (8) Bash, Dart, Groovy, Haxe, Kotlin, Perl, PHP, Scala
{} only: (12) ABAP, C#, CoffeeScript, JavaScript, Nim, Nix, Python, Ruby, Rust, Sciter, TypeScript, Visual Basic
None + (): (3) Boo, Julia, Nemerle
() only: (2) ParaSail, Swift
# only: (1) ColdFusion
No delimeter (only support greedy variable interpolation): (1) Tcl

We can easily see that there are only two common choice of delimeter: {} and (). In which {} have 20 language users, while () only have 5, so {} is the overwhelmingly favorite. Also, C++ std::format already used {} as delimeter, so I think that there should be no controversy on the choice for C++: just continue to use {} as delimeter. (One can also argue that both {} and () have had precedent in C++, with the latter being the delimeter used for raw strings; but I think consistency with std::format is much more important.) However, noted that in C++ we have to use a prefix introducer (more on this below), so we cannot introduce the greedy no-delimeter matching facility, forcing C++ to be in the {} only group (it is the group with most people anyway).

Introducer

Now comes the fun part.

Introducers are also one of the required feature of any string interpolation facility, as you have to distinguish interpolated string from regular string in some way to process them differently. However, there are four general categories of languages with regard to introducers:

Prefix, in which introducer are placed before the string, like f"something"
Adjacent, in which introducer are placed immediately before delimeter, like "something ${var}"
Quote, in which introducer are the quotes themselves (i.e. special quote is used), like |something|
Function, in which interpolation is only available as parameters to certain functions

Adjacent is more common in scripting or dynamic languages, in which variables are often also referred as $var. It is also worth noting that the aforementioned greedy no-delimeter substitution feature is only available with language in the adjacent group. The languages can be categorized as:

Prefix: (4) C#, Visual Basic (both $), Python (f), Nim (fmt and &)
Adjacent $: (9) Bash, Boo, Dart, Groovy, Haxe, Julia, Kotlin, Nix, Tcl
Adjacent #: (3) ColdFusion (double #), CoffeeScript, Ruby
Adjacent other: (4) ParaSail (double `), Perl ($ and @), PHP ($ or None), Swift (\)
Both Adjacent and Prefix: (2) Nemerle (both $), Scala (s prefix and $ adjacent)
Quote: (3) ABAP (|), JavaScript, TypeScript (both `)
Function: (2) Rust (println! family), Sciter (anything start with $)

Overall there are 6 Prefix, 18 Adjacent, 3 Quote and 2 Function, with Adjacent group being the overwhelmingly favorite. The reason for that result, I think, is that generally we want the interpolated (substituted) part to be as distinct as possible from the rest of the string, in order for reader to quickly realize that this part will be substituted, and add an introducer here can be a good way to remind them. Also, the Adjacent placement also enable the possibility of no-delimeter, which over half of the 18 languages had utilized.

However, the Adjacent group have its own great limitation, which makes it unsuitable for C++: backward compatibility. We already have strings that contain $ in C++, and changing it to perform interpolation is simply a non-starter because it will break way too much legacy code. All the Adjacent group languages have had interpolation since their first version, so there is no risk of breaking code. However, for C++, we must reject all Adjacent approach... except for one! The Swift Adjacent ("\(...)") is actually still viable for C++, given that \( is an unused escape sequence. However, currently all major C++ compilers will only produce a warning for unknown escape sequences, and then proceed as if the backslash isn't here. Therefore if we want to be secure, we must first deprecate \( for at least one standard, and then reuse it. (Given that there is very unlikely to be large number of code with this escape outside in the wild, I do think that we can skip the deprecation period and directly reuse this as interpolation; however the Swift syntax does not look very appealing anyway). For those reasons, I will suggest that the whole Adjacent group is unsuitable for C++.

The Function group also deserves a closer look. For Rust, the println! family (to be precise, the target is actually the format_args! family) are already implemented as macros, which means that it is possible to customize their argument behavior as a library feature, no need for core language change. Therefore, Rust can happily limit the interpolation scope to only the format_args! family, and unuseable for anything else. Sciter also took an interesting strategy: any function with name starting from $ will treats its argument as literal string, and anything inside {} inside such an argument will simply be left out unquoted:

var bodyDiv = self.$(div#body);
// equivalent to
var bodyDiv = self.$("div#body");

var nthDiv = self.$(div:nth-child({n}));
// equivalent to
var nthDiv = self.$("div:nth-child(", n, ")")

This way, the function can itself concatenate all the argument to form the interpolated string. However, both languages' approach cannot apply to C++: std::format is not a macro, and we do not want to limit string interpolation to std::format and std::print family anyway; and introducing $-functions will simply be too much a change for C++ to handle. It is viable, but it would simply be too radical, as the whole grammar need to change dramatically to allow this.

This only leaves Prefix and Quote as routes for C++. Both of these routes are viable, but I want to argue that Quote group have its own inherent limitation in C++ too: no existing practice. In C++, we have always had only two kind of quotations, single and double for char and const char*. Introducing the third kind of quotation for solely the purpose of string interpolation seems a bit weird and aggressive, and also having a third kind of quotation without a third kind of type (it will evaluate to std::string probably anyway) also seems weird to me. On the contrary, in C++ we have had prefix specifiers for years now (encoding and raw strings), so adding a new kind of prefix specifier is not a radical change. Therefore, I personally support Prefix as the way for C++ to go.

However, inside the Prefix group the syntax is very split in different languages (I'm actually surprised that no one else used f-strings). C++ will face a choice here:

$, the advantage is that there will be absolutely no possibility of breaking existing code, while the disadvantage will be to introduce a new novel syntax ($ have no appearance in C++ yet)
f, the advantage is that this will require no novel syntax learning, it is just similar to u and R prefix, convey clearly the "formatting" meaning, and also does not introduce new symbol into C++ glossary; however the disadvantage is that there is a small possibility of breaking existing code with macro named f
Other one-character prefix, the analyze is same with f, with the additional disadvantage that it has no clear link with "formatting" meaning
fmt (or format, etc), the advantage is that the meaning is conveyed most clearly, however a big disadvantage is that this will be more clumsy to type (shorter typing is the sole reason we introduce string interpolation anyway), and also have a bigger possibility of macro conflicting.

Overall, I don't see a clear winner. Personally, I think that f makes the most sense for C++, as it has the least disadvantages among the options (macro named f is increasingly rare anyway, and this problem is also faced by u and R prefix too, they solved it, kinda). $ can be a close second or even first if one day C++ introduced an operator with $ in it so that it is no longer novel, and other choice I think is clearly worse.

So, in conclusion, my personal suggestion for C++ is the f"{...}" syntax, with support for format-specifiers (or in other words, copy Python).

General design issues

These are the issues that applys to any string interpolation facility, not unique to C++.

Implementation: eager or lazy?

Escaping behaviour

Now this is the most difficult and contentious part of any such facility.

Customization

Issues specifically for C++

Of course, being one of the most complex language in the world, a string interpolation facility for C++ will face its own bunch of issues, specifically because of its interaction with other features or limitations of C++.

Availability of `@`, `$` and `

What is the type of interpolated string?

Macro conflict

Ambiguity of `=` specifier

(Non-existent?) issues with format-specifier support

Concatenation

Interaction with other prefix

Interaction with UDL

`constexpr` interpolated strings

Translation stage

Implementation difficulty

Wording

[!NOTE] This wording is just an initial attempt and is known to be incorrect and incomplete, if this were to be a proposal, the wording is probably in need of an overhaul. Wording is based on N5054.

How are my WG21 proposals doing?

Thu, 07 Jul 2022 00:00:00 GMT

I have written several proposals for the ISO C++ committee (WG21). They are all written in Bikeshed so that automatic proposal referencing can be used, and the resulting proposal looks nicer. All proposal source code are stored in the wg21-papers repo.

P2549: `std::unexpected<E>` should have `error()` as member accessor

Audience: LWG
Target: C++23
Revisions: R0, R1
Current Status: Approved for C++23

This is my first ever proposal to WG21. It is a simple renaming proposal, proposing to fix an inconsistency in the std::expected paper, such that std::expected::value() returns the normal value but std::unexpected::value() actually returns the error (abnormal) value.

History:

2022-07-25: R1 approved for inclusion in C++23 in the 2022-07-25 WG21 plenary. (Plenary -> Approved)
2022-07-08: R1 seen by LWG, approved for plenary. (Stage 3 -> Plenary)
2022-06-22: R0 passed 2022-05 LEWG Electronic Poll. (EP -> Stage 3)
2022-06-20: P2549R1 shipped in the 2022-07 Mailing.
2022-03-01: R0 seen by LEWG, approved for EP. (Stage 2 -> EP)
2022-02-13: P2549R0 shipped in the 2022-02 Mailing.

P2573: `= delete("should have a reason");`

Audience: CWG
Target: C++26
Revisions: R0, R1, R2
Current Status: Approved for C++26

C++20 added [[nodiscard("with reason")]], together with [[deprecated]] and static_assert, forming the group of "diagnostic with reason" constructs in C++. = delete functions often have a reason to delete themselves (alternative exist, prevent rvalue dangling, etc), so this proposal proposed adding a reason clause to it too.

History:

2024-04-15: P2573R2 shipped in the 2024-04 post-Tokyo Mailing.
2024-03-23: R2 approved for inclusion in C++26 in the Tokyo (2024-03) WG21 plenary. (Plenary -> Approved)
2024-03-22: R2 seen by CWG in Tokyo (2024-03), approved for plenary. (Stage 3 -> Plenary)
2024-03-19: R1 seen by EWG in Tokyo (2024-03), approved for CWG. (Stage 2 -> Stage 3)
2023-12-15: P2573R1 shipped in the 2023-12 post-Kona Mailing.
2023-11-06: Backtrack to Stage 1, then D2573R1 seen by EWGI in Kona (2023-11), approved for EWG. (Stage 2 -> Stage 1 -> Stage 2)
2022-04-12: P2573R0 shipped in the 2022-04 Mailing.

P2613: Add the missing `empty()` to `mdspan`

Audience: LEWG, LWG
Target: C++23
Revisions: R0, R1
Current Status: Approved for C++23

This is a very rushed paper. In mid-June, I spotted a bunch of problems with the about-to-be-approved mdspan paper, and opened a PR, wanting to add noexcept to some member functions, and also add the missing mdspan::empty(). In the following LWG small-group review session, noexcept additions are approved, but a new function need its own proposal to pass through LEWG review again. Thus the paper.

History:

2022-07-25: R1 approved for inclusion in C++23 in the 2022-07-25 WG21 plenary. (Plenary -> Approved)
2022-07-23: R1 passed 2022-07 LEWG Electronic Poll. (EP -> Plenary)
2022-07-08: R1 seen by LWG, approved for plenary. (Stage 3 preapproval)
2022-06-28: R0 seen by LEWG (of which I forgot to attend the telecon, sorry!), approved for EP. (Stage 2 -> EP)
2022-06-25: P2613R1 shipped in the 2022-07 Mailing (LWG request a one-line wording change, so this is quick).
2022-06-23: P2613R0 shipped in the 2022-06 Mailing (as a late paper).

P3351: `views::scan`

Audience: LEWG
Target: C++29
Revisions: R0, R1, R2, R3, R4
Current Status: Stage 2

This paper proposes the views::scan range adaptor, which takes a range and a function that takes the current element and the current state as parameters. Basically, views::scan is a lazy view version of std::inclusive_scan, or views::transform with a stateful function.

History:

2026-04-27: P3351R4 shipped in the 2026-05 pre-Brno Mailing.
2025-11-04: R3 seen by SG9 in Kona (2025-11), approved for LEWG. (Stage 1 -> Stage 2)
2025-09-30: P3351R3 shipped in the 2025-10 pre-Kona Mailing.
2025-01-12: P3351R2 shipped in the 2025-01 pre-Hagenberg Mailing.
2024-09-24: P3351R1 shipped in the 2024-10 pre-Wrocław Mailing.
2024-07-08: P3351R0 shipped in the 2024-07 post-St. Louis Mailing.

P3423: Extending User-Generated Diagnostic Messages

Audience: CWG
Target: C++29
Revisions: R0, R1, R2
Current Status: Stage 3

During Varna (2023-06), P2741R3 had been adopted into the C++26 working draft, which gave static_assert the ability to accept a user-generated string-like object as the message parameter. This extension allowed the user of static_assert to provide a more precise error message in compile time, thus significantly increasing the user-friendliness of libraries. This proposal, therefore, proposes to unify the language by allowing other constructs in the language that currently accept a message parameter, namely [[nodiscard]], [[deprecated]], and = delete, to also allow a user-generated string-like object as the provided message.

History:

2026-07-21: P3423R2 shipped in the 2026-08 Mailing.
2025-11-04: R1 seen by EWG in Kona (2025-11), approved for CWG. (Stage 2 -> Stage 3)
2025-01-12: P3423R1 shipped in the 2025-01 pre-Hagenberg Mailing.
2024-11-22: R0 seen by EWGI in Wrocław (2024-11), approved for EWG. (Stage 1 -> Stage 2)
2024-10-14: P3423R0 shipped in the 2024-10 pre-Wrocław Mailing.

P3831: Contract Labels Should Use Annotation Syntax

Audience: SG21
Target: P3400R1
Revisions: R0
Current Status: Rejected

Contract labels (P3400R1) are one of the most important extensions proposed to C++26 Contracts, providing the ability to control the behavior of specific contract assertions. This proposal argues that instead of inventing a new syntax for parameterizing contract assertions, the labels should utilize the existing feature in the standard that permits this parameterization with defined semantics, namely annotations (P3394R4).

History:

2025-09-07: P3831R0 shipped in the 2025-09 Mailing.
2026-06-09: R0 seen by EWG in Brno (2026-06) and rejected. (Stage 1 -> Stage 2 -> Rejected)

P4205: Range-Based Searchers

Audience: SG9
Target: C++29
Revisions: R0, R1
Current Status: Stage 1

This proposal introduces std::ranges versions of the Searcher overload of the std::search algorithm, which takes a searcher object instead of an iterator pair and (optionally) a predicate. It was originally introduced for more performant specialized searching.

As customary in Ranges algorithms, this proposal also proposes Range-ified versions of the existing standard searchers, along with a concept std::searchable for better capturing the semantic requirements of standard searchers.

History:

2026-07-21: P4205R1 shipped in the 2026-08 Mailing.
2026-04-29: P4205R0 shipped in the 2026-05 pre-Brno Mailing.

P4211: Adaptors For Closed Ranges

Audience: SG9
Target: C++29
Revisions: R0
Current Status: Stage 1

This proposal introduces a family of adaptors that convert closed ranges into half-open ranges, as expected by most other standard library facilities in C++, thus providing direct support for a range model that has been fundamentally incompatible with the C++ iterator model until now.

History:

2026-05-05: P4211R0 shipped in the 2026-05 pre-Brno Mailing.

Hello World

Wed, 22 Aug 2018 00:00:00 GMT

(Automatically generated by the Alembic theme)

This is my very first blog post. I haven't written anything yet but I'm sure I have some great stories to tell.

Mick235711's Personal Website

Coroutine-Based Scope Guards

Bare Bones

Recursive Awaitable

Error Handling

Premature Return

Exception Handling

Multiple Yields

Performance

Fun With Deducing This, SMFs and = delete

Terminology

Special Member Functions

Default Constructors and Destructors

Copy/Move Constructors

Copy/Move Assignment

= default

Deducing This

What Does The Standard Say?

Implementation Divergence

Comparison of Minecraft Launchers

Launcher Selection

What, Your Favorite Launcher Is Not Here?

Comparison Table

Screenshots

Star History Charts

The Definitive Guide to Operator Overloading in C++

Basic Terminology

Basics of Operator Overloading

Transversing the Operator Zoo

Basic Idioms

Deducing This: A Retrospective and A Mistake Unfixed

Hidden Friends and the Barton-Nackman Trick

You Must Type It Three Times: SFINAE Woes

Choices and Classification

Member or Hidden Friend? A Difficult Choice

The Big Classification

The Good Four

Simple Assignment: operator=

The Basics

Automatic Generation Rules: The Rule of Three, The Rule of Five, and The Rule of Zero

When Compiler Fails: Defaulted as deleted, and why it matters

Copy-and-Swap Idiom: When and How

More Idioms

Copy-and-Move Idiom

Implementing Constructors by Assignment

A Nightmare Operator: Deal with optional<T&>

operator= That Is Not Copy/Move Assignment: Irrelevant or Optimization?

Templated operator=

Virtual operator=: Genius or Trap?

const operator=: When Is A Contradiction Useful?

swap: An Operator Disguised

The Basics: Importance of A noexcept swap

ADL swap and ranges::swap: Incomplete Solution

Member or Non-Member or Hidden Friend? A War Story

Comparison Crash Course: operator<=> and operator== (and other five)

The Basics: Primary and Secondary Comparison

Comparison Result Types and Functions

Rewritten Candidates and Reverse Rewrite

The Default Situation and The Great Separation

Spaceship Idioms: Ignoring, Reversing

Functors: Overloading operator()

static, const, Lambda, mutable, Oh My!

Stateful and Pure Functors with Standard Algorithms

Perfect-Forwarding Functors: = delete and Deducing This

Arithmetic Operators

Compound Assignment: operator@=

Simple Arithmetic: b+ b- b* / %

The Basics

By-Value or Symmetry: Pick Your Poison

Bitwise Arithmetic: | b& ~ >> <<

Increment/Decrement: A Dilemma

Prefix: operator++() and operator--()

Postfix: operator++(int) and operator--(int)

The Weirdo: Unary operator+() and operator-()

Input/Output Operator

operator>> as Stream Extractor

The Basics

Dealing with Failure

operator<< as Stream Inserter

The Basics

`= default`

Simple Assignment: `operator=`

A Nightmare Operator: Deal with `optional<T&>`

`operator=` That Is Not Copy/Move Assignment: Irrelevant or Optimization?

Templated `operator=`

Virtual `operator=`: Genius or Trap?

`const operator=`: When Is A Contradiction Useful?

`swap`: An Operator Disguised

The Basics: Importance of A `noexcept swap`

ADL `swap` and `ranges::swap`: Incomplete Solution

Comparison Crash Course: `operator<=>` and `operator==` (and other five)

Functors: Overloading `operator()`

`static`, `const`, Lambda, `mutable`, Oh My!

Perfect-Forwarding Functors: `= delete` and Deducing This

Compound Assignment: `operator@=`

Simple Arithmetic: `b+ b- b* / %`

Bitwise Arithmetic: `| b& ~ >> <<`

Prefix: `operator++()` and `operator--()`

Postfix: `operator++(int)` and `operator--(int)`

The Weirdo: Unary `operator+()` and `operator-()`

`operator>>` as Stream Extractor

`operator<<` as Stream Inserter

Migrate to `std::formatter<T>`

One-and-a-Fake Unary: `operator*()` and `operator->()`

Shallow or Deep `const`?

The Forgotten Sister: `operator->*`

A Changed Friend: `operator[]`

The Basics: `const`-Coercing Subscript and Deducing This

Deploying an Multidimensional `operator[]`

Coroutine Internals: Overloading `operator co_await`

Implementing `std::lazy<T>`

Defending Against the Dark Unary `operator&`

`&&` and `||`: Before and After C++17

Overloading `new` and `delete`: Explained

Placement `new` and `nothrow new`

Placement `delete`: The Weirdest Operator in the Standard

Overloading `new[]` and `delete[]`

The One Good Conversion: `explicit operator bool()`

An Irrelevant `!`

Templated UDL and the `constexpr std::string` Dilemma

`u*`, `->` and `++`: Disguised Core

`--`, `+=`, `-=`, and `[]`: Extending the Basic Iterator

Postfix `++ --` in C++20: A Rebellion

`explicit operator bool` for Ranges: A Twist

`u*`: Nullable, Pointer or Optional?

Deprecating and Decreasing `operator->`

`operator+` For `std::string`: A Mistake? Nightmare with `string_view`?

Three Generations of `std::less`

Three Generations of `std::function`

The Power of The `std::bind` Family

`operator&&` and `operator||`

`operator?:`: A Cure for SIMD?

Overloadable `operator^^`: Customising Reflection

A Pipeline-Rewrite Operator: `|>`

A Control-Flow Operator: `??`

A War Story on Pattern Matching and Operators (`is`, `as`, `match`, ...)

Generalized `match` and `is`: Converging Solutions