std::counte...,+=,--,-,-=(3)

okay bestie, this is std::counte...,+=,--,-,-=(3) from the C++ Standard Libary — section 3, and it's literally the manual page for the std::counted_iterator increment/decrement/advance operators. Buckle up, the title alone is a keyboard smash. 💅

💖 NAME 💖

The original NAME is std::counted_iterator::operator++,+,+=,--,-,-= - std::counted_iterator::operator++,+,+=,--,-,-= (yes, it says it twice). These are the increment, decrement, and advance operators for std::counted_iterator.

✨ Synopsis ✨

          constexpr counted_iterator& operator++();
       (1) (since C++20)
          constexpr decltype(auto) operator++( int );
       (2) (since C++20)
          constexpr counted_iterator operator++( int )
       (3) (since C++20)
              requires std::forward_iterator<I>;
          constexpr counted_iterator& operator--()
       (4) (since C++20)
              requires std::bidirectional_iterator<I>;
          constexpr counted_iterator operator--( int )
       (5) (since C++20)
              requires std::bidirectional_iterator<I>;
          constexpr counted_iterator operator+( std::iter_difference_t<I> n
          ) const
       (6) (since C++20)
              requires std::random_access_iterator<I>;
          constexpr counted_iterator& operator+=( std::iter_difference_t<I>
          n )
       (7) (since C++20)
              requires std::random_access_iterator<I>;
          constexpr counted_iterator operator-( std::iter_difference_t<I> n
          ) const
       (8) (since C++20)
              requires std::random_access_iterator<I>;
          constexpr counted_iterator& operator-=( std::iter_difference_t<I>
          n )
       (9) (since C++20)
              requires std::random_access_iterator<I>;

Increments or decrements the underlying iterator current and the distance to the end length.

⚠️ bestie, the behavior of these functions is undefined if length would be set to a minus value. That's not a cute little glitch — that's undefined behavior, periodt. 💀

1. Pre-increments by one. Equivalent to ++current; --length; return *this;.
2. Post-increments by one. Equivalent to --length; try { return current++; } catch(...) { ++length; throw; }.
3. Post-increments by one. Equivalent to counted_iterator temp{*this}; ++*this; return temp;.
4. Pre-decrements by one. Equivalent to --current; ++length; return *this;.
5. Post-decrements by one. Equivalent to counted_iterator temp{*this}; --*this; return temp;.
6. Returns an iterator adaptor which is advanced by n. Equivalent to return counted_iterator(current + n, length - n);.
7. Advances the iterator adaptor by n. Equivalent to current += n; length -= n; return *this;.
8. Returns an iterator adaptor which is advanced by -n. Equivalent to return counted_iterator(current - n, length + n);.
9. Advances the iterator adaptor by -n. Equivalent to current -= n; length += n; return *this;.

🎀 Parameters 🎀

• n — the number of positions to increment or decrement the iterator adaptor

🦋 Return value 🦋

• 1) *this
• 2,3) A copy of *this that was made before the change.
• 4) *this
• 5) A copy of *this that was made before the change.
• 6) An iterator adaptor which is advanced by n.
• 7) *this
• 8) An iterator adaptor which is advanced by -n.
• 9) *this

🌈 Example 🌈

okay this example is the whole vibe check:

        // Run this code

        #include <cassert>
        #include <initializer_list>
        #include <iterator>

        int main()
        {
            const auto v = {1, 2, 3, 4, 5, 6};
            std::counted_iterator<std::initializer_list<int>::iterator>
       it1{v.begin(), 5};

            ++it1;              assert(*it1 == 2 && it1.count() == 4); // (1)
            auto it2 = it1++;   assert(*it2 == 2 && *it1 == 3);        // (3)
            --it1;              assert(*it1 == 2 && it1.count() == 4); // (4)
            auto it3 = it1--;   assert(*it3 == 2 && *it1 == 1);        // (5)
            auto it4 = it1 + 3; assert(*it4 == 4 && it4.count() == 2); // (6)
            auto it5 = it4 - 3; assert(*it5 == 1 && it5.count() == 5); // (8)
            it1 += 3;           assert(*it1 == 4 && it1.count() == 2); // (7)
            it1 -= 3;           assert(*it1 == 1 && it1.count() == 5); // (9)
        }

👑 See also 👑

• operator+ — advances the iterator (C++20) (function template)
• operator- — computes the distance between two iterator adaptors (C++20) (function template)

mwah 💋 — this cutie came from source/version http://cppreference.com, dated 2024.06.10.