#959: Replace type_name template with name_type(). (#970)

Fixes: #959

This should make it easier to override a type name with a manually
written, human-friendly one such as std::string instead of the whole
std::basic_string<char, ...> incantation; inline those to reduce
duplication; and consistently make it a std::string_view.

With that latter point, it abstracts away the underlying storage. Which does mean that sometimes with template types you may need to construct the names in a separate place just so name_type() can return a view. But that's probably better than storing each individual name in its own std::string, and allows for more optimisations.

Author: jtv

include/pqxx/array.hxx

@@ -427,7 +427,7 @@ private:
                 std::format(
                   "Array contains a null {}.  Consider making it an array of "
                   "std::optional<{}> instead.",
-                  type_name<ELEMENT>, type_name<ELEMENT>),
+                  name_type<ELEMENT>(), name_type<ELEMENT>()),
                 loc};
           }
           else

include/pqxx/doc/datatypes.md

@@ -74,10 +74,11 @@ First off, of course, you need a C++ type.  It may be your own, but it doesn't
 have to be.  It could be a type from a third-party library, or even one from
 the standard library that libpqxx does not yet support.
 
-First thing to do is specialise the `pqxx::type_name` variable to give the type
-a human-readable name.  That allows libpqxx error messages and such to talk
-about the type.  If you don't define a name, libpqxx will try to figure one out
-with some help from the compiler, but it may not always be easy to read.
+First thing to do is specialise the `pqxx::name_type()` function to give the
+type a human-readable name.  That allows libpqxx error messages and such to
+talk about the type.  If you don't define a name, libpqxx will try to figure
+one out with some help from the compiler, but it may not always be easy to
+read.
 
 Then, does your type have a built-in null value?  For example, a `char *` can
 be null on the C++ side.  Or some types are _always_ null, such as `nullptr`.
@@ -112,8 +113,8 @@ The library also provides specialisations for `std::optional<T>`,
 have conversions for `T`, you'll also automatically have conversions for those.
 
 
-Specialise `type_name`
-----------------------
+Specialise `name_type()`
+------------------------
 
 (This is a feature that should disappear once we have introspection in the C++
 language.)
@@ -122,15 +123,16 @@ When errors happen during conversion, libpqxx will compose error messages for
 the user.  Sometimes these will include the name of the type that's being
 converted.
 
-To tell libpqxx the name of each type, there's a template variable called
-`pqxx::type_name`.  For any given type `T`, it should have a specialisation
+To tell libpqxx the name of each type, there's a function template called
+`pqxx::name_type()`.  For any given type `T`, it should have a specialisation
 that provides that `T`'s human-readable name:
 
 ```cxx
     // T is your type.
     namespace pqxx
     {
-    template<> std::string const type_name<T>{"My T type's name"};
+    template<> inline std::string_view
+    name_type<T>(){ return "My T type's name"; };
     }
 ```
 

include/pqxx/field.hxx

@@ -227,7 +227,7 @@ public:
     if (is_null())
     {
       if constexpr (not nullness<T>::has_null)
-        internal::throw_null_conversion(type_name<T>, c.loc);
+        internal::throw_null_conversion(name_type<T>(), c.loc);
       else
         return nullness<T>::null();
     }
@@ -255,7 +255,7 @@ public:
 
     // There's no such thing as a null SQL array.
     if (is_null())
-      internal::throw_null_conversion(type_name<array_type>, loc);
+      internal::throw_null_conversion(name_type<array_type>(), loc);
     else
       return array_type{this->view(), this->m_home.m_encoding, loc};
   }
@@ -366,7 +366,7 @@ inline bool field::to<zview>(zview &obj, zview const &default_value, ctx) const
 template<> inline zview field::as<zview>(ctx c) const
 {
   if (is_null())
-    internal::throw_null_conversion(type_name<zview>, c.loc);
+    internal::throw_null_conversion(name_type<zview>(), c.loc);
   return zview{c_str(), size()};
 }
 
