std::regex_...gex_iterator(3)

okay bestie, this is the std::regex_...gex_iterator(3) page from the C++ Standard Library manual, and we're talking about the std::regex_iterator::regex_iterator constructor. Yes, the name is giving “I am my own icon” — constructor realness 💅.

🌸 NAME 🌸

• std::regex_iterator::regex_iterator — std::regex_iterator::regex_iterator. That's the constructor, bestie; it's literally named after the class and we respect it.

🌀 Synopsis 🌀

          regex_iterator();
       (1) (since C++11)
          regex_iterator( BidirIt a, BidirIt b,

                          const regex_type& re,
       (2) (since C++11)
                          std::regex_constants::match_flag_type m =

                              std::regex_constants::match_default );
          regex_iterator( const regex_iterator& );
       (3) (since C++11)
          regex_iterator( BidirIt, BidirIt,

                          const regex_type&&,
                          std::regex_constants::match_flag_type =
       (4) (since C++11)

                              std::regex_constants::match_default ) =
          delete;

Constructs a new regex_iterator. All four overloads are (since C++11), and they are doing very different things:

• (1) — default constructor. Constructs an end-of-sequence iterator.
• (2) — constructs a regex_iterator from the sequence of characters [a, b), the regular expression re, and a flag m that governs matching behavior. This constructor performs an initial call to std::regex_search with this data. If the result of this initial call is false, *this is set to an end-of-sequence iterator.
• (3) — copies a regex_iterator.
• (4) — the overload (2) is not allowed to be called with a temporary regex, since the returned iterator would be immediately invalidated.

temporary regex + overload (2) = immediately invalidated iterator, which is why overload (4) is = delete;. The compiler is literally guarding the vibe 💀✨

🎀 Parameters 🎀

• a — LegacyBidirectionalIterator to the beginning of the target character sequence.
• b — LegacyBidirectionalIterator to the end of the target character sequence.
• re — regular expression used to search the target character sequence.
• m — flags that govern the behavior of re.

🌈 Example 🌈

        // Run this code

        #include <iostream>
        #include <regex>
        #include <string_view>

        int main()
        {
            constexpr std::string_view str{R"(
                #ONE: *p = &Mass;
                #Two: MOV %rd, 42
            )"};
            const std::regex re("[a-w]");

            // create regex_iterator, overload (2)
            auto it = std::regex_iterator<std::string_view::iterator>
            {
                str.cbegin(), str.cend(),
                re // re is lvalue; if an immediate expression was used
                   // instead, e.g. std::regex{"[a-z]"}, this would
                   // produce an error since overload (4) is deleted
            };

            for (decltype(it) last /* overload (1) */; it != last; ++it)
                std::cout << (*it).str();
            std::cout << '\n';
        }

Output:

password

🩹 Defect reports 🩹

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• DR: LWG 2332
  • Applied to: C++11
  • Behavior as published: a regex_iterator constructed from a temporary basic_regex became invalid immediately
  • Correct behavior: such construction is disallowed via a deleted overload

That's the whole page, bestie — source/version: cppreference.com, dated 2024.06.10. Go forth and let your iterators slay 💅✨🫶