Struct Ptr

pub struct Ptr<T>(/* private fields */);

A const pointer to a C++ object (similar to a C++ pointer).

A Ptr may or may not be owned. If you actually own the object, it’s recommended to convert it to CppBox using to_box method.

Note that unlike Rust references, Ptr can be freely copied, producing multiple pointers to the same object, which is usually necessary to do when working with C++ libraries.

Ptr implements operator traits and delegates them to the corresponding C++ operators. This means that you can use &ptr + value to access the object’s operator+.

Ptr implements Deref, allowing to call the object’s methods directly. In addition, methods of the object’s first base class are also directly available thanks to nested Deref implementations.

Ptr can contain a null pointer. Deref will panic if attempted to dereference a null pointer.

If the object provides an iterator interface through begin() and end() functions, Ptr will implement IntoIterator, so you can iterate on it directly.

Safety

It’s not possible to automatically track the ownership of objects possibly managed by C++ libraries. The user must ensure that the object is alive while Ptr exists. Note that with Ptr, it’s possible to call unsafe C++ code without using any more unsafe Rust code, for example, by using operator traits, so care should be taken when exposing Ptr in a safe interface.

Null pointers must not be dereferenced.

Implementations

impl<T> Ptr<T>

pub unsafe fn from_raw(ptr: *const T) -> Self

Creates a Ptr from a raw pointer.

Safety

See type level documentation.

pub unsafe fn null() -> Self

Creates a null pointer.

Note that you can also use NullPtr to specify a null pointer to a function accepting impl CastInto<Ptr<_>>. Unlike Ptr, NullPtr is not a generic type, so it will not cause type inference issues.

Safety

Null pointers must not be dereferenced. See type level documentation.

pub fn as_raw_ptr(self) -> *const T

Returns the content as a raw const pointer.

pub unsafe fn as_ref(self) -> Option<Ref<T>>

Returns the content as a const Ref. Returns None if self is a null pointer.

Safety

The operation is safe as long as self is valid or null. See type level documentation.

pub fn is_null(self) -> bool

Returns true if the pointer is null.

pub unsafe fn static_upcast<U>(self) -> Ptr<U>

where T: StaticUpcast<U>,

Converts the pointer to the base class type U.

Safety

This operation is safe as long as self is valid or null.

pub unsafe fn static_downcast<U>(self) -> Ptr<U>

where T: StaticDowncast<U>,

Converts the pointer to the derived class type U.

It’s recommended to use dynamic_cast instead because it performs a checked conversion.

Safety

This operation is safe as long as self is valid and it’s type is U or inherits from U, of if self is a null pointer.

pub unsafe fn dynamic_cast<U>(self) -> Ptr<U>

where T: DynamicCast<U>,

Converts the pointer to the derived class type U. Returns None if the object’s type is not U and doesn’t inherit U.

Safety

This operation is safe as long as self is valid or null.

pub unsafe fn begin(self) -> <&'static T as Begin>::Output

where &'static T: Begin,

Returns a C++ const iterator object pointing to the beginning of the collection.

It’s recommended to iterate directly on a Ptr<T> when possible, using automatic IntoIterator implementation.

Safety

self must be valid. It’s not possible to make any guarantees about safety, since this function calls arbitrary C++ library code.

pub unsafe fn end(self) -> <&'static T as End>::Output

where &'static T: End,

Returns a C++ const iterator object pointing to the end of the collection.

It’s recommended to iterate directly on a Ptr<T> when possible, using automatic IntoIterator implementation.

Safety

self must be valid. It’s not possible to make any guarantees about safety, since this function calls arbitrary C++ library code.

pub unsafe fn as_slice<'a, T1>(self) -> &'a [T1]

where T: 'static, &'static T: Begin<Output = Ptr<T1>> + End<Output = Ptr<T1>>,

Returns a slice corresponding to the object. This function is available when begin() and end() functions of the object return pointers.

Safety

self must be valid. It’s not possible to make any guarantees about safety, since this function calls arbitrary C++ library code. It’s not recommended to store the slice because it may be modified by the C++ library, which would violate Rust’s aliasing rules.

impl Ptr<c_char>

Allows to call member functions of T and its base classes directly on the pointer.

pub unsafe fn from_c_str(str: &CStr) -> Self

Creates a Ptr<c_char>, i.e. C++’s const char* from a CStr.

Safety

The source str must be valid while Ptr exists and while it’s used by the C++ library.

After passing str to Ptr, it’s unsafe to use str and any references to the same buffer from Rust because the memory can be modified through Ptr.

pub unsafe fn to_c_str<'a>(self) -> &'a CStr

Converts Ptr<c_char>, i.e. C++’s const char* to a &CStr.

Safety

No guarantees can be made about the validity and lifetime of the buffer, since it could be produced by a C++ library.

Trait Implementations

impl<T: 'static, U> Add<U> for Ptr<T>

where &'static T: Add<U>,

type Output = <&'static T as Add<U>>::Output

The resulting type after applying the + operator.

fn add(self, rhs: U) -> Self::Output

Performs the + operation.

