std::time_g...get_weekday(3)

💖 NAME 💖

std::time_get::get_weekday, std::time_get::do_get_weekday — literally std::time_get::get_weekday, std::time_get::do_get_weekday. Bestie, this is the manual page for std::time_g...get_weekday(3) from the C++ Standard Libary (yes, that's the spelling in the header, I'm preserving it 💅).

---

✨ Synopsis ✨

Defined in header <locale>
public:

iter_type get_weekday( iter_type beg, iter_type end, std::ios_base&
str,        (1)

std::ios_base::iostate& err, std::tm* t )
const;
protected:

virtual iter_type do_get_weekday( iter_type beg, iter_type end,
std::ios_base&
str,
(2)

std::ios_base::iostate& err,
std::tm* t )
const;

1. The public member function — it calls the protected virtual member function do_get_weekday of the most derived class.
2. The protected virtual one — it reads successive characters from the sequence [beg, end) and parses out the weekday name (possibly abbreviated), using the default format for weekdays expected by this locale. That format is the same as "%a" as used by the functions std::get_time, time_get::get, and the POSIX function strptime().

If it finds an abbreviated name followed by characters that are valid for the full name, it keeps reading until it consumes all the characters for the full name or finds a character that is not expected. In that case, parsing fails even if the first few characters were a valid abbreviation. 😭 No cap, that's the rule.

The parsed weekday is stored in the std::tm field t->tm_wday.

If the end iterator is reached before a valid weekday name is read, the function sets std::ios_base::eofbit in err. If a parsing error is encountered, the function sets std::ios_base::failbit in err.

---

🌸 Parameters 🌸

• beg — iterator designating the start of the sequence to parse
• end — one past the end iterator for the sequence to parse
• str — a stream object that this function uses to obtain locale facets when needed, e.g. std::ctype to skip whitespace or std::collate to compare strings
• err — stream error flags object that is modified by this function to indicate errors
• t — pointer to the std::tm object that will hold the result of this function call

---

🎀 Return value 🎀

Iterator pointing one past the last character in [beg, end) that was recognized as a part of a valid weekday name. That's the whole return vibe.

---

🦋 Notes 🦋

This function is usually case-insensitive.

If a parsing error is encountered, most implementations of this function leave *t unmodified. So don't count on *t getting a little treat on failure, okay?

---

🔥 Example 🔥

// Run this code

#include <initializer_list>
#include <iostream>
#include <iterator>
#include <locale>
#include <sstream>
#include <string_view>

void try_get_wday(std::string_view s)
{
    std::cout << "Parsing the weekday out of '" << s
              << "' in the locale " << std::locale().name() << '\n';
    std::istringstream str{s.data()};
    std::ios_base::iostate err{std::ios_base::goodbit};

    std::tm t;
    std::time_get<char> const& facet =
std::use_facet<std::time_get<char>>(str.getloc());
    std::istreambuf_iterator<char> ret = facet.get_weekday({str}, {},
str, err, &t);
    str.setstate(err);
    std::istreambuf_iterator<char> last{};

    if (str)
    {
        std::cout << "Successfully parsed, weekday number is " <<
t.tm_wday;

        if (ret != last)
        {
            std::cout << " Remaining content: ";
            std::copy(ret, last,
std::ostreambuf_iterator<char>(std::cout));
        }
        else
            std::cout << " the input was fully consumed";
    }
    else
    {
        std::cout << "Parse failed. Unparsed string: ";
        std::copy(ret, last,
std::ostreambuf_iterator<char>(std::cout));
    }

    std::cout << '\n';
}

void demo(std::string_view locale_name,
std::initializer_list<std::string_view>&& data)
{
    try
    {
        std::locale::global(std::locale(locale_name.data()));
    }
    catch (std::runtime_error const& ex)
    {
        std::cout << "Cannot setup locale: " << locale_name << "\n"
                     "Exception: " << ex.what() << '\n';
        return;
    }

    for (std::string_view const weekday : data)
        try_get_wday(weekday);
}

int main()
{
    demo("lt_LT.utf8", {"Št", "Šeštadienis"});
    demo("en_US.utf8", {"SATELLITE"});
    demo("ja_JP.utf8", {"土曜日"});
}

💫 Possible output 💫

Parsing the weekday out of 'Št' in the locale lt_LT.utf8
Successfully parsed, weekday number is 6 the input was fully consumed
Parsing the weekday out of 'Šeštadienis' in the locale lt_LT.utf8
Successfully parsed, weekday number is 6 the input was fully consumed
Parsing the weekday out of 'SATELLITE' in the locale en_US.utf8
Successfully parsed, weekday number is 6 Remaining content: ELLITE
Parsing the weekday out of '土曜日' in the locale ja_JP.utf8
Successfully parsed, weekday number is 6 the input was fully consumed

---

🩹 Defect reports 🩹

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

• DR LWG 248, applied to C++98 — as published: eofbit was not set upon reaching the end iterator. Correct behavior: sets eofbit if a valid weekday name has not been read.

Retroactive glow-up, love that for the standard.

---

👀 See also 👀

• get_time parses a date/time value of specified format (C++11) (function template)

---

source/version/date sign-off, bestie: http://cppreference.com, 2024.06.10, page std::time_g...get_weekday(3). Now go parse a weekday and slay 💖✨