std::stoul,std::stoull(3)

💅 std::stoul, std::stoull — the C++ Standard Library glow-up

okay bestie, welcome to <string>'s number-parsing corner 💖 this is std::stoul and std::stoull, straight out of the C++ Standard Library, and we're gonna get you fluent, no cap ✨

---

🌸 NAME 🌸

std::stoul, std::stoull — literally just std::stoul,std::stoull 🎀 (yes the manpage is that self-referential, she's a little icon that way)

---

✨ SYNOPSIS ✨

Defined in header <string> — that's the vibe check you need to pass first, iykyk 🦋

(1) — since C++11 🔥

unsigned long      stoul ( const std::string& str,
                           std::size_t* pos = nullptr, int base = 10 );

(2) — since C++11 🔥

unsigned long      stoul ( const std::wstring& str,
                           std::size_t* pos = nullptr, int base = 10 );

(3) — since C++11 🔥

unsigned long long stoull( const std::string& str,
                           std::size_t* pos = nullptr, int base = 10 );

(4) — since C++11 🔥

unsigned long long stoull( const std::wstring& str,
                           std::size_t* pos = nullptr, int base = 10 );

---

🧚 DESCRIPTION 🧚

So what she does: she interprets an unsigned integer value inside the string str. Main character energy 💅

Let ptr be an internal (to the conversion functions) pointer of type char* (1,3) or wchar_t* (2,4), accordingly. Lowkey important, keep that in your back pocket 🫶

• 1) Calls std::strtoul(str.c_str(), &ptr, base).
• 2) Calls std::wcstoul(str.c_str(), &ptr, base).
• 3) Calls std::strtoull(str.c_str(), &ptr, base).
• 4) Calls std::wcstoull(str.c_str(), &ptr, base).

She discards any whitespace characters (as identified by calling std::isspace) until the first non-whitespace character is found 😌 then takes as many characters as possible to form a valid base-n (where n=base) unsigned integer number representation and converts them to an integer value. Obsessed with her efficiency, honestly.

The valid unsigned integer value consists of these parts, in this exact order 🎀

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

The set of valid values for base is {0,2,3,...,36} ⭐ The set of valid digits for base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases larger than 10, valid digits include alphabetic characters, starting from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters is ignored 🙈 (she does not care about your capital letters, she's above it)

Additional numeric formats may be accepted by the currently installed C locale 🌍 (so like… your mileage may vary depending on locale, ngl)

If the value of base is 0, the numeric base is auto-detected: 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 🔍 she's intuitive like that.

⚠️ okay this part matters: 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. 💀 so like, yes you can pass a minus sign, and yes the result is still unsigned, and yes the math gets feral. Don't say I didn't warn you.

If pos is not a null pointer, then ptr will receive the address of the first unconverted character in str.c_str(), and the index of that character will be calculated and stored in *pos, giving the number of characters that were processed by the conversion 📍 she's giving receipts.

---

💜 PARAMETERS 💜

• str — the string to convert 🍓
• pos — address of an integer to store the number of characters processed
• base — the number base

---

🌈 RETURN VALUE 🌈

The string converted to the specified unsigned integer type. That's it, that's the whole return, slay 👑

---

🎀 EXCEPTIONS 🎀

• std::invalid_argument if no conversion could be performed 😭 (she tried, okay?)
• std::out_of_range if the converted value would fall out of the range of the result type or if the underlying function (std::strtoul or std::strtoull) sets errno to ERANGE. 🚨

---

🦋 EXAMPLE 🦋

This section is incomplete 😔

Reason: no example

(like… they really left us hanging, fr fr 💀)

---

⭐ DEFECT REPORTS ⭐

The following behavior-changing defect reports were applied retroactively to previously published C++ standards. History rewrite, but make it committee 📜✨

• DR LWG 2009 — Applied to: C++11 — Behavior as published: std::out_of_range would not be thrown if std::strtoul or std::strtoull sets errno to ERANGE — Correct behavior: will throw 🔥

---

👑 SEE ALSO 👑

• stoi, stol, stoll — converts a string to a signed integer (function) (C++11) (C++11) (C++11) 🌸
• stof, stod, stold — converts a string to a floating point value (function) (C++11) (C++11) (C++11) 🫶

---

💅 CATEGORY 💅

• Todo no example 🙈

---

and that's the whole page, bestie 💖 source: http://cppreference.com, version/date 2024.06.10, filed under std::stoul,std::stoull(3) — mwah, go parse something iconic 🌟🎀