Struct pyo3::buffer::PyBuffer

source ·
pub struct PyBuffer<T>(/* private fields */);
Available on non-Py_LIMITED_API or Py_3_11 only.
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>

source

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

Deprecated form of PyBuffer::get_bound

source

pub fn get_bound(obj: &Bound<'_, PyAny>) -> PyResult<PyBuffer<T>>

Gets the underlying buffer from the specified python object.

source

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.

source

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.

source

pub fn readonly(&self) -> bool

Gets whether the underlying buffer is read-only.

source

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

source

pub fn item_count(&self) -> usize

Gets the total number of items.

source

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.

source

pub fn dimensions(&self) -> usize

Gets the number of dimensions.

May be 0 to indicate a single scalar value.

source

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.

source

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.

source

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

source

pub fn format(&self) -> &CStr

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

source

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

source

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

source

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.

source

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.

source

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.

source

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.

source

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

source

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

source

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.

source

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.

source

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

source

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

source

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

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

This will automatically be called on drop.

Trait Implementations§

source§

impl<T> Debug for PyBuffer<T>

source§

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

Formats the value using the given formatter. Read more
source§

impl<T> Drop for PyBuffer<T>

source§

fn drop(&mut self)

Executes the destructor for this type. Read more
source§

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

source§

fn extract_bound(obj: &Bound<'_, PyAny>) -> PyResult<PyBuffer<T>>

Extracts Self from the bound smart pointer obj. Read more
source§

fn extract(ob: &'py PyAny) -> PyResult<Self>

Extracts Self from the source GIL Ref obj. Read more
source§

fn type_input() -> TypeInfo

Available on crate feature experimental-inspect only.
Extracts the type hint information for this type when it appears as an argument. Read more
source§

impl<T> Send for PyBuffer<T>

source§

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> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<'py, T> FromPyObjectBound<'_, 'py> for T
where T: FromPyObject<'py>,

source§

fn from_py_object_bound(ob: Borrowed<'_, 'py, PyAny>) -> Result<T, PyErr>

Extracts Self from the bound smart pointer obj. Read more
source§

fn type_input() -> TypeInfo

Available on crate feature experimental-inspect only.
Extracts the type hint information for this type when it appears as an argument. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> Ungil for T
where T: Send,