Struct pyo3::buffer::PyBuffer

#[repr(transparent)]
pub struct PyBuffer<T>(_, _);

Available on non-Py_LIMITED_API or Py_3_11 only.

Allows access to the underlying buffer used by a python object such as bytes, bytearray or array.array.

Implementations

impl<T: Element> PyBuffer<T>

pub fn get(obj: &PyAny) -> PyResult<PyBuffer<T>>

Get the underlying buffer from the specified python object.

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.

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.

pub fn readonly(&self) -> bool

Gets whether the underlying buffer is read-only.

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

pub fn item_count(&self) -> usize

Gets the total number of items.

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.

pub fn dimensions(&self) -> usize

Gets the number of dimensions.

May be 0 to indicate a single scalar value.

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.

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.

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).

pub fn format(&self) -> &CStr

A NUL terminated string in struct module style syntax describing the contents of a single item.

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).

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).

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.

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.

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.

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.

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()).

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()).

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.

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.

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()).

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()).

pub fn release(self, _py: Python<'_>)

Release the buffer object, freeing the reference to the Python object which owns the buffer.

Trait Implementations

impl<T> Debug for PyBuffer<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Drop for PyBuffer<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<'source, T: Element> FromPyObject<'source> for PyBuffer<T>

fn extract(obj: &PyAny) -> PyResult<PyBuffer<T>>

Extracts Self from the source PyObject.

impl<T> Send for PyBuffer<T>

impl<T> Sync for PyBuffer<T>