Trait PyTupleMethods

pub trait PyTupleMethods<'py>: Sealed {
    // Required methods
    fn len(&self) -> usize;
    fn is_empty(&self) -> bool;
    fn as_sequence(&self) -> &Bound<'py, PySequence>;
    fn into_sequence(self) -> Bound<'py, PySequence>;
    fn get_slice(&self, low: usize, high: usize) -> Bound<'py, PyTuple>;
    fn get_item(&self, index: usize) -> PyResult<Bound<'py, PyAny>>;
    fn get_borrowed_item<'a>(
        &'a self,
        index: usize,
    ) -> PyResult<Borrowed<'a, 'py, PyAny>>;
    unsafe fn get_item_unchecked(&self, index: usize) -> Bound<'py, PyAny>;
    unsafe fn get_borrowed_item_unchecked<'a>(
        &'a self,
        index: usize,
    ) -> Borrowed<'a, 'py, PyAny>;
    fn as_slice(&self) -> &[Bound<'py, PyAny>];
    fn contains<V>(&self, value: V) -> PyResult<bool>
       where V: IntoPyObject<'py>;
    fn index<V>(&self, value: V) -> PyResult<usize>
       where V: IntoPyObject<'py>;
    fn iter(&self) -> BoundTupleIterator<'py> ;
    fn iter_borrowed<'a>(&'a self) -> BorrowedTupleIterator<'a, 'py> ;
    fn to_list(&self) -> Bound<'py, PyList>;
}

Implementation of functionality for PyTuple.

These methods are defined for the Bound<'py, PyTuple> smart pointer, so to use method call syntax these methods are separated into a trait, because stable Rust does not yet support arbitrary_self_types.

Required Methods

fn len(&self) -> usize

Gets the length of the tuple.

fn is_empty(&self) -> bool

Checks if the tuple is empty.

fn as_sequence(&self) -> &Bound<'py, PySequence>

Returns self cast as a PySequence.

fn into_sequence(self) -> Bound<'py, PySequence>

Returns self cast as a PySequence.

fn get_slice(&self, low: usize, high: usize) -> Bound<'py, PyTuple>

Takes the slice self[low:high] and returns it as a new tuple.

Indices must be nonnegative, and out-of-range indices are clipped to self.len().

fn get_item(&self, index: usize) -> PyResult<Bound<'py, PyAny>>

Gets the tuple item at the specified index.

Example

use pyo3::prelude::*;

Python::with_gil(|py| -> PyResult<()> {
    let tuple = (1, 2, 3).into_pyobject(py)?;
    let obj = tuple.get_item(0);
    assert_eq!(obj?.extract::<i32>()?, 1);
    Ok(())
})

fn get_borrowed_item<'a>( &'a self, index: usize, ) -> PyResult<Borrowed<'a, 'py, PyAny>>

Like get_item, but returns a borrowed object, which is a slight performance optimization by avoiding a reference count change.

unsafe fn get_item_unchecked(&self, index: usize) -> Bound<'py, PyAny>

Available on neither Py_LIMITED_API nor PyPy nor GraalPy.

Gets the tuple item at the specified index. Undefined behavior on bad index. Use with caution.

Safety

Caller must verify that the index is within the bounds of the tuple.

unsafe fn get_borrowed_item_unchecked<'a>( &'a self, index: usize, ) -> Borrowed<'a, 'py, PyAny>

Available on neither Py_LIMITED_API nor PyPy nor GraalPy.

Like get_item_unchecked, but returns a borrowed object, which is a slight performance optimization by avoiding a reference count change.

Safety

Caller must verify that the index is within the bounds of the tuple.

fn as_slice(&self) -> &[Bound<'py, PyAny>]

Available on neither Py_LIMITED_API nor GraalPy.

Returns self as a slice of objects.

fn contains<V>(&self, value: V) -> PyResult<bool>

where V: IntoPyObject<'py>,

Determines if self contains value.

This is equivalent to the Python expression value in self.

fn index<V>(&self, value: V) -> PyResult<usize>

where V: IntoPyObject<'py>,

Returns the first index i for which self[i] == value.

This is equivalent to the Python expression self.index(value).

fn iter(&self) -> BoundTupleIterator<'py>

Returns an iterator over the tuple items.

fn iter_borrowed<'a>(&'a self) -> BorrowedTupleIterator<'a, 'py>

Like iter, but produces an iterator which returns borrowed objects, which is a slight performance optimization by avoiding a reference count change.

fn to_list(&self) -> Bound<'py, PyList>

Return a new list containing the contents of this tuple; equivalent to the Python expression list(tuple).

This method is equivalent to self.as_sequence().to_list() and faster than PyList::new(py, self).

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<'py> PyTupleMethods<'py> for Bound<'py, PyTuple>