bslstl_charconv

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Demonstrating Writing a number to a streambuf

Purpose

Provide implementations for functions not in the system library.

Classes

Canonical header: bsl_charconv.h

See also

bsl+bslhdrs

Description

This component is for internal use only. Please include <bsl_charconv.h> instead. This component provides implementations for standard algorithms that are not provided by the underlying standard library implementation. For example, to_chars is a C++17 algorithm, and it is provided here for code using C++03 - C++14 or for compilers that do not provide <charconv> in C++17.

to_chars is locale-independent, non-allocating, and non-throwing, and provides a safe and more performant alternative to snprintf in contexts where complex formatting options or locale are not important.

Usage

In this section we show intended use of this component.

Example 1: Demonstrating Writing a number to a streambuf

Suppose we want to write a function that writes an int to a streambuf. We can use bsl::to_chars to write the int to a buffer, then write the buffer to the streambuf.

First, we declare our function:

/// Write the specified `value`, in decimal, to the specified `result`.
void writeJsonScalar(std::streambuf *result, int value)
{

Then, we declare a buffer long enough to store any int value in decimal.

    char buffer[11];        // size large enough to write `INT_MIN`, the
                            // worst-case value, in decimal.

Next, we declare a variable to store the return value:

    bsl::to_chars_result sts;

Then, we call the function:

    sts = bsl::to_chars(buffer, buffer + sizeof(buffer), value);

Next, we check that the buffer was long enough, which should always be the case:

    assert(bsl::ErrcEnum() == sts.ec);

Now, we check that sts.ptr is in the range [ buffer + 1, buffer + sizeof(buffer) ], which will always be the case whether to_chars succeeded or failed.

    assert(buffer  <  sts.ptr);
    assert(sts.ptr <= buffer + sizeof(buffer));

Finally, we write our buffer to the streambuf:

    result->sputn(buffer, sts.ptr - buffer);
}