std::fwide(3)

💅 std::fwide 💅

okay so this is std::fwide from the C++ Standard Library (yes, the std::fwide(3) girlies, hi 🫶) — she's the one who decides whether your stream is living its wide-character fantasy or keeping it byte-sized. let's get into it ✨

---

✨ NAME ✨

std::fwide — literally just std::fwide, that's the whole name, no notes 💀

🌸 Synopsis 🌸

bestie it lives here:

Defined in header <cwchar>
int fwide( std::FILE* stream, int mode );

so here's the vibe check on mode, no cap:

• if mode > 0, she attempts to make stream wide-oriented 👑
• if mode < 0, she attempts to make stream byte-oriented 🎀
• if mode == 0, she's just asking, not telling — it only queries the current orientation of stream 🔍

and the big one: if the orientation of the stream has already been decided (either by executing output, or by an earlier call to fwide), this function does nothing. like, she's not gonna fight about it. it's settled. periodt. 💅

🦋 Parameters 🦋

• stream — pointer to the C I/O stream you wanna modify or query. that's the main character rn 🌟
• mode — an integer value: greater than zero to set the stream wide, less than zero to set the stream narrow, or zero to query only. three moods, one int, we love range 🙈

🎀 Return value 🎀

what she gives you back:

• an integer greater than zero if the stream is wide-oriented after this call 🌈
• an integer less than zero if the stream is byte-oriented after this call 💜
• zero if the stream has no orientation (she's still figuring herself out, valid) ✨

🔥 Example 🔥

the following code sets and resets the stream orientation. iconic behaviour honestly:

// Run this code

#include <cstdio>
#include <cstdlib>
#include <cwchar>
#include <iostream>

void show_orientation(int n)
{
    n < 0 ? std::wcout << "\tnarrow orientation\n" :
    n > 0 ? std::wcout << "\twide orientation\n" :
            std::wcout << "\tno orientation\n";
}

void try_read(FILE* fp)
{
    if (const int c = std::fgetc(fp); c == EOF)
        std::wcout << "\tnarrow character read failed\n";
    else
        std::wcout << "\tnarrow character read '" <<
   static_cast<char>(c) << "'\n";

    if (const wint_t wc = std::fgetwc(fp); wc == WEOF)
        std::wcout << "\twide character read failed\n";
    else
        std::wcout << "\twide character read '" <<
   static_cast<wchar_t>(wc) << "'\n";
}

int main()
{
    enum fwide_orientation : int { narrow = -1, query, wide };

    FILE* fp = std::fopen("main.cpp", "r");
    if (!fp)
    {
        std::wcerr << "fopen() failed\n";
        return EXIT_FAILURE;
    }

    std::wcout << "1) A newly opened stream has no orientation.\n";
    show_orientation(std::fwide(fp, fwide_orientation::query));

    std::wcout << "2) Establish byte orientation.\n";
    show_orientation(std::fwide(fp, fwide_orientation::narrow));
    try_read(fp);

    std::wcout << "3) Only freopen() can reset stream orientation.\n";
    if (std::freopen("main.cpp", "r", fp) == NULL)
    {
        std::wcerr << "freopen() failed\n";
        return EXIT_FAILURE;
    }

    std::wcout << "4) A reopened stream has no orientation.\n";
    show_orientation(std::fwide(fp, fwide_orientation::query));

    std::wcout << "5) Establish wide orientation.\n";
    show_orientation(std::fwide(fp, fwide_orientation::wide));
    try_read(fp);

    std::fclose(fp);
}

⭐ Possible output ⭐

(and yes, the output is giving exactly this:)

1) A newly opened stream has no orientation.
        no orientation
2) Establish byte orientation.
        narrow orientation
        narrow character read '#'
        wide character read failed
3) Only freopen() can reset stream orientation.
4) A reopened stream has no orientation.
        no orientation
5) Establish wide orientation.
        wide orientation
        narrow character read failed
        wide character read '#'

okay bestie real talk for a sec: notice how once the stream picks a lane, reading it the other way just fails? that's not a bug, that's the whole point — orientation is a commitment 💀 and also notice line 3: freopen() is the only thing that can reset it. like, only freopen() has that power. main character energy fr fr.

👑 See also 👑

• fopen — opens a file (function) 🍓
• C documentation for fwide 📚

---

and that's the page, babe! 🌸 this lovely little doc dropped as std::fwide(3) from http://cppreference.com, version 2024.06.10 — so go forth, orient your streams, and slay 💖✨🎀🦋