std::codecv...,do_unshift(3)

🎀 std::codecv...,do_unshift(3) — C++ Standard Libary manual, bestie! 💖

Okay so welcome to the manual page for std::codecvt::unshift and do_unshift, straight from the <purple>C++ Standard Libary</purple>. This is your group-chat explainer for conversion states, and we are keeping every parameter and every weird little detail. No skipping, no cap. 🦋

🌸 NAME

std::codecvt::unshift,do_unshift — yep, the name is literally std::codecvt::unshift,do_unshift, and it is giving “repetition is the brand.” 💅

🦋 Synopsis

Defined in header <locale>.

public:

result unshift( StateT& state, ExternT* to, ExternT* to_end,
                ExternT*& to_next ) const;

(1) — public member function: calls the member function do_unshift of the most derived class. 💖

protected:

virtual result do_unshift( StateT& state, ExternT* to, ExternT* to_end,
                           ExternT*& to_next ) const;

(2) — if the encoding represented by this codecvt facet is state-dependent, and state represents a conversion state that is not the initial shift state, writes the characters necessary to return to the initial shift state. The characters are written to a character array whose first element is pointed to by to. No more than to_end - to characters are written. The parameter to_next is updated to point one past the last character written. 🦋

💖 Return value

It returns a value of type std::codecvt_base::result, and that result tells you the success status, like a little vibe check for the conversion:

• ok — all necessary characters were written. state now represents initial shift state. ✨
• partial — not enough space in the output buffer. to_next == to_end. 😭
• error — an unspecified error has occurred. 💀
• noconv — the encoding is not state-dependent, no termination sequence necessary. 🎀

🧚 Notes

This function is called by std::basic_filebuf::close() and in other situations when finalizing a state-dependent multibyte character sequence. 🫶

🍓 Example

This section is incomplete. Reason: no example.

💀 Defect reports

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

• LWG 305 — Applied to: C++98. Behavior as published: std::codecvt<wchar_t, char, std::mbstate_t>::do_unshift was required not to write any character. Correct behavior: not required.
• LWG 380 — Applied to: C++98. Behavior as published: the meaning of returning partial was 'more characters need to be supplied to complete termination', but no character is supplied. Correct behavior: corrected to indicating insufficient buffer space.
• LWG 381 — Applied to: C++98. Behavior as published: state was not required to be valid, and error is returned if state is invalid. Correct behavior: state is required to be valid, and returning error indicates an error.
• LWG 664 — Applied to: C++98. Behavior as published: std::codecvt<char, char, std::mbstate_t>::do_unshift was required not to write any character. Correct behavior: not required.
• LWG 665 — Applied to: C++98. Behavior as published: std::codecvt<char, char, std::mbstate_t>::do_unshift was required to return noconv. Correct behavior: not required.

🌈 See also

• wcrtomb — converts a wide character to its multibyte representation, given state (function).
• do_out — converts a string from InternT to ExternT, such as when writing to file [virtual] (virtual protected member function).

🏷️ Category

• * Todo no example

---

💖 That is the whole page, bestie — source/version: http://cppreference.com, date: 2024.06.10. Go finalize those state-dependent sequences and slay, periodt. 🫶