include/pybind11/numpy.h

16 #include <array>
40 class array; // Forward declaration
274 template <typename T, size_t N> struct is_std_array<std::array<T, N>> : std::true_type { };
285 // Computes underlying type and a comma-separated list of extents for array
286 // types (any mix of std::array and built-in arrays). An array of char is
289 template <typename T, size_t N> struct array_info<std::array<T, N>> {
306 // the size in the array extents.
308 template <size_t N> struct array_info<std::array<char, N>> : array_info_scalar<std::array<char, N>> { };
309 template <typename T, size_t N> struct array_info<T[N]> : array_info<std::array<T, N>> { };
333  * Proxy class providing unsafe, unchecked const access to array data.  This is constructed through
334  * the `unchecked<T, N>()` method of `array` or the `unchecked<N>()` method of `array_t<T>`.  `Dims`
344     conditional_t<Dynamic, const ssize_t *, std::array<ssize_t, (size_t) Dims>>
348     friend class pybind11::array;
371                 "Invalid number of indices for unchecked array reference");
376      * is to a 1-dimensional array.  When present, this is exactly equivalent to `obj(index)`.
390     /// Returns the number of dimensions of the array
393     /// Returns the total number of elements in the referenced array, i.e. the product of the shapes
404     /// memory may be larger if the referenced array has non-contiguous strides (e.g. for a slice).
412     friend class pybind11::array;
420                 "Invalid number of indices for unchecked array reference");
425      * reference is to a 1-dimensional array (or has runtime dimensions).  When present, this is
437     static_assert(Dim == 0 && Dim > 0 /* always fail */, "unchecked array proxy object is not castable");
538 class array : public buffer {
540     PYBIND11_OBJECT_CVT(array, buffer, detail::npy_api::get().PyArray_Check_, raw_array)
548     array() : array({{0}}, static_cast<const double *>(nullptr)) {}
553     // Constructs an array taking shape/strides from arbitrary container types
554     array(const pybind11::dtype &dt, ShapeContainer shape, StridesContainer strides,
567             if (isinstance<array>(base))
569                 flags = reinterpret_borrow<array>(base).flags() & ~detail::npy_api::NPY_ARRAY_OWNDATA_;
591     array(const pybind11::dtype &dt, ShapeContainer shape, const void *ptr = nullptr, handle base = handle())
592         : array(dt, std::move(shape), {}, ptr, base) { }
595     array(const pybind11::dtype &dt, T count, const void *ptr = nullptr, handle base = handle())
596         : array(dt, {{count}}, ptr, base) { }
599     array(ShapeContainer shape, StridesContainer strides, const T *ptr, handle base = handle())
600         : array(pybind11::dtype::of<T>(), std::move(shape), std::move(strides), ptr, base) { }
603     array(ShapeContainer shape, const T *ptr, handle base = handle())
604         : array(std::move(shape), {}, ptr, base) { }
607     explicit array(ssize_t count, const T *ptr, handle base = handle()) : array({count}, {}, ptr, base) { }
609     explicit array(const buffer_info &info)
610     : array(pybind11::dtype(info), info.shape, info.strides, info.ptr) { }
642     /// Dimensions of the array
654     /// Strides of the array
666     /// Return the NumPy array flags
671     /// If set, the array is writeable (otherwise the buffer is read-only)
676     /// If set, the array owns the data (will be freed when the array is deleted)
689     /// May throw if the array is not writeable.
695     /// Byte offset from beginning of the array to a given index (full or partial).
699             fail_dim_check(sizeof...(index), "too many indices for an array");
705     /// Item count from beginning of the array to a given index (full or partial).
712      * Returns a proxy object that provides access to the array's data without bounds or
713      * dimensionality checking.  Will throw if the array is missing the `writeable` flag.  Use with
714      * care: the array must not be destroyed or reshaped for the duration of the returned object,
719             throw std::domain_error("array has incorrect number of dimensions: " + std::to_string(ndim()) +
725      * Returns a proxy object that provides const access to the array's data without bounds or
727      * underlying array have the `writable` flag.  Use with care: the array must not be destroyed or
733             throw std::domain_error("array has incorrect number of dimensions: " + std::to_string(ndim()) +
739     array squeeze() {
741         return reinterpret_steal<array>(api.PyArray_Squeeze_(m_ptr));
744     /// Resize array to given shape
745     /// If refcheck is true and more that one reference exist to this array
756         if (isinstance<array>(new_array)) { *this = std::move(new_array); }
759     /// Ensure that the argument is a NumPy array
761     static array ensure(handle h, int ExtraFlags = 0) {
762         auto result = reinterpret_steal<array>(raw_array(h.ptr(), ExtraFlags));
783             throw std::domain_error("array is not writeable");
820     /// Create array from any object -- always returns a new reference
823             PyErr_SetString(PyExc_ValueError, "cannot create a pybind11::array from a nullptr");
831 template <typename T, int ExtraFlags = array::forcecast> class array_t : public array {
836         : array(std::move(shape), std::move(strides), ptr, base) {}
842     array_t() : array(0, static_cast<const T *>(nullptr)) {}
843     array_t(handle h, borrowed_t) : array(h, borrowed_t{}) { }
844     array_t(handle h, stolen_t) : array(h, stolen_t{}) { }
847     array_t(handle h, bool is_borrowed) : array(raw_array_t(h.ptr()), stolen_t{}) {
852     array_t(const object &o) : array(raw_array_t(o.ptr()), stolen_t{}) {
856     explicit array_t(const buffer_info& info) : array(info) { }
859         : array(std::move(shape), std::move(strides), ptr, base) { }
867         : array({count}, {}, ptr, base) { }
878         return static_cast<const T*>(array::data(index...));
882         return static_cast<T*>(array::mutable_data(index...));
889         return *(static_cast<const T*>(array::data()) + byte_offset(ssize_t(index)...) / itemsize());
896         return *(static_cast<T*>(array::mutable_data()) + byte_offset(ssize_t(index)...) / itemsize());
900      * Returns a proxy object that provides access to the array's data without bounds or
901      * dimensionality checking.  Will throw if the array is missing the `writeable` flag.  Use with
902      * care: the array must not be destroyed or reshaped for the duration of the returned object,
906         return array::mutable_unchecked<T, Dims>();
910      * Returns a proxy object that provides const access to the array's data without bounds or
912      * array have the `writable` flag.  Use with care: the array must not be destroyed or reshaped
917         return array::unchecked<T, Dims>();
920     /// Ensure that the argument is a NumPy array of the correct dtype (and if not, try to convert
936     /// Create array from any object -- always returns a new reference
958 template <size_t N> struct format_descriptor<std::array<char, N>> {
1056 template <size_t N> struct npy_format_descriptor<std::array<char, N>> { PYBIND11_DECL_CHAR_FMT };
1143     auto arr =  array(buffer_info(nullptr, itemsize, format_str, 1));
1315     multi_array_iterator(const std::array<buffer_info, N> &buffers,
1382     std::array<common_iter, N> m_common_iterator;
1392 broadcast_trivial broadcast(const std::array<buffer_info, N> &buffers, ssize_t &ndim, std::vector<ssize_t> &shape) {
1475     // Accept this type: an array for vectorized types, otherwise the type as-is:
1476     using type = conditional_t<vectorize, array_t<remove_cv_t<call_type>, array::forcecast>, T>;
1511     //       we can store vectorized buffer_infos in an array (argument VIndex has its buffer at
1512     //       index BIndex in the array).
1520         std::array<void *, N> params{{ &args... }};
1522         // The array of `buffer_info`s of vectorized arguments:
1523         std::array<buffer_info, NVectorized> buffers{{ reinterpret_cast<array *>(params[VIndex])->request()... }};
1525         /* Determine dimensions parameters of output array */
1534         // not wrapped in an array).
1541         if (trivial == broadcast_trivial::f_trivial) result = array_t<Return, array::f_style>(shape);
1556     void apply_trivial(std::array<buffer_info, NVectorized> &buffers,
1557                        std::array<void *, N> &params,
1562         // Initialize an array of mutable byte references and sizes with references set to the
1565         std::array<std::pair<unsigned char *&, const size_t>, NVectorized> vecparams{{
1579     void apply_broadcast(std::array<buffer_info, NVectorized> &buffers,
1580                          std::array<void *, N> &params,