Struct Ptr

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

A 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§

Source§

impl<T> Ptr<T>

Source

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

Creates a Ptr from a raw pointer.

§Safety

See type level documentation.

Source

pub unsafe fn null() -> Self

Creates a null pointer.

Note that accessing the content of a null Ptr through Deref will result in a panic.

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.

Source

pub fn as_mut_raw_ptr(self) -> *mut T

Returns the content as a raw const pointer.

Source

pub fn as_raw_ptr(self) -> *const T

Returns the content as a raw const pointer.

Source

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.

Source

pub unsafe fn as_raw_ref<'a>(self) -> Option<&'a T>

Returns a reference to the value. Returns None if the pointer is null.

§Safety

self must be valid. The content must not be read or modified through other ways while the returned reference exists.See type level documentation.

Source

pub unsafe fn as_mut_raw_ref<'a>(self) -> Option<&'a mut T>

Returns a mutable reference to the value. Returns None if the pointer is null.

§Safety

self must be valid. The content must not be read or modified through other ways while the returned reference exists.See type level documentation.

Source

pub fn is_null(self) -> bool

Returns true if the pointer is null.

Source

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.

Source

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.

Source

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.

Source§

impl<V, T> Ptr<V>
where V: Data<Output = *const T> + Size,

Source

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

Returns the content of the object as a slice, based on data() and size() methods.

§Safety

The caller must make sure self contains a valid pointer. The content must not be read or modified through other ways while the returned slice exists. This function may invoke arbitrary foreign code, so no safety guarantees can be made.

Source§

impl<V, T> Ptr<V>
where V: DataMut<Output = *mut T> + Size,

Source

pub unsafe fn as_mut_slice<'a>(self) -> &'a mut [T]

Returns the content of the vector as a mutable slice, based on data() and size() methods.

§Safety

The caller must make sure self contains a valid pointer. The content must not be read or modified through other ways while the returned slice exists. This function may invoke arbitrary foreign code, so no safety guarantees can be made.

Source§

impl<T, T1, T2> Ptr<T>
where T: Begin<Output = CppBox<T1>> + End<Output = CppBox<T2>>, T1: CppDeletable + PartialEq<Ref<T2>> + Increment + Indirection, T2: CppDeletable,

Source

pub unsafe fn iter(self) -> CppIterator<T1, T2>

Returns an iterator over the content of the object, based on begin() and end() methods.

§Safety

The caller must make sure self contains a valid pointer. The content must not be read or modified through other ways while the returned slice exists. This function may invoke arbitrary foreign code, so no safety guarantees can be made.

Source§

impl<T, T1, T2> Ptr<T>
where T: BeginMut<Output = CppBox<T1>> + EndMut<Output = CppBox<T2>>, T1: CppDeletable + PartialEq<Ref<T2>> + Increment + Indirection, T2: CppDeletable,

Source

pub unsafe fn iter_mut(self) -> CppIterator<T1, T2>

Returns a mutable iterator over the content of the object, based on begin() and end() methods.

§Safety

The caller must make sure self contains a valid pointer. The content must not be read or modified through other ways while the returned slice exists. This function may invoke arbitrary foreign code, so no safety guarantees can be made.

Source§

impl<T: CppDeletable> Ptr<T>

Source

pub unsafe fn to_box(self) -> Option<CppBox<T>>

Converts this pointer to a CppBox. Returns None if self is a null pointer.

Use this function to take ownership of the object. This is the same as CppBox::new.

§Safety

See type level documentation. See also CppBox::new documentation.

Trait Implementations§

Source§

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

Source§

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

The resulting type after applying the + operator.
Source§

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

Performs the + operation. Read more
Source§

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

Source§

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

The resulting type after applying the & operator.
Source§

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

Performs the & operation. Read more
Source§

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

Source§

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

The resulting type after applying the | operator.
Source§

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

Performs the | operation. Read more
Source§

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

Source§

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

The resulting type after applying the ^ operator.
Source§

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

Performs the ^ operation. Read more
Source§

impl<'a, T, U> CastFrom<&'a CppBox<U>> for Ptr<T>
where U: StaticUpcast<T> + CppDeletable,

Source§

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

Performs the conversion. Read more
Source§

impl<T, U> CastFrom<*const U> for Ptr<T>
where U: StaticUpcast<T>,

Source§

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

Performs the conversion. Read more
Source§

impl<T, U> CastFrom<*mut U> for Ptr<T>
where U: StaticUpcast<T>,

Source§

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

Performs the conversion. Read more
Source§

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

Source§

unsafe fn cast_from(_value: NullPtr) -> Self

Performs the conversion. Read more
Source§

impl<T, U> CastFrom<Ptr<U>> for Ptr<T>
where U: StaticUpcast<T>,

Source§

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

Performs the conversion. Read more
Source§

impl<T, U> CastFrom<Ref<U>> for Ptr<T>
where U: StaticUpcast<T>,

Source§

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

Performs the conversion. Read more
Source§

impl<T> Clone for Ptr<T>

Creates another pointer to the same object.

Source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from source. Read more
Source§

impl<T> Debug for Ptr<T>

Source§

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

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

impl<T> Deref for Ptr<T>

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

Panics if the pointer is null.

Source§

type Target = T

The resulting type after dereferencing.
Source§

fn deref(&self) -> &T

Dereferences the value.
Source§

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

Source§

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

The resulting type after applying the / operator.
Source§

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

Performs the / operation. Read more
Source§

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

Source§

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

The resulting type after applying the * operator.
Source§

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

Performs the * operation. Read more
Source§

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

Source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

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

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

impl<T, U> PartialOrd<U> for Ptr<T>
where T: Lt<U> + Le<U> + Gt<U> + Ge<U> + PartialEq<U>,

Source§

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

This method returns an ordering between self and other values if one exists. Read more
Source§

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

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

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

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

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

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

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

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

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

Source§

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

The resulting type after applying the % operator.
Source§

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

Performs the % operation. Read more
Source§

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

Source§

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

The resulting type after applying the << operator.
Source§

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

Performs the << operation. Read more
Source§

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

Source§

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

The resulting type after applying the >> operator.
Source§

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

Performs the >> operation. Read more
Source§

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

Source§

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

The resulting type after applying the - operator.
Source§

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

Performs the - operation. Read more
Source§

impl<T> Copy for Ptr<T>

Creates another pointer to the same object.

Auto Trait Implementations§

§

impl<T> Freeze for Ptr<T>

§

impl<T> RefUnwindSafe for Ptr<T>
where T: RefUnwindSafe,

§

impl<T> !Send for Ptr<T>

§

impl<T> !Sync for Ptr<T>

§

impl<T> Unpin for Ptr<T>

§

impl<T> UnwindSafe for Ptr<T>
where T: RefUnwindSafe,

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, U> CastInto<U> for T
where U: CastFrom<T>,

Source§

unsafe fn cast_into(self) -> U

Performs the conversion. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

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<P, T> Receiver for P
where P: Deref<Target = T> + ?Sized, T: ?Sized,

Source§

type Target = T

🔬This is a nightly-only experimental API. (arbitrary_self_types)
The target type on which the method may be called.
Source§

impl<T> StaticUpcast<T> for T

Source§

unsafe fn static_upcast(ptr: Ptr<T>) -> Ptr<T>

Convert type of a const pointer. Read more
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

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

Source§

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>,

Source§

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.