impl<T: 'static, U> BitAnd<U> for Ptr<T>

where &'static T: BitAnd<U>,

type Output = <&'static T as BitAnd<U>>::Output

The resulting type after applying the & operator.

fn bitand(self, rhs: U) -> Self::Output

Performs the & operation.

impl<T: 'static, U> BitOr<U> for Ptr<T>

where &'static T: BitOr<U>,

type Output = <&'static T as BitOr<U>>::Output

The resulting type after applying the | operator.

fn bitor(self, rhs: U) -> Self::Output

Performs the | operation.

impl<T: 'static, U> BitXor<U> for Ptr<T>

where &'static T: BitXor<U>,

type Output = <&'static T as BitXor<U>>::Output

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: U) -> Self::Output

Performs the ^ operation.

impl<'a> CastFrom<&'a CStr> for Ptr<c_char>

unsafe fn cast_from(value: &'a CStr) -> Self

Performs the conversion.

impl<'a, T, U> CastFrom<&'a CppBox<U>> for Ptr<T>

where U: StaticUpcast<T> + CppDeletable,

unsafe fn cast_from(value: &'a CppBox<U>) -> Self

Performs the conversion.

impl<T, U> CastFrom<*const U> for Ptr<T>

where U: StaticUpcast<T>,

unsafe fn cast_from(value: *const U) -> Self

Performs the conversion.

impl<T, U> CastFrom<*mut U> for Ptr<T>

where U: StaticUpcast<T>,

unsafe fn cast_from(value: *mut U) -> Self

Performs the conversion.

impl<T, U> CastFrom<MutPtr<U>> for Ptr<T>

where U: StaticUpcast<T>,

unsafe fn cast_from(value: MutPtr<U>) -> Self

Performs the conversion.

impl<T, U> CastFrom<MutRef<U>> for Ptr<T>

where U: StaticUpcast<T>,

unsafe fn cast_from(value: MutRef<U>) -> Self

Performs the conversion.

impl<T> CastFrom<NullPtr> for Ptr<T>

unsafe fn cast_from(_value: NullPtr) -> Self

Performs the conversion.

impl<T, U> CastFrom<Ptr<U>> for Ptr<T>

where U: StaticUpcast<T>,

unsafe fn cast_from(value: Ptr<U>) -> Self

Performs the conversion.

impl<T, U> CastFrom<Ref<U>> for Ptr<T>

where U: StaticUpcast<T>,

unsafe fn cast_from(value: Ref<U>) -> Self

Performs the conversion.

impl<T> Clone for Ptr<T>

Creates another pointer to the same object.

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for Ptr<T>

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

Formats the value using the given formatter.

impl<T> Deref for Ptr<T>

Allows to call member functions of T and its base classes directly on the pointer.

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: 'static, U> Div<U> for Ptr<T>

where &'static T: Div<U>,

type Output = <&'static T as Div<U>>::Output

The resulting type after applying the / operator.

fn div(self, rhs: U) -> Self::Output

Performs the / operation.

impl<T, T1, T2> IntoIterator for Ptr<T>

where T: 'static, &'static T: Begin<Output = CppBox<T1>> + End<Output = CppBox<T2>>, T1: CppDeletable + PartialEq<Ref<T2>> + 'static, T2: CppDeletable, &'static T1: Indirection, &'static mut T1: Increment,

type Item = <&'static T1 as Indirection>::Output

The type of the elements being iterated over.

type IntoIter = CppIterator<T1, T2>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: 'static, U> Mul<U> for Ptr<T>

where &'static T: Mul<U>,

type Output = <&'static T as Mul<U>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: U) -> Self::Output

Performs the * operation.

impl<T, U> PartialEq<U> for Ptr<T>

where T: PartialEq<U>,

fn eq(&self, rhs: &U) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, U> PartialOrd<U> for Ptr<T>

where T: Lt<U> + Le<U> + Gt<U> + Ge<U> + PartialEq<U>,

fn partial_cmp(&self, other: &U) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &U) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &U) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &U) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &U) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: 'static, U> Rem<U> for Ptr<T>

where &'static T: Rem<U>,

type Output = <&'static T as Rem<U>>::Output

The resulting type after applying the % operator.

fn rem(self, rhs: U) -> Self::Output

Performs the % operation.

impl<T: 'static, U> Shl<U> for Ptr<T>

where &'static T: Shl<U>,

type Output = <&'static T as Shl<U>>::Output

The resulting type after applying the << operator.

fn shl(self, rhs: U) -> Self::Output

Performs the << operation.

impl<T: 'static, U> Shr<U> for Ptr<T>

where &'static T: Shr<U>,

type Output = <&'static T as Shr<U>>::Output

The resulting type after applying the >> operator.

fn shr(self, rhs: U) -> Self::Output

Performs the >> operation.

impl<T: 'static, U> Sub<U> for Ptr<T>

where &'static T: Sub<U>,

type Output = <&'static T as Sub<U>>::Output

The resulting type after applying the - operator.

fn sub(self, rhs: U) -> Self::Output

Performs the - operation.

impl<T> Copy for Ptr<T>

Creates another pointer to the same object.