Struct Ref

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

A non-null, mutable pointer to a C++ object (similar to a C++ reference).

Ref never owns its content.

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

Ref 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+.

Ref 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.

If the object provides an iterator interface through begin() and end() functions, Ref 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 Ref exists. Note that with Ref, 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 Ref in a safe interface.

Implementations

impl<T> Ref<T>

pub unsafe fn new(ptr: Ptr<T>) -> Option<Self>

Creates a Ref from a Ptr. Returns None if ptr is null.

Safety

ptr must be valid. See type level documentation.

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

Creates a Ref from a raw pointer. Returns None if ptr is null.

Safety

ptr must be valid. See type level documentation.

pub unsafe fn from_raw_non_null(ptr: NonNull<T>) -> Self

Creates a Ref from a non-null pointer.

Safety

ptr must be valid. See type level documentation.

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

Converts self to a Ptr.

Safety

self must be valid. See type level documentation.

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

Returns a reference to the value.

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) -> &'a mut T

Returns a mutable reference to the value.

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 fn as_raw_ptr(self) -> *const T

Returns constant raw pointer to the value.

pub fn as_mut_raw_ptr(self) -> *mut T

Returns constant raw pointer to the value.

pub unsafe fn static_upcast<U>(self) -> Ref<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.

pub unsafe fn static_downcast<U>(self) -> Ref<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.

pub unsafe fn dynamic_cast<U>(self) -> Option<Ref<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.

impl<V, T> Ref<V>

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

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.

impl<V, T> Ref<V>

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

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.

impl<T, T1, T2> Ref<T>

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

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.

impl<T, T1, T2> Ref<T>

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

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.

Trait Implementations

impl<T: 'static, U> Add<U> for Ref<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 Ref<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 Ref<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 Ref<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, T, U> CastFrom<&'a CppBox<U>> for Ref<T>

where U: StaticUpcast<T> + CppDeletable,

unsafe fn cast_from(value: &'a CppBox<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, U> CastFrom<Ref<U>> for Ref<T>

where U: StaticUpcast<T>,

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

Performs the conversion.

impl<T> Clone for Ref<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> Debug for Ref<T>

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

Formats the value using the given formatter.

impl<T> Deref for Ref<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 Ref<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: 'static, U> Mul<U> for Ref<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 Ref<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 Ref<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 Ref<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 Ref<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 Ref<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 Ref<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 Ref<T>

Creates another pointer to the same object.