pub unsafe trait Element:
Sized
+ Send
+ Sync {
const IS_COPY: bool;
// Required methods
fn get_dtype(py: Python<'_>) -> Bound<'_, PyArrayDescr>;
fn clone_ref(&self, py: Python<'_>) -> Self;
// Provided methods
fn get_dtype_bound(py: Python<'_>) -> Bound<'_, PyArrayDescr> { ... }
fn vec_from_slice(py: Python<'_>, slc: &[Self]) -> Vec<Self> { ... }
fn array_from_view<D>(
py: Python<'_>,
view: ArrayView<'_, Self, D>,
) -> Array<Self, D>
where D: Dimension { ... }
}Expand description
Represents that a type can be an element of PyArray.
Currently, only integer/float/complex/object types are supported. The NumPy documentation list the other built-in types which we are not yet implemented.
Note that NumPy’s integer types like numpy.int_ and numpy.uint are based on C’s integer hierarchy
which implies that their widths change depending on the platform’s data model.
For example, numpy.int_ matches C’s long which is 32 bits wide on Windows (using the LLP64 data model)
but 64 bits wide on Linux (using the LP64 data model).
In contrast, Rust’s isize and usize types are defined to have the same width as a pointer
and are therefore always 64 bits wide on 64-bit platforms. If you want to match NumPy’s behaviour,
consider using the c_long and c_ulong type aliases.
§Safety
A type T that implements this trait should be safe when managed by a NumPy
array, thus implementing this trait is marked unsafe. Data types that don’t
contain Python objects (i.e., either the object type itself or record types
containing object-type fields) are assumed to be trivially copyable, which
is reflected in the IS_COPY flag. Furthermore, it is assumed that for
the object type the elements are pointers into the Python heap and that the
corresponding Clone implemenation will never panic as it only increases
the reference count.
§Custom element types
Note that we cannot safely store Py<T> where T: PyClass, because the type information would be
eliminated in the resulting NumPy array.
In other words, objects are always treated as Py<PyAny> (a.k.a. PyObject) by Python code,
and only Py<PyAny> can be stored in a type safe manner.
You can however create Array<Py<T>, D> and turn that into a NumPy array
safely and efficiently using from_owned_object_array.
Required Associated Constants§
Sourceconst IS_COPY: bool
const IS_COPY: bool
Flag that indicates whether this type is trivially copyable.
It should be set to true for all trivially copyable types (like scalar types and record/array types only containing trivially copyable fields and elements).
This flag should always be set to false for object types or record types
that contain object-type fields.
Required Methods§
Sourcefn get_dtype(py: Python<'_>) -> Bound<'_, PyArrayDescr>
fn get_dtype(py: Python<'_>) -> Bound<'_, PyArrayDescr>
Returns the associated type descriptor (“dtype”) for the given element type.
Provided Methods§
Sourcefn get_dtype_bound(py: Python<'_>) -> Bound<'_, PyArrayDescr>
👎Deprecated since 0.23.0: renamed to Element::get_dtype
fn get_dtype_bound(py: Python<'_>) -> Bound<'_, PyArrayDescr>
Element::get_dtypeDeprecated name for Element::get_dtype.
Sourcefn vec_from_slice(py: Python<'_>, slc: &[Self]) -> Vec<Self>
fn vec_from_slice(py: Python<'_>, slc: &[Self]) -> Vec<Self>
Create an owned copy of the slice while the GIL is guaranteed to be held.
Some types may provide implementations of this method that are more efficient
than simply mapping the py_clone method to each element in the slice.
Sourcefn array_from_view<D>(
py: Python<'_>,
view: ArrayView<'_, Self, D>,
) -> Array<Self, D>where
D: Dimension,
fn array_from_view<D>(
py: Python<'_>,
view: ArrayView<'_, Self, D>,
) -> Array<Self, D>where
D: Dimension,
Create an owned copy of the array while the GIL is guaranteed to be held.
Some types may provide implementations of this method that are more efficient
than simply mapping the py_clone method to each element in the view.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.