std::ungetwc(3)

💅 std::ungetwc

okay bestie, so this one's from the C++ Standard Library — it's std::ungetwc, and no, it's not a weird dance move, it's the "nvm put it back" function for wide characters. let me walk you through it 🫶

---

✨ Synopsis ✨

so first of all, she lives in this header:

#include <cwchar>

and here's her whole signature, literally the entire thing:

std::wint_t ungetwc( std::wint_t ch, std::FILE* stream );

that's it. that's the whole vibe. 🌸

---

🦋 Description 🦋

okay so here's what's going down. if ch does not equal WEOF, she pushes the wide character ch into the input buffer associated with the stream stream — and she does it in such a manner that a subsequent read operation from stream will retrieve that wide character. 🎀

and the actual external device associated with the stream? not modified. not touched. not even a little bit. she's just messing with the buffer, king. 💅

stream repositioning operations std::fseek, std::fsetpos, and std::rewind all discard the effects of std::ungetwc. so like, yeah, they'll undo your cute little pushback. rude but okay. 😭

now here's the part where you gotta pay attention, bestie — if std::ungetwc is called more than once without an intervening read or repositioning, it may fail. read that again. in other words, a pushback buffer of size 1 is guaranteed, but any larger buffer is implementation-defined. so one (1) pushback is iconic and safe, and two or more is giving "cross your fingers" energy. 🙈

if multiple successful std::ungetwc were performed, read operations retrieve the pushed-back wide characters in reverse order of std::ungetwc. last one back is first one out — LIFO realness, no cap. 🔥

if ch equals WEOF, the operation fails and the stream is not affected. like she simply didn't show up. 💀

a successful call to std::ungetwc clears the end of file status flag feof. so if you were at EOF and you push something back, bestie you are no longer at EOF. character development. 🌈

and finally — a successful call to std::ungetwc on a stream (whether text or binary) modifies the stream position indicator in an unspecified manner, but guarantees that after all pushed-back wide characters are retrieved with a read operation, the stream position indicator is equal to its value before std::ungetwc. translation: she's allowed to be messy while she's working, but she will put it back exactly where she found it. periodt. ✨

---

🌸 Parameters 🌸

• ch — the wide character to be put back. the little guy going back into the buffer 🍓
• stream — the file stream to put the wide character back to. the destination, the home, the vibe 💜

---

👑 Return value 👑

• On success, ch is returned. she ate and she came back. 💅
• On failure, WEOF is returned — and the given stream remains unchanged. so if it flops, at least it flops cleanly. 🧚

---

⭐ See also ⭐

• ungetc — puts a character back into a file stream (function). the narrow-char cousin, same energy 🎀
• fgetwc — gets a wide character from a file stream (function). the one that picks the character back up lol
• getwc — (function). another way to pull a wide character out 🦋
• C documentation for ungetwc — if you want to see where she came from 💖

---

so yeah, that's std::ungetwc. push one (1) wide character back, don't get greedy, remember that repositioning wipes the slate, and she'll always restore the position indicator once you read everything out. slay. 💅✨

mwah, this page was served up fresh from http://cppreference.com, dated 2024.06.10 — go be great with your wide characters, bestie 🫶💖