C++ string stoul Function

C++ String stoul

The std::stoul function in C++ converts a string representation of an unsigned integral number into an unsigned long. It is part of the C++11 standard and is defined in the <string> header.

---

Syntax of string stoul function

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

---

Parameters of string stoul function

Parameter	Description
str	The string containing the representation of an unsigned integral number.
idx (optional)	A pointer to a std::size_t object. If provided, it is set to the position of the first character in str after the numerical value. Defaults to 0.
base (optional)	The numerical base (radix) for the conversion, which can range from 2 to 36. If set to 0, the base is automatically deduced from the string format (e.g., prefixes like 0x indicate base 16). Defaults to 10.

---

Return Value of string stoul function

On successful conversion, std::stoul returns the converted value as an unsigned long. If the conversion fails, it throws an exception.

---

Exceptions for string stoul function

The std::stoul function can throw the following exceptions:

• std::invalid_argument: Thrown if the input string does not contain a valid unsigned integral number.
• std::out_of_range: Thrown if the converted value exceeds the range of the unsigned long type.

---

Examples for string stoul function

Example 1: Converting a Decimal String to Unsigned Long

In this example, we convert a string containing a decimal number to an unsigned long using std::stoul.

Program

#include <iostream>
#include <string>

int main() {
    std::string str = "4294967295";
    unsigned long num = std::stoul(str);
    std::cout << "The unsigned long value is: " << num << std::endl;
    return 0;
}

Output

The unsigned long value is: 4294967295

Explanation

1. The program includes the necessary headers: <iostream> for input and output operations, and <string> for string handling.
2. A string str is initialized with the value "4294967295", which is the maximum value for a 32-bit unsigned integer.
3. The std::stoul function converts the string to an unsigned long and stores it in the variable num.
4. The program outputs the unsigned long value using std::cout.

---

Example 2: Converting a Hexadecimal String to Unsigned Long

In this example, we convert a string representing a hexadecimal number to an unsigned long by specifying the base as 16.

Program

#include <iostream>
#include <string>

int main() {
    std::string str = "0x1A3F"; // Hexadecimal value
    unsigned long num = std::stoul(str, nullptr, 16); // Base 16 indicates hexadecimal
    std::cout << "The unsigned long value is: " << num << std::endl;
    return 0;
}

Output

The unsigned long value is: 6719

Explanation

1. The program includes the necessary headers: <iostream> for input/output operations and <string> for string handling.
2. The string str is initialized with the hexadecimal value "0x1A3F".
3. The std::stoul function is called with the base parameter set to 16, converting the hexadecimal string into its decimal equivalent.
4. The resulting unsigned long value is stored in num and printed using std::cout.

---

Examples for Exception Handling in stoul

The std::stoul function can throw exceptions when the string cannot be converted to an unsigned long. Here are examples to demonstrate how to handle these exceptions:

Example 1: Handling std::invalid_argument

This exception is thrown when the string does not contain a valid numeric representation.

Program

#include <iostream>
#include <string>
#include <exception>

int main() {
    try {
        std::string invalidStr = "HelloWorld";
        unsigned long num = std::stoul(invalidStr);
    } catch (const std::invalid_argument& e) {
        std::cout << "Invalid argument exception: " << e.what() << std::endl;
    }
    return 0;
}

Output

Invalid argument exception: stoul

Explanation

1. The string invalidStr contains characters that do not represent a valid number.
2. When std::stoul is called, it detects the invalid input and throws a std::invalid_argument exception.
3. The exception is caught in the catch block, and an error message is displayed using std::cout.

---

Example 2: Handling std::out_of_range

This exception is thrown when the value represented by the string exceeds the range of the unsigned long type.

Program

#include <iostream>
#include <string>
#include <exception>

int main() {
    try {
        std::string largeStr = "99999999999999999999";
        unsigned long num = std::stoul(largeStr);
    } catch (const std::out_of_range& e) {
        std::cout << "Out of range exception: " << e.what() << std::endl;
    }
    return 0;
}

Output

Out of range exception: stoul

Explanation

1. The string largeStr contains a numeric value that exceeds the maximum range of the unsigned long type.
2. When std::stoul attempts to convert the string, it detects the out-of-range value and throws a std::out_of_range exception.
3. The exception is caught in the catch block, and an error message is displayed using std::cout.