Struct qt_core::QPtr

pub struct QPtr<T: StaticUpcast<QObject>> { /* fields omitted */ }

A smart pointer that automatically sets to null when the object is deleted.

QPtr exposes functionality provided by the QPointer<T> C++ class. QPtr can only contain a pointer to a QObject-based object. When that object is deleted, QPtr automatically becomes a null pointer.

Note that dereferencing a null QPtr will panic, so if it's known that the object may already have been deleted, you should use is_null(), as_ref(), or a similar method to check if the object is still alive before calling its methods.

QPtr is not an owning pointer, similar to cpp_core::Ptr. If you actually own the object, you should convert it to QBox (it will delete the object when dropped if it has no parent) or CppBox (it will always delete the object when dropped). QPtr provides into_qbox and to_box helpers for that.

Safety

While QPtr is much safer than cpp_core::Ptr and prevents use-after-free in common cases, it is unsafe to use in Rust terms. QPtr::new must receive a valid pointer or a null pointer, otherwise the behavior is undefined. You should not store pointers of other types (e.g. Ptr, Ref, or raw pointers) produced by QPtr because, unlike QPtr, these pointers will not become null pointers when the object is deleted.

It's still possible to cause use-after-free by calling a method through QPtr. Even in a single threaded program, the accessed object can be deleted by a nested call while one of its methods is still running. In multithreaded context, the object can be deleted in another thread between the null check and the method call, also resulting in undefined behavior.

Methods

impl<T: StaticUpcast<QObject>> QPtr<T>

pub unsafe fn new(target: impl CastInto<Ptr<T>>) -> Self

Creates a QPtr from a Ptr.

Safety

target must be either a valid pointer to an object or a null pointer. See type level documentation.

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

Creates a QPtr from a raw pointer.

Safety

target must be either a valid pointer to an object or a null pointer. 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.

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

Safety

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

pub unsafe fn is_null(&self) -> bool

Returns true if the pointer is null.

Safety

See type level documentation.

pub unsafe fn as_ptr(&self) -> Ptr<T>

Returns the content as a const Ptr.

Safety

See type level documentation.

pub unsafe fn as_raw_ptr(&self) -> *const T

Returns the content as a raw const pointer.

Safety

See type level documentation.

pub unsafe fn as_mut_raw_ptr(&self) -> *mut T

Returns the content as a raw pointer.

Safety

See type level documentation.

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

See type level documentation.

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.

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.

pub unsafe fn static_upcast<U>(&self) -> QPtr<U> where
    T: StaticUpcast<U>,
    U: StaticUpcast<QObject>, 

Converts the pointer to the base class type U.

Safety

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

pub unsafe fn static_downcast<U>(&self) -> QPtr<U> where
    T: StaticDowncast<U>,
    U: StaticUpcast<QObject>, 

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. See type level documentation.

pub unsafe fn dynamic_cast<U>(&self) -> QPtr<U> where
    T: DynamicCast<U>,
    U: StaticUpcast<QObject>, 

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. See type level documentation.

pub unsafe fn to_box(&self) -> Option<CppBox<T>> where
    T: CppDeletable, 

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. CppBox will delete the object when dropped.

You can also use into_qbox to convert the pointer to a QBox. Unlike CppBox, QBox will only delete the object if it has no parent.

Safety

CppBox will attempt to delete the object on drop. If something else also tries to delete this object before or after that, the behavior is undefined. See type level documentation.

pub unsafe fn into_q_box(self) -> QBox<T> where
    T: CppDeletable, 

Converts this pointer to a QBox.

Use this function to take ownership of the object. This is the same as QBox::from_q_mut_ptr.

Safety

See type level documentation.

Trait Implementations

impl<'a, T, U> Add<U> for &'a QPtr<T> where
    T: StaticUpcast<QObject>,
    &'a T: Add<U>, 

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

The resulting type after applying the + operator.

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

Performs the + operation.

impl<'a, T: StaticUpcast<QObject>> AsReceiver for &'a QPtr<T> where
    T: AsReceiver, 

type Arguments = <T as AsReceiver>::Arguments

Argument types expected by this receiver.

fn as_receiver(&self) -> Receiver<Self::Arguments>

Returns information about this receiver.

impl<'a, T, U> BitAnd<U> for &'a QPtr<T> where
    T: StaticUpcast<QObject>,
    &'a T: BitAnd<U>, 

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

The resulting type after applying the & operator.

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

Performs the & operation.

impl<'a, T, U> BitOr<U> for &'a QPtr<T> where
    T: StaticUpcast<QObject>,
    &'a T: BitOr<U>, 

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

The resulting type after applying the | operator.

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

Performs the | operation.

impl<'a, T, U> BitXor<U> for &'a QPtr<T> where
    T: StaticUpcast<QObject>,
    &'a T: BitXor<U>, 

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

The resulting type after applying the ^ operator.

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

Performs the ^ operation.

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

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

Performs the conversion.

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

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

Performs the conversion.

impl<T: StaticUpcast<QObject>> Clone for QPtr<T>

Creates another pointer to the same object.

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: StaticUpcast<QObject>> Debug for QPtr<T>

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

Formats the value using the given formatter.

impl<T: StaticUpcast<QObject>> Deref for QPtr<T>

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

Panics if the pointer is null.

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<'a, T, U> Div<U> for &'a QPtr<T> where
    T: StaticUpcast<QObject>,
    &'a T: Div<U>, 

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

The resulting type after applying the / operator.

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

Performs the / operation.

impl<'a, T, U> Mul<U> for &'a QPtr<T> where
    T: StaticUpcast<QObject>,
    &'a T: Mul<U>, 

type Output = <&'a 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 QPtr<T> where
    T: PartialEq<U> + StaticUpcast<QObject>, 

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl<'a, T, U> Rem<U> for &'a QPtr<T> where
    T: StaticUpcast<QObject>,
    &'a T: Rem<U>, 

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

The resulting type after applying the % operator.

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

Performs the % operation.

impl<'a, T, U> Shl<U> for &'a QPtr<T> where
    T: StaticUpcast<QObject>,
    &'a T: Shl<U>, 

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

The resulting type after applying the << operator.

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

Performs the << operation.

impl<'a, T, U> Shr<U> for &'a QPtr<T> where
    T: StaticUpcast<QObject>,
    &'a T: Shr<U>, 

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

The resulting type after applying the >> operator.

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

Performs the >> operation.

impl<'a, T, U> Sub<U> for &'a QPtr<T> where
    T: StaticUpcast<QObject>,
    &'a T: Sub<U>, 

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

The resulting type after applying the - operator.

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

Performs the - operation.