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>
impl<T> Ptr<T>
Sourcepub unsafe fn null() -> Self
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.
Sourcepub fn as_mut_raw_ptr(self) -> *mut T
pub fn as_mut_raw_ptr(self) -> *mut T
Returns the content as a raw const pointer.
Sourcepub fn as_raw_ptr(self) -> *const T
pub fn as_raw_ptr(self) -> *const T
Returns the content as a raw const pointer.
Sourcepub unsafe fn as_ref(self) -> Option<Ref<T>>
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.
Sourcepub unsafe fn as_raw_ref<'a>(self) -> Option<&'a T>
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.
Sourcepub unsafe fn as_mut_raw_ref<'a>(self) -> Option<&'a mut T>
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.
Sourcepub unsafe fn static_upcast<U>(self) -> Ptr<U>where
T: StaticUpcast<U>,
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.
Sourcepub unsafe fn static_downcast<U>(self) -> Ptr<U>where
T: StaticDowncast<U>,
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.
Sourcepub unsafe fn dynamic_cast<U>(self) -> Ptr<U>where
T: DynamicCast<U>,
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>
impl<V, T> Ptr<V>
Sourcepub unsafe fn as_slice<'a>(self) -> &'a [T]
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>
impl<V, T> Ptr<V>
Sourcepub unsafe fn as_mut_slice<'a>(self) -> &'a mut [T]
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,
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,
Sourcepub unsafe fn iter(self) -> CppIterator<T1, T2> ⓘ
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,
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,
Sourcepub unsafe fn iter_mut(self) -> CppIterator<T1, T2> ⓘ
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>
impl<T: CppDeletable> Ptr<T>
Trait Implementations§
Source§impl<'a, T, U> CastFrom<&'a CppBox<U>> for Ptr<T>where
U: StaticUpcast<T> + CppDeletable,
impl<'a, T, U> CastFrom<&'a CppBox<U>> for Ptr<T>where
U: StaticUpcast<T> + CppDeletable,
Source§impl<T> Deref for Ptr<T>
Allows to call member functions of T
and its base classes directly on the pointer.
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§impl<T, U> PartialOrd<U> for Ptr<T>
impl<T, U> PartialOrd<U> for Ptr<T>
impl<T> Copy for Ptr<T>
Creates another pointer to the same object.