Make changes to format_descriptor backwards-compat

The format strings that are known at compile time are now accessible
via both ::value and ::format(), and format strings for everything
else is accessible via ::format(). This makes it backwards compatible.

docs/advanced.rst

@@ -1224,12 +1224,12 @@ completely avoid copy operations with Python expressions like
     py::class_<Matrix>(m, "Matrix")
        .def_buffer([](Matrix &m) -> py::buffer_info {
             return py::buffer_info(
-                m.data(),                              /* Pointer to buffer */
-                sizeof(float),                         /* Size of one scalar */
-                py::format_descriptor<float>::value(), /* Python struct-style format descriptor */
-                2,                                     /* Number of dimensions */
-                { m.rows(), m.cols() },                /* Buffer dimensions */
-                { sizeof(float) * m.rows(),            /* Strides (in bytes) for each index */
+                m.data(),                               /* Pointer to buffer */
+                sizeof(float),                          /* Size of one scalar */
+                py::format_descriptor<float>::format(), /* Python struct-style format descriptor */
+                2,                                      /* Number of dimensions */
+                { m.rows(), m.cols() },                 /* Buffer dimensions */
+                { sizeof(float) * m.rows(),             /* Strides (in bytes) for each index */
                   sizeof(float) }
             );
         });
@@ -1273,7 +1273,7 @@ buffer objects (e.g. a NumPy matrix).
             py::buffer_info info = b.request();
 
             /* Some sanity checks ... */
-            if (info.format != py::format_descriptor<Scalar>::value())
+            if (info.format != py::format_descriptor<Scalar>::format())
                 throw std::runtime_error("Incompatible format: expected a double array!");
 
             if (info.ndim != 2)
@@ -1299,7 +1299,7 @@ as follows:
             m.data(),                /* Pointer to buffer */
             sizeof(Scalar),          /* Size of one scalar */
             /* Python struct-style format descriptor */
-            py::format_descriptor<Scalar>::value(),
+            py::format_descriptor<Scalar>::format(),
             /* Number of dimensions */
             2,
             /* Buffer dimensions */
@@ -1439,7 +1439,7 @@ simply using ``vectorize``).
         auto result = py::array(py::buffer_info(
             nullptr,            /* Pointer to data (nullptr -> ask NumPy to allocate!) */
             sizeof(double),     /* Size of one item */
-            py::format_descriptor<double>::value, /* Buffer format */
+            py::format_descriptor<double>::format(), /* Buffer format */
             buf1.ndim,          /* How many dimensions? */
             { buf1.shape[0] },  /* Number of elements for each dimension */
             { sizeof(double) }  /* Strides for each dimension */
@@ -1830,4 +1830,3 @@ is always ``none``).
 
     // Evaluate the statements in an separate Python file on disk
     py::eval_file("script.py", scope);
-

example/example-buffers.cpp

@@ -81,7 +81,7 @@ void init_ex_buffers(py::module &m) {
         /// Construct from a buffer
         .def("__init__", [](Matrix &v, py::buffer b) {
             py::buffer_info info = b.request();
-            if (info.format != py::format_descriptor<float>::value() || info.ndim != 2)
+            if (info.format != py::format_descriptor<float>::format() || info.ndim != 2)
                 throw std::runtime_error("Incompatible buffer format!");
             new (&v) Matrix(info.shape[0], info.shape[1]);
             memcpy(v.data(), info.ptr, sizeof(float) * v.rows() * v.cols());
@@ -104,12 +104,12 @@ void init_ex_buffers(py::module &m) {
        /// Provide buffer access
        .def_buffer([](Matrix &m) -> py::buffer_info {
             return py::buffer_info(
-                m.data(),                              /* Pointer to buffer */
-                sizeof(float),                         /* Size of one scalar */
-                py::format_descriptor<float>::value(), /* Python struct-style format descriptor */
-                2,                                     /* Number of dimensions */
-                { m.rows(), m.cols() },                /* Buffer dimensions */
-                { sizeof(float) * m.rows(),            /* Strides (in bytes) for each index */
+                m.data(),                               /* Pointer to buffer */
+                sizeof(float),                          /* Size of one scalar */
+                py::format_descriptor<float>::format(), /* Python struct-style format descriptor */
+                2,                                      /* Number of dimensions */
+                { m.rows(), m.cols() },                 /* Buffer dimensions */
+                { sizeof(float) * m.rows(),             /* Strides (in bytes) for each index */
                   sizeof(float) }
             );
         })

example/example20.cpp

@@ -47,7 +47,7 @@ std::ostream& operator<<(std::ostream& os, const NestedStruct& v) {
 template <typename T>
 py::array mkarray_via_buffer(size_t n) {
     return py::array(py::buffer_info(nullptr, sizeof(T),
-                                     py::format_descriptor<T>::value(),
+                                     py::format_descriptor<T>::format(),
                                      1, { n }, { sizeof(T) }));
 }
 
@@ -80,9 +80,9 @@ void print_recarray(py::array_t<S> arr) {
 }
 
 void print_format_descriptors() {
-    std::cout << py::format_descriptor<SimpleStruct>::value() << std::endl;
-    std::cout << py::format_descriptor<PackedStruct>::value() << std::endl;
-    std::cout << py::format_descriptor<NestedStruct>::value() << std::endl;
+    std::cout << py::format_descriptor<SimpleStruct>::format() << std::endl;
+    std::cout << py::format_descriptor<PackedStruct>::format() << std::endl;
+    std::cout << py::format_descriptor<NestedStruct>::format() << std::endl;
 }
 
 void print_dtypes() {

include/pybind11/common.h

@@ -204,7 +204,7 @@ struct buffer_info {
     void *ptr;                   // Pointer to the underlying storage
     size_t itemsize;             // Size of individual items in bytes
     size_t size;                 // Total number of entries
-    std::string format;          // For homogeneous buffers, this should be set to format_descriptor<T>::value()
+    std::string format;          // For homogeneous buffers, this should be set to format_descriptor<T>::format()
     size_t ndim;                 // Number of dimensions
     std::vector<size_t> shape;   // Shape of the tensor (1 entry per dimension)
     std::vector<size_t> strides; // Number of entries between adjacent entries (for each per dimension)
@@ -349,18 +349,19 @@ PYBIND11_RUNTIME_EXCEPTION(reference_cast_error) /// Used internally
 
 /// Format strings for basic number types
 #define PYBIND11_DECL_FMT(t, v) template<> struct format_descriptor<t> \
-    { static constexpr const char* value() { return v; } };
+    { static constexpr const char* value = v; /* for backwards compatibility */ \
+      static constexpr const char* format() { return value; } }
 
 template <typename T, typename SFINAE = void> struct format_descriptor { };
 
 template <typename T> struct format_descriptor<T, typename std::enable_if<std::is_integral<T>::value>::type> {
-    static constexpr const char* value() { return format; }
-    static constexpr const char format[2] =
+    static constexpr const char value[2] =
         { "bBhHiIqQ"[detail::log2(sizeof(T))*2 + (std::is_unsigned<T>::value ? 1 : 0)], '\0' };
+    static constexpr const char* format() { return value; }
 };
 
 template <typename T> constexpr const char format_descriptor<
-    T, typename std::enable_if<std::is_integral<T>::value>::type>::format[2];
+    T, typename std::enable_if<std::is_integral<T>::value>::type>::value[2];
 
 PYBIND11_DECL_FMT(float, "f");
 PYBIND11_DECL_FMT(double, "d");

include/pybind11/eigen.h

@@ -133,7 +133,7 @@ struct type_caster<Type, typename std::enable_if<is_eigen_dense<Type>::value &&
                 /* Size of one scalar */
                 sizeof(Scalar),
                 /* Python struct-style format descriptor */
-                format_descriptor<Scalar>::value(),
+                format_descriptor<Scalar>::format(),
                 /* Number of dimensions */
                 1,
                 /* Buffer dimensions */
@@ -148,7 +148,7 @@ struct type_caster<Type, typename std::enable_if<is_eigen_dense<Type>::value &&
                 /* Size of one scalar */
                 sizeof(Scalar),
                 /* Python struct-style format descriptor */
-                format_descriptor<Scalar>::value(),
+                format_descriptor<Scalar>::format(),
                 /* Number of dimensions */
                 isVector ? 1 : 2,
                 /* Buffer dimensions */
@@ -276,7 +276,7 @@ struct type_caster<Type, typename std::enable_if<is_eigen_sparse<Type>::value>::
             // Size of one scalar
             sizeof(Scalar),
             // Python struct-style format descriptor
-            format_descriptor<Scalar>::value(),
+            format_descriptor<Scalar>::format(),
             // Number of dimensions
             1,
             // Buffer dimensions
@@ -291,7 +291,7 @@ struct type_caster<Type, typename std::enable_if<is_eigen_sparse<Type>::value>::
             // Size of one scalar
             sizeof(StorageIndex),
             // Python struct-style format descriptor
-            format_descriptor<StorageIndex>::value(),
+            format_descriptor<StorageIndex>::format(),
             // Number of dimensions
             1,
             // Buffer dimensions
@@ -306,7 +306,7 @@ struct type_caster<Type, typename std::enable_if<is_eigen_sparse<Type>::value>::
             // Size of one scalar
             sizeof(StorageIndex),
             // Python struct-style format descriptor
-            format_descriptor<StorageIndex>::value(),
+            format_descriptor<StorageIndex>::format(),
             // Number of dimensions
             1,
             // Buffer dimensions

include/pybind11/numpy.h

@@ -164,8 +164,8 @@ template <typename T> struct format_descriptor
                             !std::is_same<T, std::complex<float>>::value &&
                             !std::is_same<T, std::complex<double>>::value>::type>
 {
-    static const char *value() {
-        return detail::npy_format_descriptor<T>::format_str();
+    static const char *format() {
+        return detail::npy_format_descriptor<T>::format();
     }
 };
 
@@ -231,8 +231,8 @@ template <typename T> struct npy_format_descriptor
         return object(descr_(), true);
     }
 
-    static const char* format_str() {
-        return format_str_();
+    static const char* format() {
+        return format_();
     }
 
     static void register_dtype(std::initializer_list<field_descriptor> fields) {
@@ -256,7 +256,7 @@ template <typename T> struct npy_format_descriptor
         if (auto arr = (object) empty(int_(0), object(descr(), true)))
             if (auto view = PyMemoryView_FromObject(arr.ptr()))
                 if (auto info = PyMemoryView_GET_BUFFER(view)) {
-                    std::strncpy(format_str_(), info->format, 4096);
+                    std::strncpy(format_(), info->format, 4096);
                     return;
                 }
         pybind11_fail("NumPy: failed to extract buffer format");
@@ -264,7 +264,7 @@ template <typename T> struct npy_format_descriptor
 
 private:
     static inline PyObject*& descr_() { static PyObject *ptr = nullptr; return ptr; }
-    static inline char* format_str_() { static char s[4096]; return s; }
+    static inline char* format_() { static char s[4096]; return s; }
 };
 
 #define FIELD_DESCRIPTOR(Type, Field) \
@@ -480,7 +480,7 @@ struct vectorize_helper {
             return cast(f(*((Args *) buffers[Index].ptr)...));
 
         array result(buffer_info(nullptr, sizeof(Return),
-                     format_descriptor<Return>::value(),
+                     format_descriptor<Return>::format(),
             ndim, shape, strides));
 
         buffer_info buf = result.request();