`<charconv>`

The following functions are all overloads injected into Boost.Charconv.

This header depends on the headers of Boost.Charconv being present, otherwise it will #error. It is therefore not included by the umbrella header and must be included explicitly.

Since Boost.Charconv is a compiled library, auto-linking may occur (especially on MSVC platforms). If you do not use Boost.Charconv in your application except for the dependency to this library, you can define the following:

#define BOOST_CHARCONV_NO_LIB
#include <boost/int256.hpp> // or any other boost.int256 header

BOOST_CHARCONV_NO_LIB must be defined before the inclusion of any int256 header. This will disable auto-linking for Boost.Charconv.

to_chars

to_chars attempts to convert value into the character buffer specified by [first, last). For full documentation and explanation see the Boost.Charconv documentation.

#include <boost/int256/charconv.hpp>

namespace boost {
namespace charconv {

struct to_chars_result
{
    char* ptr;
    std::errc ec;

    friend constexpr bool operator==(const to_chars_result& lhs, const to_chars_result& rhs) noexcept = default;
    constexpr explicit operator bool() const noexcept { return ec == std::errc{}; }
};

BOOST_CHARCONV_CONSTEXPR to_chars_result to_chars(char* first, char* last, int256::uint256 value, int base = 10) noexcept;

BOOST_CHARCONV_CONSTEXPR to_chars_result to_chars(char* first, char* last, int256::int256 value, int base = 10) noexcept;

} // namespace charconv
} // namespace boost

BOOST_CHARCONV_CONSTEXPR is defined as constexpr when using a compiler with __builtin_is_constant_evaluated, or C++20 with std::is_constant_evaluated(). Otherwise, it is defined as inline.

A buffer that is too short is reported as std::errc::value_too_large with ptr set to last, and nothing is written. Size the buffer for the base in use: the maximum needs 78 characters in base 10, 64 in base 16, and 256 in base 2 for uint256, and one more character for int256 to hold a - sign. For int256 the sign, when there is one, is written before the digits (and before a base prefix from std::format’s `#, if that is also requested; see Formatting Support), never after: a negative value in base 16 is -ff, not f…f two’s-complement digits.

These functions are in the namespace boost::charconv, and not boost::int256.

from_chars

from_chars parses the string in [first, last) in an attempt to convert it into value. For full documentation and explanation see the Boost.Charconv documentation.

#include <boost/int256/charconv.hpp>

namespace boost {
namespace charconv {

struct from_chars_result
{
    const char* ptr;
    std::errc ec;

    friend constexpr bool operator==(const from_chars_result& lhs, const from_chars_result& rhs) noexcept = default;
    constexpr explicit operator bool() const noexcept { return ec == std::errc{}; }
};

constexpr from_chars_result from_chars(const char* first, const char* last, int256::uint256& value, int base = 10) noexcept;

constexpr from_chars_result from_chars(const char* first, const char* last, int256::int256& value, int base = 10) noexcept;

// Allows both std::string and std::string_view (when available)
constexpr from_chars_result from_chars(core::string_view sv, int256::uint256& value, int base = 10) noexcept;

constexpr from_chars_result from_chars(core::string_view sv, int256::int256& value, int base = 10) noexcept;

} // namespace charconv
} // namespace boost

Bases 2 through 36 are accepted. Parsing stops at the first character that is not a digit of the base, and ptr reports where it stopped, so "0x10" in base 16 yields 0 with ptr at the x. Text with no leading digit is std::errc::invalid_argument, and a value above the maximum is std::errc::result_out_of_range with value left untouched. For int256, a leading - is accepted before the digits (a leading + is not, matching std::from_chars); an unsigned value never accepts a sign at all, so "-1" into a uint256 is std::errc::invalid_argument rather than the two’s-complement value.

The core::string_view overload is host only; the pointer overloads run on the device as well when BOOST_INT256_ENABLE_CUDA or BOOST_INT256_ENABLE_SYCL is defined, since Boost.Charconv provides matching device support.

See the Boost.Charconv example for a program that covers every one of these cases.

Edit this Page