From 22e7d50ef9e4632c386115c4047a5799ebe8a12b Mon Sep 17 00:00:00 2001 From: Adam Reichold Date: Sat, 11 Nov 2023 12:28:48 +0100 Subject: [PATCH] Add documentation on the consequences of NumPy matching C's integeer hierarchy. --- src/dtype.rs | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/dtype.rs b/src/dtype.rs index 0c6f6b01a..f8183c0ce 100644 --- a/src/dtype.rs +++ b/src/dtype.rs @@ -368,6 +368,15 @@ impl PyArrayDescr { /// Currently, only integer/float/complex/object types are supported. The [NumPy documentation][enumerated-types] /// 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][data-models]. +/// 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`][std::ffi::c_long] and [`c_ulong`][std::ffi::c_ulong] type aliases. +/// /// # Safety /// /// A type `T` that implements this trait should be safe when managed by a NumPy @@ -390,6 +399,7 @@ impl PyArrayDescr { /// safely and efficiently using [`from_owned_object_array`][crate::PyArray::from_owned_object_array]. /// /// [enumerated-types]: https://numpy.org/doc/stable/reference/c-api/dtype.html#enumerated-types +/// [data-models]: https://en.wikipedia.org/wiki/64-bit_computing#64-bit_data_models pub unsafe trait Element: Clone + Send { /// Flag that indicates whether this type is trivially copyable. ///