mirror of
https://github.com/boostorg/charconv.git
synced 2026-02-21 15:02:20 +00:00
213 lines
6.9 KiB
Plaintext
213 lines
6.9 KiB
Plaintext
////
|
|
Copyright 2022 Peter Dimov
|
|
Copyright 2023 Matt Borland
|
|
Distributed under the Boost Software License, Version 1.0.
|
|
https://www.boost.org/LICENSE_1_0.txt
|
|
////
|
|
|
|
[#reference]
|
|
= Reference
|
|
:idprefix: ref_
|
|
|
|
== <boost/charconv/from_chars.hpp>
|
|
|
|
=== Synopsis
|
|
[source, c++]
|
|
----
|
|
namespace boost {
|
|
namespace charconv {
|
|
|
|
struct from_chars_result;
|
|
|
|
template <typename Integral>
|
|
BOOST_CXX14_CONSTEXPR from_chars_result from_chars(const char* first, const char* last, Integral& value, int base = 10) noexcept;
|
|
|
|
template <typename Real>
|
|
from_chars_result from_chars(const char* first, const char* last, Real& value, chars_format fmt = chars_format::general) noexcept;
|
|
|
|
// ...
|
|
|
|
} // namespace charconv
|
|
} // namespace boost
|
|
----
|
|
|
|
=== from_chars_result
|
|
|
|
[source, c++]
|
|
----
|
|
struct from_chars_result
|
|
{
|
|
char const* ptr;
|
|
std::errc ec;
|
|
};
|
|
----
|
|
|
|
`from_chars_result` is the return type of the `from_chars` family of
|
|
overloaded functions.
|
|
|
|
The `ec` member is `std::errc()` when the conversion was successful, `std::errc::invalid_argument`
|
|
when no prefix of the passed characters form a valid value, or `std::errc::result_out_of_range`
|
|
when the characters form a value that would be out of range for the type.
|
|
|
|
The `ptr` member points to the first character not part of the matched
|
|
value, or to `last` if all characters matched.
|
|
|
|
=== from_chars
|
|
|
|
[source, c++]
|
|
----
|
|
template <typename Integral>
|
|
BOOST_CXX14_CONSTEXPR from_chars_result from_chars(const char* first, const char* last, Integral& value, int base = 10) noexcept;
|
|
----
|
|
|
|
Requires:;; `base` is between 2 and 36 (inclusive).
|
|
|
|
Effects:;; Attempts to interpret the characters in `[first, last)` as a numeric value in base `base`,
|
|
consisting of an optional minus sign (only if the type is signed), and a sequence of digits. For
|
|
bases above 10, the digit characters are `Aa` to `Zz`, as appropriate for `base`.
|
|
|
|
Returns:;; The `ec` member of the return value is `std::errc()` on success, `std::errc::invalid_argument` if
|
|
`[first, last)` can't be interpreted as an integer of base `base`, and `std::errc::result_out_of_range`
|
|
if `[first, last)` when interpreted as an integer of base `base` can't be represented
|
|
as a value of type `Integral`. The `ptr` member of the return value points to the first
|
|
character in `[first, last)` that is not part of the matched value, or is `last` when
|
|
all characters matched.
|
|
|
|
[source, c++]
|
|
----
|
|
template <typename Real>
|
|
from_chars_result from_chars(const char* first, const char* last, Real& value, boost::charconv::chars_format fmt = boost::charconv::chars_format::general, int precision) noexcept;
|
|
----
|
|
|
|
Requires:;; `fmt` has the value of one of the enumerators of chars_format
|
|
|
|
Effects:;; value is converted to a string in the style of printf in the "C" locale with the given precision. If a precision is not provided the shortest representation will be given.
|
|
|
|
Returns:;; The `ec` member of the return value is `0` on success.
|
|
`std::errc::invalid_argument` is returned if the value can't be interpreted with the given format `fmt`.
|
|
`std::errc::result_out_of_range` is returned when the value can't be represented in the target floating point type.
|
|
The `ptr` member of the return value points to the first character in `[first, last)` that is not part of the matched value, or is `last` when all characters are matched.
|
|
|
|
== <boost/charconv/to_chars.hpp>
|
|
|
|
=== Synopsis
|
|
[source, c++]
|
|
----
|
|
namespace boost {
|
|
namespace charconv {
|
|
|
|
struct to_chars_result;
|
|
|
|
template <typename Integral>
|
|
BOOST_CHARCONV_CONSTEXPR to_chars_result to_chars(char* first, char* last, Integral value, int base = 10) noexcept;
|
|
|
|
template <typename Real>
|
|
to_chars_result to_chars(char* first, char* last, Real value, chars_format fmt = chars_format::general, int precision) noexcept;
|
|
|
|
// ...
|
|
|
|
} // namespace charconv
|
|
} // namespace boost
|
|
----
|
|
|
|
=== to_chars_result
|
|
|
|
[source, c++]
|
|
----
|
|
struct to_chars_result
|
|
{
|
|
char const* ptr;
|
|
std::errc ec;
|
|
};
|
|
----
|
|
|
|
`to_chars_result` is the return type of the `to_chars` family of
|
|
overloaded functions.
|
|
|
|
The `ec` member is `std::errc()` when the conversion was successful, or `std::errc::result_out_of_range`
|
|
when the value cannot fit into the provided buffer.
|
|
|
|
The `ptr` member points to the first character after the characters written,
|
|
or `last` when `ec` is `std::errc::result_out_of_range`.
|
|
|
|
=== to_chars
|
|
|
|
[source, c++]
|
|
----
|
|
template <typename Integral>
|
|
BOOST_CHARCONV_CONSTEXPR to_chars_result to_chars( char* first, char* last, Integral value, int base = 10 ) noexcept;
|
|
----
|
|
|
|
Requires:;; `base` is between 2 and 36 (inclusive).
|
|
|
|
Effects:;; The value of `value` is converted to a string of digits in the given
|
|
base (with no redundant leading zeroes), which is stored in `[first, last)`.
|
|
Digits in the range 10..35 (inclusive) are represented as lowercase characters
|
|
`a`..`z`. If value is less than zero, the representation starts with a minus sign.
|
|
|
|
Returns:;; The `ec` member of the return value is `std::errc()` on success, and `std::errc::result_out_of_range` if
|
|
`[first, last)` does not contain enough space to hold the string representation of
|
|
`value`. The `ptr` member of the return value points to the character in `[first, last]`
|
|
that is one past the parsed characters, or is `last` when `ec` is `std::errc::result_out_of_range`.
|
|
|
|
[source, c++]
|
|
----
|
|
template <typename Real>
|
|
to_chars_result to_chars(char* first, char* last, Real value, chars_format fmt = chars_format::general, int precision) noexcept;
|
|
----
|
|
|
|
Requires:;; fmt has the value of one of the enumerators of chars_format
|
|
|
|
Effects:;; value is converted to a string in the style of printf in the "C" locale with the given precision.
|
|
If no precision is provided the value character string will be the shortest representation of `value`
|
|
|
|
Returns:;; The `ec` member of the return value is `std::errc()` on success, and `std::errc::result_out_of_range` if
|
|
`[first, last)` does not contain enough space to hold the string representation of
|
|
`value`. The `ptr` member of the return value points to the character in `[first, last]`
|
|
that is one past the parsed characters, or is `last` when `ec` is `std::errc::result_out_of_range`.
|
|
|
|
== <boost/charconv/limits.hpp>
|
|
|
|
=== Synopsis
|
|
[source, c++]
|
|
----
|
|
namespace boost {
|
|
namespace charconv {
|
|
|
|
template<typename T> struct limits
|
|
{
|
|
static constexpr int max_chars10 = /*see below*/;
|
|
static constexpr int max_chars = /*see below*/;
|
|
};
|
|
|
|
} // namespace charconv
|
|
} // namespace boost
|
|
----
|
|
|
|
=== limits
|
|
|
|
[source, c++]
|
|
----
|
|
template<typename T>
|
|
constexpr int limits<T>::max_chars10;
|
|
----
|
|
|
|
`max_chars10` is the minimum size of the buffer that needs to be
|
|
passed to `to_chars` to guarantee successful conversion for all values of
|
|
type `T`, when either no base is passed, or base 10 is passed.
|
|
|
|
[source, c++]
|
|
----
|
|
template<typename T>
|
|
constexpr int limits<T>::max_chars;
|
|
----
|
|
|
|
`max_chars` is the minimum size of the buffer that needs to be
|
|
passed to `to_chars` to guarantee successful conversion for all values of
|
|
type `T`, for any base.
|
|
|
|
== <boost/charconv.hpp>
|
|
|
|
This convenience header includes all headers previously
|
|
mentioned.
|