# pyo3::buffer::PyBuffer - Rust
Allows access to the underlying buffer used by a python object such as `bytes`, `bytearray` or `array.array`.
Keywords: rust, rustlang, rust-lang, PyBuffer

# Struct pyo3::buffer::PyBuffer [−] [src]

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

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

## Implementations

### `impl<T: Element> PyBuffer<T>` [src]

#### `pub fn get(obj: &PyAny) -> PyResult<PyBuffer<T>>` [src]

Get the underlying buffer from the specified python object.

#### `pub fn buf_ptr(&self) -> *mut c_void` [src]

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` [src]

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` [src]

Gets whether the underlying buffer is read-only.

#### `pub fn item_size(&self) -> usize` [src]

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` [src]

Gets the total number of items.

#### `pub fn len_bytes(&self) -> usize` [src]

`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` [src]

Gets the number of dimensions.

May be 0 to indicate a single scalar value.

#### `pub fn shape(&self) -> &[usize]` [src]

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]` [src]

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]>` [src]

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` [src]

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

#### `pub fn is_c_contiguous(&self) -> bool` [src]

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` [src]

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>]>` [src]

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>]>` [src]

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>]>` [src]

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>]>` [src]

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<()>` [src]

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<()>` [src]

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>>` [src]

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>>` [src]

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<()>` [src]

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<()>` [src]

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<'_>)` [src]

## Trait Implementations

### `impl<T> Drop for PyBuffer<T>` [src]

#### `fn drop(&mut self)` [src]

Executes the destructor for this type. Read more

### `impl<'source, T: Element> FromPyObject<'source> for PyBuffer<T>` [src]

#### `fn extract(obj: &PyAny) -> PyResult<PyBuffer<T>>` [src]

Extracts `Self` from the source `PyObject`.

### `impl<T> Send for PyBuffer<T>` [src]

### `impl<T> Sync for PyBuffer<T>` [src]

## Auto Trait Implementations

### `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

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId` [src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &T` [src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut T` [src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T` [src]

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` [src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

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

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.