Component bslstl_charconv [Package bslstl]

Provide implementations for functions not in the system library. More...

Namespaces
namespace	bslstl

---

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:

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

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);
  }