pub struct PyBuffer<T>(/* private fields */);
Expand description
Allows access to the underlying buffer used by a python object such as bytes
, bytearray
or array.array
.
Implementations§
Source§impl<T: Element> PyBuffer<T>
impl<T: Element> PyBuffer<T>
Sourcepub fn get(obj: &Bound<'_, PyAny>) -> PyResult<PyBuffer<T>>
pub fn get(obj: &Bound<'_, PyAny>) -> PyResult<PyBuffer<T>>
Gets the underlying buffer from the specified python object.
Sourcepub fn get_bound(obj: &Bound<'_, PyAny>) -> PyResult<PyBuffer<T>>
👎Deprecated since 0.23.0: renamed to PyBuffer::get
pub fn get_bound(obj: &Bound<'_, PyAny>) -> PyResult<PyBuffer<T>>
PyBuffer::get
Deprecated name for PyBuffer::get
.
Sourcepub fn buf_ptr(&self) -> *mut c_void
pub fn buf_ptr(&self) -> *mut c_void
Gets the pointer to the start of the buffer memory.
Warning: the buffer memory might be mutated by other Python functions, and thus may only be accessed while the GIL is held.
Sourcepub fn get_ptr(&self, indices: &[usize]) -> *mut c_void
pub fn get_ptr(&self, indices: &[usize]) -> *mut c_void
Gets a pointer to the specified item.
If indices.len() < self.dimensions()
, returns the start address of the sub-array at the specified dimension.
Sourcepub fn item_size(&self) -> usize
pub fn item_size(&self) -> usize
Gets the size of a single element, in bytes. Important exception: when requesting an unformatted buffer, item_size still has the value
Sourcepub fn item_count(&self) -> usize
pub fn item_count(&self) -> usize
Gets the total number of items.
Sourcepub fn len_bytes(&self) -> usize
pub fn len_bytes(&self) -> usize
item_size() * item_count()
.
For contiguous arrays, this is the length of the underlying memory block.
For non-contiguous arrays, it is the length that the logical structure would have if it were copied to a contiguous representation.
Sourcepub fn dimensions(&self) -> usize
pub fn dimensions(&self) -> usize
Gets the number of dimensions.
May be 0 to indicate a single scalar value.
Sourcepub fn shape(&self) -> &[usize]
pub fn shape(&self) -> &[usize]
Returns an array of length dimensions
. shape()[i]
is the length of the array in dimension number i
.
May return None for single-dimensional arrays or scalar values (dimensions() <= 1
);
You can call item_count()
to get the length of the single dimension.
Despite Python using an array of signed integers, the values are guaranteed to be non-negative. However, dimensions of length 0 are possible and might need special attention.
Sourcepub fn strides(&self) -> &[isize]
pub fn strides(&self) -> &[isize]
Returns an array that holds, for each dimension, the number of bytes to skip to get to the next element in the dimension.
Stride values can be any integer. For regular arrays, strides are usually positive,
but a consumer MUST be able to handle the case strides[n] <= 0
.
Sourcepub fn suboffsets(&self) -> Option<&[isize]>
pub fn suboffsets(&self) -> Option<&[isize]>
An array of length ndim.
If suboffsets[n] >= 0
, the values stored along the nth dimension are pointers and the suboffset value dictates how many bytes to add to each pointer after de-referencing.
A suboffset value that is negative indicates that no de-referencing should occur (striding in a contiguous memory block).
If all suboffsets are negative (i.e. no de-referencing is needed), then this field must be NULL (the default value).
Sourcepub fn format(&self) -> &CStr
pub fn format(&self) -> &CStr
A NUL terminated string in struct module style syntax describing the contents of a single item.
Sourcepub fn is_c_contiguous(&self) -> bool
pub fn is_c_contiguous(&self) -> bool
Gets whether the buffer is contiguous in C-style order (last index varies fastest when visiting items in order of memory address).
Sourcepub fn is_fortran_contiguous(&self) -> bool
pub fn is_fortran_contiguous(&self) -> bool
Gets whether the buffer is contiguous in Fortran-style order (first index varies fastest when visiting items in order of memory address).
Sourcepub fn as_slice<'a>(&'a self, _py: Python<'a>) -> Option<&'a [ReadOnlyCell<T>]>
pub fn as_slice<'a>(&'a self, _py: Python<'a>) -> Option<&'a [ReadOnlyCell<T>]>
Gets the buffer memory as a slice.
This function succeeds if:
- the buffer format is compatible with
T
- alignment and size of buffer elements is matching the expectations for type
T
- the buffer is C-style contiguous
The returned slice uses type Cell<T>
because it’s theoretically possible for any call into the Python runtime
to modify the values in the slice.
Sourcepub fn as_mut_slice<'a>(&'a self, _py: Python<'a>) -> Option<&'a [Cell<T>]>
pub fn as_mut_slice<'a>(&'a self, _py: Python<'a>) -> Option<&'a [Cell<T>]>
Gets the buffer memory as a slice.
This function succeeds if:
- the buffer is not read-only
- the buffer format is compatible with
T
- alignment and size of buffer elements is matching the expectations for type
T
- the buffer is C-style contiguous
The returned slice uses type Cell<T>
because it’s theoretically possible for any call into the Python runtime
to modify the values in the slice.
Sourcepub fn as_fortran_slice<'a>(
&'a self,
_py: Python<'a>,
) -> Option<&'a [ReadOnlyCell<T>]>
pub fn as_fortran_slice<'a>( &'a self, _py: Python<'a>, ) -> Option<&'a [ReadOnlyCell<T>]>
Gets the buffer memory as a slice.
This function succeeds if:
- the buffer format is compatible with
T
- alignment and size of buffer elements is matching the expectations for type
T
- the buffer is Fortran-style contiguous
The returned slice uses type Cell<T>
because it’s theoretically possible for any call into the Python runtime
to modify the values in the slice.
Sourcepub fn as_fortran_mut_slice<'a>(
&'a self,
_py: Python<'a>,
) -> Option<&'a [Cell<T>]>
pub fn as_fortran_mut_slice<'a>( &'a self, _py: Python<'a>, ) -> Option<&'a [Cell<T>]>
Gets the buffer memory as a slice.
This function succeeds if:
- the buffer is not read-only
- the buffer format is compatible with
T
- alignment and size of buffer elements is matching the expectations for type
T
- the buffer is Fortran-style contiguous
The returned slice uses type Cell<T>
because it’s theoretically possible for any call into the Python runtime
to modify the values in the slice.
Sourcepub fn copy_to_slice(&self, py: Python<'_>, target: &mut [T]) -> PyResult<()>
pub fn copy_to_slice(&self, py: Python<'_>, target: &mut [T]) -> PyResult<()>
Copies the buffer elements to the specified slice. If the buffer is multi-dimensional, the elements are written in C-style order.
- Fails if the slice does not have the correct length (
buf.item_count()
). - Fails if the buffer format is not compatible with type
T
.
To check whether the buffer format is compatible before calling this method,
you can use <T as buffer::Element>::is_compatible_format(buf.format())
.
Alternatively, match buffer::ElementType::from_format(buf.format())
.
Sourcepub fn copy_to_fortran_slice(
&self,
py: Python<'_>,
target: &mut [T],
) -> PyResult<()>
pub fn copy_to_fortran_slice( &self, py: Python<'_>, target: &mut [T], ) -> PyResult<()>
Copies the buffer elements to the specified slice. If the buffer is multi-dimensional, the elements are written in Fortran-style order.
- Fails if the slice does not have the correct length (
buf.item_count()
). - Fails if the buffer format is not compatible with type
T
.
To check whether the buffer format is compatible before calling this method,
you can use <T as buffer::Element>::is_compatible_format(buf.format())
.
Alternatively, match buffer::ElementType::from_format(buf.format())
.
Sourcepub fn to_vec(&self, py: Python<'_>) -> PyResult<Vec<T>>
pub fn to_vec(&self, py: Python<'_>) -> PyResult<Vec<T>>
Copies the buffer elements to a newly allocated vector. If the buffer is multi-dimensional, the elements are written in C-style order.
Fails if the buffer format is not compatible with type T
.
Sourcepub fn to_fortran_vec(&self, py: Python<'_>) -> PyResult<Vec<T>>
pub fn to_fortran_vec(&self, py: Python<'_>) -> PyResult<Vec<T>>
Copies the buffer elements to a newly allocated vector. If the buffer is multi-dimensional, the elements are written in Fortran-style order.
Fails if the buffer format is not compatible with type T
.
Sourcepub fn copy_from_slice(&self, py: Python<'_>, source: &[T]) -> PyResult<()>
pub fn copy_from_slice(&self, py: Python<'_>, source: &[T]) -> PyResult<()>
Copies the specified slice into the buffer. If the buffer is multi-dimensional, the elements in the slice are expected to be in C-style order.
- Fails if the buffer is read-only.
- Fails if the slice does not have the correct length (
buf.item_count()
). - Fails if the buffer format is not compatible with type
T
.
To check whether the buffer format is compatible before calling this method,
use <T as buffer::Element>::is_compatible_format(buf.format())
.
Alternatively, match buffer::ElementType::from_format(buf.format())
.
Sourcepub fn copy_from_fortran_slice(
&self,
py: Python<'_>,
source: &[T],
) -> PyResult<()>
pub fn copy_from_fortran_slice( &self, py: Python<'_>, source: &[T], ) -> PyResult<()>
Copies the specified slice into the buffer. If the buffer is multi-dimensional, the elements in the slice are expected to be in Fortran-style order.
- Fails if the buffer is read-only.
- Fails if the slice does not have the correct length (
buf.item_count()
). - Fails if the buffer format is not compatible with type
T
.
To check whether the buffer format is compatible before calling this method,
use <T as buffer::Element>::is_compatible_format(buf.format())
.
Alternatively, match buffer::ElementType::from_format(buf.format())
.
Trait Implementations§
Source§impl<T: Element> FromPyObject<'_> for PyBuffer<T>
impl<T: Element> FromPyObject<'_> for PyBuffer<T>
impl<T> Send for PyBuffer<T>
impl<T> Sync for PyBuffer<T>
Auto Trait Implementations§
impl<T> Freeze for PyBuffer<T>
impl<T> RefUnwindSafe for PyBuffer<T>where
T: RefUnwindSafe,
impl<T> Unpin for PyBuffer<T>where
T: Unpin,
impl<T> UnwindSafe for PyBuffer<T>where
T: UnwindSafe,
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<'py, T> FromPyObjectBound<'_, 'py> for Twhere
T: FromPyObject<'py>,
impl<'py, T> FromPyObjectBound<'_, 'py> for Twhere
T: FromPyObject<'py>,
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read more