New string conversion API

(Updated 2025-11-24)

The string conversion API is changing in libpqxx 8.0.

In include/pqxx/strconv.hxx you'll see a new API definition for the string conversion template, string_traits. This is where the string conversion API is defined.

This API is responsible for converting data between their SQL text formats (which is how we transfer it to and from the database) and the C++ objects in which you store the data internally. The API has changed significantly, becoming lighter and faster but also clearer and safer.

One big difference is that string_traits::into_buf() is gone. You no longer need to implement it. The main difference from to_buf() was that into_buf() promised to write its output into the buffer you provided, starting exactly at the beginning of the buffer. But a call to to_buf() followed by a std::memmove() can achieve the same.

Likewise, converts_to_string and converts_from_string are gone from the string_traits template. In 8.0, if you want to indicate that there's no conversion in one or the other direction... you simply don't declare the corresponding function.

The conversion functions' signatures have also changed. It no longer uses raw pointers, relying on the safer and more modern std::span and std::string_view instead.

Yes, std::string_view and not pqxx:zview. We no longer have a terminating zero at the end of a string.

When building new string conversions, please implement the new function signatures. If you already have string conversion code, please update it to the new API. The old API will eventually disappear.

These changes are on a per-function basis. So if you define your own string conversions for a custom type, you don't need to rewrite all your conversion functions at once. You can change to_buf() in one release, from_buf() in the next, and into_buf() later.

There are now generic versions of each of these, which will detect which API version the conversion implements: pqxx::to_buf(), pqxx::into_buf(), and pqxx::from_buf(). These operate on the new API, but they know how to call the old-style functions if needed.

The new API removes the raw pointers into buffers and replaces them with std::span. I hope this will make it easier for humans to avoid mistakes, and for static analysis tools to check for memory safety.

The new API also introduces std::sourcec_location parameters, so that libpqxx can trace any exceptions it needs to throw back to where you originally called into the library's code.`