@@ -505,7 +505,7 @@ template<typename T> inline T from_string(field const &value, ctx c = {})
     if constexpr (nullness<T>::has_null)
       return nullness<T>::null();
     else
-      internal::throw_null_conversion(type_name<T>, c.loc);
+      internal::throw_null_conversion(name_type<T>(), c.loc);
   }
   else
   {

include/pqxx/internal/array-composite.hxx

@@ -202,7 +202,7 @@ inline void parse_composite_field(
       throw conversion_error{
         std::format(
           "Can't read composite field {}: C++ type {} does not support nulls.",
-          to_string(index), type_name<T>),
+          to_string(index), name_type<T>()),
         loc};
     break;
 

include/pqxx/internal/conversions.hxx

@@ -101,7 +101,7 @@ generic_into_buf(char *begin, char *end, T const &value, ctx c = {})
   auto const len = std::size(text) + 1;
   if (std::cmp_greater(len, space))
     throw conversion_overrun{
-      std::format("Not enough buffer space to insert {}.  ", type_name<T>) +
+      std::format("Not enough buffer space to insert {}.  ", name_type<T>()) +
         state_buffer_overrun(space, len),
       c.loc};
   std::memmove(begin, std::data(text), len);
@@ -121,7 +121,7 @@ generic_into_buf(std::span<char> buf, T const &value, ctx c = {})
   auto const len = std::size(text) + 1;
   if (std::cmp_greater(len, space))
     throw conversion_overrun{
-      std::format("Not enough buffer space to insert {}.  ", type_name<T>) +
+      std::format("Not enough buffer space to insert {}.  ", name_type<T>()) +
         state_buffer_overrun(space, len),
       c.loc};
   std::memmove(begin, std::data(text), len);
@@ -841,7 +841,7 @@ struct string_traits<std::unique_ptr<T, Args...>>
     ctx c = {})
   {
     if (not value)
-      internal::throw_null_conversion(type_name<std::unique_ptr<T>>, c.loc);
+      internal::throw_null_conversion(name_type<std::unique_ptr<T>>(), c.loc);
     return begin + pqxx::into_buf({begin, end}, *value);
   }
 
@@ -850,7 +850,7 @@ struct string_traits<std::unique_ptr<T, Args...>>
     ctx c = {})
   {
     if (not value)
-      internal::throw_null_conversion(type_name<std::unique_ptr<T>>, c.loc);
+      internal::throw_null_conversion(name_type<std::unique_ptr<T>>(), c.loc);
     return pqxx::to_buf({begin, end}, *value);
   }
 
@@ -905,14 +905,14 @@ template<typename T> struct string_traits<std::shared_ptr<T>>
   to_buf(char *begin, char *end, std::shared_ptr<T> const &value, ctx c = {})
   {
     if (not value)
-      internal::throw_null_conversion(type_name<std::shared_ptr<T>>, c.loc);
+      internal::throw_null_conversion(name_type<std::shared_ptr<T>>(), c.loc);
     return pqxx::to_buf({begin, end}, *value, c);
   }
   static char *
   into_buf(char *begin, char *end, std::shared_ptr<T> const &value, ctx c = {})
   {
     if (not value)
-      internal::throw_null_conversion(type_name<std::shared_ptr<T>>, c.loc);
+      internal::throw_null_conversion(name_type<std::shared_ptr<T>>(), c.loc);
     return begin + pqxx::into_buf({begin, end}, *value, c);
   }
   static std::size_t size_buffer(std::shared_ptr<T> const &value) noexcept
