std::wcstoul,std::wcstoull(3)

💖 std::wcstoul, std::wcstoull — the wide-string glow-up 💖

okay so bestie, listen. you know how strtoul and strtoull are the byte-string girlies? this is literally their wide-string cousins, living over in the C++ Standard Library manual (section 3, the icons ✨). the whole thing is defined in the header <cwchar>, and it's giving "string-to-number" but make it wide.

---

🦋 SYNOPSIS 🦋

unsigned long      wcstoul ( const wchar_t* str, wchar_t** str_end, int base );
unsigned long long wcstoull( const wchar_t* str, wchar_t** str_end, int base );

heads up: wcstoull is (since C++11) — she's a newer addition, so check your standard, iykyk 🫶

basically what happens is: it interprets an unsigned integer value sitting inside the wide string that str points to. main character energy fr.

So here's the tea — it discards any whitespace characters (as identified by calling std::iswspace) until the first non-whitespace character is found. then it takes as many characters as possible to form a valid base-n unsigned integer number representation (where n=base, no cap) and converts them to an integer value. Slay.

The valid unsigned integer value is made of these parts:

• (optional) plus or minus sign
• (optional) prefix (0) indicating octal base (only applies when the base is 8 or 0)
• (optional) prefix (0x or 0X) indicating hexadecimal base (only applies when the base is 16 or 0)
• a sequence of digits

Now — the valid values for base are the set {0,2,3,...,36} 👑. And the valid digits for base-2 integers are {0,1}, for base-3 integers are {0,1,2}, and so on forever and ever. For bases larger than 10, valid digits include alphabetic characters, starting from Aa for a base-11 integer, all the way to Zz for a base-36 integer. oh and the case of the characters is ignored — Aa and aA are the same vibe 💅

ngl, additional numeric formats may be accepted by the currently installed C locale. so like, your locale can absolutely do the most, don't be surprised.

If the value of base is 0, the numeric base is auto-detected, and it's honestly so smart: if the prefix is 0, the base is octal 🌸 if the prefix is 0x or 0X, the base is hexadecimal 🦋 otherwise the base is decimal ✨

and if the minus sign was part of the input sequence, the numeric value calculated from the sequence of digits is negated as if by unary minus in the result type — which applies unsigned integer wraparound rules. yes bestie, wraparound. that's the whole point of unsigned, don't come for her 💀

The functions set the pointer pointed to by str_end to point to the wide character past the last character interpreted. If str_end is a null pointer, it is ignored. periodt. 🎀

---

🌈 PARAMETERS 🌈

• str — pointer to the null-terminated wide string to be interpreted 🥰
• str_end — pointer to a pointer to a wide character
• base — base of the interpreted integer value

---

🔥 RETURN VALUE 🔥

Integer value corresponding to the contents of str on success. Big W.

but okay, danger zone — if the converted value falls out of range of the corresponding return type, a range error occurs and ULONG_MAX or ULLONG_MAX is returned 😭 and if no conversion can be performed, 0 is returned. that's the "nothing to see here" answer fr fr.

---

✨ EXAMPLE ✨

// Run this code

#include <cwchar>
#include <errno.h>
#include <iostream>
#include <string>

int main()
{
    const wchar_t* p = L"10 200000000000000000000000000000 30 40";
    wchar_t* end;
    std::wcout << "Parsing L'" << p << "':\n";
    for (unsigned long i = std::wcstoul(p, &end, 10);
         p != end;
         i = std::wcstoul(p, &end, 10))
    {
        std::wcout << '\'' << std::wstring(p, end - p) << "' -> ";
        p = end;
        if (errno == ERANGE)
        {
            std::wcout << "range error, got ";
            errno = 0;
        }
        std::wcout << i << '\n';
    }
}

🍓 Possible output 🍓

Parsing L'10 200000000000000000000000000000 30 40':
'10' -> 10
' 200000000000000000000000000000' -> range error, got
18446744073709551615
' 30' -> 30
' 40' -> 40

see that huge number? yeah, that's the range error doing her dramatic little overflow moment, iconic honestly 💀✨

---

💜 SEE ALSO 💜

• strtoul — converts a byte string to an unsigned integer value
• strtoull — (function) (C++11)
• wcstol — converts a wide string to an integer value
• wcstoll — (function)

and if you want the full C-lore crossover episode, there's the C documentation for wcstoul, wcstoull — go read it bestie, i'm rooting for you 🫶

---

okay that's the whole page, no notes. this cutie's dated 2024.06.10, and she comes to us from cppreference.com over at http://cppreference.com — go give her a visit, she ate and left absolutely no crumbs 👑💖