Strconv

Wrappers around output buffers for string-producing functions, enabling a single string producer to accept multiple string representations and allocation policies. More...

Collaboration diagram for Strconv:

Namespaces
namespace	mysql
namespace	mysql::strconv
namespace	mysql::strconv::detail

Detailed Description

Wrappers around output buffers for string-producing functions, enabling a single string producer to accept multiple string representations and allocation policies.

Anyone that defines a string-producing function usually has to make several decisions, and this framework makes it easy to support all variants without duplicating/repeating code:

• Who allocates the string: the function or the caller?
• How are strings represented: std::string or raw pointer? For raw pointers, how is the length represented: an integer length, or a raw pointer to the end? Are characters char, unsigned char, or std::byte? Which integer type is used for the length?
• Should the string be null-terminated or not?

If the string producer will only be used in code that follows one defined convention, the API can just use that. Otherwise, in more heterogeneous environments, use this library as follows:

• The string-producing function should take an Out_str & as out-parameter:

  Return_status produce(Out_str &out);

• The user code should pass an object returned by any of the out_str_* functions, which return a wrapper around the output parameters. For example:

  std::string str;
  // Allocate and write to `str`; return error if allocation fails.
  if (produce(out_str_growable(str)) == Return_status::error) { ... }

  or

  char *str = nullptr;
  char *end = str;
  // Allocate memory and write to `str`.
  // If allocation fails, return error.
  // Make the string null-terminated (the _z suffix).
  // Make `end` point to the null character.
  if (produce(out_str_growable_z(str, end)) == Return_status::error) {...}

  or

  unsigned char str[1024];
  size_t size = 1024;
  // We know the produced string is at most 1024 bytes (otherwise, behavior
  // is undefined). Write the string to `str`.
  // Do not make the string null-terminated (the _nz suffix).
  // Set `size` to the actual number of bytes written.
  if (produce(out_str_fixed_nz(str, size)) == Return_status::Error) { ... }

  or

  std::byte str[1024];
  size_t size = 1024;
  // We know the produced string is at most 1024 bytes (otherwise, behavior
  // is undefined). Write the string to `str`.
  // Do not make the string null-terminated (the _nz suffix).
  // Set `size` to the actual number of bytes written.
  produce(out_str_fixed_nz(str, size));

  These are only examples: each of _growable, _fixed can be combined with all string representations (std::string, begin+end, or begin+length). Raw pointer representations can be either null-terminated or not (the _z/_nz suffixes); optionally take a Memory_resource parameter; use char, unsigned char, or std::byte for the character type; and their sizes can be any integer type.
• To write to Output String Wrappers, while taking both the resize policy and the zero-termination policy into account, the implementation of produce may use the function out_str_write. out_str_write takes an invocable as argument; the invocable is what actually generates the string, and out_str_write performs the allocation (and checking for out-of-memory errors), and writes the null-termination byte if required.