@@ -1140,7 +1140,7 @@ template<typename TYPE> inline std::string to_string(TYPE const &value, ctx c)
 {
   if (is_null(value))
     throw conversion_error{
-      std::format("Attempt to convert null to a string.", type_name<TYPE>),
+      std::format("Attempt to convert null to a string.", name_type<TYPE>()),
       c.loc};
 
   if constexpr (nullness<std::remove_cvref_t<TYPE>>::always_null)
@@ -1187,7 +1187,7 @@ inline void into_string(T const &value, std::string &out, ctx c = {})
 {
   if (is_null(value))
     throw conversion_error{
-      std::format("Attempt to convert null {} to a string.", type_name<T>),
+      std::format("Attempt to convert null {} to a string.", name_type<T>()),
       c.loc};
 
   // We can't just reserve() data; modifying the terminating zero leads to

include/pqxx/internal/stream_query.hxx

@@ -282,14 +282,14 @@ private:
       if (std::data(text) != nullptr)
         throw conversion_error{std::format(
           "Streaming a non-null value into a {}, which must always be null.",
-          type_name<field_type>)};
+          name_type<field_type>())};
     }
     else if (std::data(text) == nullptr)
     {
       if constexpr (nullity::has_null)
         return nullity::null();
       else
-        internal::throw_null_conversion(type_name<field_type>, loc);
+        internal::throw_null_conversion(name_type<field_type>(), loc);
     }
     else
     {

include/pqxx/strconv.hxx

@@ -30,13 +30,6 @@
 #include "pqxx/zview.hxx"
 
 
-namespace pqxx::internal
-{
-/// Attempt to demangle @c std::type_info::name() to something human-readable.
-PQXX_LIBEXPORT std::string demangle_type_name(char const[]);
-} // namespace pqxx::internal
-
-
 namespace pqxx
 {
 /**
@@ -64,18 +57,6 @@ namespace pqxx
  */
 //@{
 
-/// A human-readable name for a type, used in error messages and such.
-/** Actually this may not always be very user-friendly.  It uses
- * @c std::type_info::name().  On gcc-like compilers we try to demangle its
- * output.  Visual Studio produces human-friendly names out of the box.
- *
- * This variable is not inline.  Inlining it gives rise to "memory leak"
- * warnings from asan, the address sanitizer, possibly from use of
- * @c std::type_info::name.
- */
-template<typename TYPE>
-std::string const type_name{internal::demangle_type_name(typeid(TYPE).name())};
-
 
 /// Traits describing a type's "null value," if any.
 /** Some C++ types have a special value or state which correspond directly to
@@ -613,13 +594,9 @@ private:
 } // namespace pqxx::internal
 
 
-// We used to inline type_name<ENUM>, but this triggered a "double free" error
-// on program exit, when libpqxx was built as a shared library on Debian with
-// gcc 12.
-
 /// Macro: Define a string conversion for an enum type.
-/** This specialises the @c pqxx::string_traits template, so use it in the
- * @c ::pqxx namespace.
+/** This specialises the @ref pqxx::string_traits and @ref pqxx::name_type
+ * templates, so use it in the @ref pqxx namespace.
  *
  * For example:
  *
@@ -630,12 +607,15 @@ private:
  *      int main() { std::cout << pqxx::to_string(xa) << std::endl; }
  */
 #define PQXX_DECLARE_ENUM_CONVERSION(ENUM)                                    \
-  template<> struct string_traits<ENUM> : pqxx::internal::enum_traits<ENUM>   \
-  {};                                                                         \
-  template<> inline std::string_view const type_name<ENUM>                    \
+  template<>                                                                  \
+  [[maybe_unused, deprecated("Use name_type() instead of type_name.")]]       \
+  inline std::string_view const type_name<ENUM>{#ENUM};                       \
+  template<> constexpr inline std::string_view name_type<ENUM>()              \
   {                                                                           \
-    #ENUM                                                                     \
-  }
+    return #ENUM;                                                             \
+  }                                                                           \
+  template<> struct string_traits<ENUM> : pqxx::internal::enum_traits<ENUM>   \
+  {}
 
 
 namespace pqxx

include/pqxx/stream_from.hxx

@@ -358,7 +358,7 @@ inline void stream_from::extract_value(Tuple &t, sl loc) const
     if constexpr (nullity::has_null)
       std::get<index>(t) = nullity::null();
     else
-      internal::throw_null_conversion(type_name<field_type>, loc);
+      internal::throw_null_conversion(name_type<field_type>(), loc);
   }
   else
   {

include/pqxx/types.hxx

@@ -158,6 +158,123 @@ struct from_query_t
 } // namespace pqxx
 
 
+namespace pqxx::internal
+{
+/// Attempt to demangle @c std::type_info::name() to something human-readable.
+PQXX_LIBEXPORT std::string demangle_type_name(char const[]);
+} // namespace pqxx::internal
+
+
+namespace pqxx
+{
+/// A human-readable name for a type, used in error messages and such.
+/** Actually this may not always be very user-friendly.  It uses
+ * @c std::type_info::name().  On gcc-like compilers we try to demangle its
+ * output.  Visual Studio produces human-friendly names out of the box.
+ *
+ * This variable is not inline.  Inlining it gives rise to "memory leak"
+ * warnings from asan, the address sanitizer, possibly from use of
+ * @c std::type_info::name.
+ */
+#include "pqxx/internal/ignore-deprecated-pre.hxx"
+template<typename TYPE>
+[[deprecated("Use name_type() instead.")]]
+std::string const type_name{
+  pqxx::internal::demangle_type_name(typeid(TYPE).name())};
+#include "pqxx/internal/ignore-deprecated-post.hxx"
+
+
+/// Return human-readable name for `TYPE`.
+template<typename TYPE> inline std::string_view name_type()
+{
+#include "pqxx/internal/ignore-deprecated-pre.hxx"
+  return type_name<TYPE>;
+#include "pqxx/internal/ignore-deprecated-post.hxx"
+}
+
+
+/// Specialisation to save on startup work & produce friendlier output.
+template<> constexpr inline std::string_view name_type<std::string>()
+{
+  return "std::string";
+}
+/// Specialisation to save on startup work & produce friendlier output.
+template<> constexpr inline std::string_view name_type<std::string_view>()
+{
+  return "std::string_view";
+}
+template<> constexpr inline std::string_view name_type<char const *>()
+{
+  return "char const *";
+}
+/// Specialisation to save on startup work.
+template<> constexpr inline std::string_view name_type<bool>()
+{
+  return "bool";
+}
+/// Specialisation to save on startup work.
+template<> constexpr inline std::string_view name_type<short>()
+{
+  return "short";
+}
+/// Specialisation to save on startup work.
+template<> constexpr inline std::string_view name_type<int>()
+{
+  return "int";
+}
+/// Specialisation to save on startup work.
+template<> constexpr inline std::string_view name_type<long>()
+{
+  return "long";
+}
+/// Specialisation to save on startup work.
+template<> constexpr inline std::string_view name_type<long long>()
+{
+  return "long long";
+}
+/// Specialisation to save on startup work.
+template<> constexpr inline std::string_view name_type<unsigned short>()
+{
+  return "short";
+}
+/// Specialisation to save on startup work.
+template<> constexpr inline std::string_view name_type<unsigned>()
+{
+  return "unsigned";
+}
+/// Specialisation to save on startup work.
+template<> constexpr inline std::string_view name_type<unsigned long>()
+{
+  return "unsigned long";
+}
+/// Specialisation to save on startup work.
+template<> constexpr inline std::string_view name_type<unsigned long long>()
+{
+  return "unsigned long long";
+}
+/// Specialisation to save on startup work.
+template<> constexpr inline std::string_view name_type<float>()
+{
+  return "float";
+}
+/// Specialisation to save on startup work.
+template<> constexpr inline std::string_view name_type<double>()
+{
+  return "double";
+}
+/// Specialisation to save on startup work.
+template<> constexpr inline std::string_view name_type<long double>()
+{
+  return "long double";
+}
+/// Specialisation to save on startup work.
+template<> constexpr inline std::string_view name_type<std::nullptr_t>()
+{
+  return "std::nullptr_t";
+}
+} // namespace pqxx
+
+
 namespace pqxx::internal
 {
 /// Concept: one of the "char" types.