Struct CppBox

Source
pub struct CppBox<T: CppDeletable>(/* private fields */);
Expand description

An owning pointer to a C++ object.

CppBox is automatically used in places where C++ class objects are passed by value and in return values of constructors because the ownership is apparent in these cases. However, sometimes an object is returned as a pointer but you must accept the ownership of the object. It’s not possible to automatically determine ownership semantics of C++ code in this case, so you should manually convert Ptr to CppBox using to_box method.

When CppBox is dropped, it will automatically delete the object using C++’s delete operator.

Objects stored in CppBox are usually placed on the heap by the C++ code.

If a C++ API accepts an object by pointer and takes ownership of it, it’s not possible to automatically detect this, so you must manually convert CppBox to a non-owning Ptr using into_ptr before passing it to such a function.

&CppBox<T> and &mut CppBox<T> implement operator traits and delegate them to the corresponding C++ operators. This means that you can use &box1 + value to access the object’s operator+.

CppBox implements Deref and DerefMut, 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, &CppBox<T> and &mut CppBox<T> will implement IntoIterator, so you can iterate on them 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 CppBox exists and that no pointers to the object are used after the object is deleted by CppBox’s Drop implementation. Note that with CppBox, it’s possible to call unsafe C++ code without using any more unsafe code, for example, by using operator traits or simply dropping the box, so care should be taken when exposing CppBox in a safe interface.

Implementations§

Source§

impl<T: CppDeletable> CppBox<T>

Source

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

Encapsulates the object into a CppBox. Returns None if the pointer is null.

The same operation can be done by calling to_box function on MutPtr.

You should use this function only for pointers that were created on C++ side and passed through a FFI boundary to Rust. An object created with C++ new must be deleted using C++ delete, which is executed by CppBox.

Do not use this function for objects that would be deleted by other means. If another C++ object is the owner of the passed object, it will attempt to delete it. If CppBox containing the object still exists, it would result in a double deletion, which must never happen.

Use CppBox::into_ptr to unwrap the pointer before passing it to a function that takes ownership of the object.

§Safety

The pointer must point to an object that can be safely deleted using C++’s delete operator. The object must not be deleted by other means while CppBox exists. Any other pointers to the object must not be used after CppBox is dropped.

Source

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

Encapsulates the object into a CppBox. Returns None if the pointer is null.

See CppBox::new for more information.

§Safety

The pointer must point to an object that can be safely deleted using C++’s delete operator. The object must not be deleted by other means while CppBox exists. Any other pointers to the object must not be used after CppBox is dropped.

Source§

impl<T: CppDeletable> CppBox<T>

Source

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

Returns a constant pointer to the value in the box.

§Safety

This operation is safe as long as self is valid.

Source

pub unsafe fn as_mut_ptr(&mut self) -> MutPtr<T>

Returns a mutable pointer to the value in the box.

§Safety

This operation is safe as long as self is valid.

Source

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

Returns a constant raw pointer to the value in the box.

Source

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

Returns a mutable raw pointer to the value in the box.

Source

pub fn into_raw_ptr(self) -> *mut T

Destroys the box without deleting the object and returns a raw pointer to the content. The caller of the function becomes the owner of the object and should ensure that the object will be deleted at some point.

Source

pub unsafe fn into_ptr(self) -> MutPtr<T>

Destroys the box without deleting the object and returns a pointer to the content. The caller of the function becomes the owner of the object and should ensure that the object will be deleted at some point.

§Safety

This operation is safe as long as self is valid.

Source

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

Returns a constant reference to the value in the box.

§Safety

This operation is safe as long as self is valid.

Source

pub unsafe fn as_mut_ref(&mut self) -> MutRef<T>

Returns a mutable reference to the value in the box.

§Safety

This operation is safe as long as self is valid.

Source

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

Returns a non-owning reference to the content converted to the base class type U. CppBox retains the ownership of the object.

§Safety

This operation is safe as long as self is valid.

Source

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

Returns a non-owning reference to the content converted to the derived class type U. CppBox retains the ownership of the object.

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.

Source

pub unsafe fn dynamic_cast<U>(&self) -> Option<Ref<U>>
where T: DynamicCast<U>,

Returns a non-owning reference to the content converted to the derived class type U. CppBox retains the ownership of the object. 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.

Source

pub unsafe fn static_upcast_mut<U>(&mut self) -> MutRef<U>
where T: StaticUpcast<U>,

Returns a non-owning reference to the content converted to the base class type U. CppBox retains the ownership of the object.

§Safety

This operation is safe as long as self is valid.

Source

pub unsafe fn static_downcast_mut<U>(&mut self) -> MutRef<U>
where T: StaticDowncast<U>,

Returns a non-owning reference to the content converted to the derived class type U. CppBox retains the ownership of the object.

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.

Source

pub unsafe fn dynamic_cast_mut<U>(&mut self) -> Option<MutRef<U>>
where T: DynamicCast<U>,

Returns a non-owning reference to the content converted to the derived class type U. CppBox retains the ownership of the object. 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.

Source

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

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

It’s recommended to iterate directly on a &CppBox<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.

Source

pub unsafe fn begin_mut(&mut self) -> <&'static mut T as BeginMut>::Output

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

It’s recommended to iterate directly on a &mut CppBox<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.

Source

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 &CppBox<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.

Source

pub unsafe fn end_mut(&mut self) -> <&'static mut T as EndMut>::Output

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

It’s recommended to iterate directly on a &mut CppBox<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.

Source

pub unsafe fn as_slice<'a, T1>(&'a 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.

Source

pub unsafe fn as_mut_slice<'a, T1>(&'a mut self) -> &'a mut [T1]
where T: 'static, &'static mut T: BeginMut<Output = MutPtr<T1>> + EndMut<Output = MutPtr<T1>>,

Returns a mutable 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.

Trait Implementations§

Source§

impl<'a, T: CppDeletable, U> Add<U> for &'a CppBox<T>
where &'a T: Add<U>,

Source§

type Output = <&'a 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, U> AddAssign<U> for CppBox<T>
where T: AddAssign<U> + CppDeletable,

Source§

fn add_assign(&mut self, rhs: U)

Performs the += operation. Read more
Source§

impl<'a, T: CppDeletable, U> BitAnd<U> for &'a CppBox<T>
where &'a T: BitAnd<U>,

Source§

type Output = <&'a 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, U> BitAndAssign<U> for CppBox<T>
where T: BitAndAssign<U> + CppDeletable,

Source§

fn bitand_assign(&mut self, rhs: U)

Performs the &= operation. Read more
Source§

impl<'a, T: CppDeletable, U> BitOr<U> for &'a CppBox<T>
where &'a T: BitOr<U>,

Source§

type Output = <&'a 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, U> BitOrAssign<U> for CppBox<T>
where T: BitOrAssign<U> + CppDeletable,

Source§

fn bitor_assign(&mut self, rhs: U)

Performs the |= operation. Read more
Source§

impl<'a, T: CppDeletable, U> BitXor<U> for &'a CppBox<T>
where &'a T: BitXor<U>,

Source§

type Output = <&'a 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<T, U> BitXorAssign<U> for CppBox<T>
where T: BitXorAssign<U> + CppDeletable,

Source§

fn bitxor_assign(&mut self, rhs: U)

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<'a, T, U> CastFrom<&'a CppBox<U>> for Ref<T>
where U: StaticUpcast<T> + CppDeletable,

Source§

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

Performs the conversion. Read more
Source§

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

Source§

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

Performs the conversion. Read more
Source§

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

Source§

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

Performs the conversion. Read more
Source§

impl<T: CppDeletable> Debug for CppBox<T>

Source§

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

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

impl<T: CppDeletable> Deref for CppBox<T>

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

Source§

type Target = T

The resulting type after dereferencing.
Source§

fn deref(&self) -> &T

Dereferences the value.
Source§

impl<T: CppDeletable> DerefMut for CppBox<T>

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

Source§

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.
Source§

impl<'a, T: CppDeletable, U> Div<U> for &'a CppBox<T>
where &'a T: Div<U>,

Source§

type Output = <&'a 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, U> DivAssign<U> for CppBox<T>
where T: DivAssign<U> + CppDeletable,

Source§

fn div_assign(&mut self, rhs: U)

Performs the /= operation. Read more
Source§

impl<T: CppDeletable> Drop for CppBox<T>

Deletes the stored object using C++’s delete operator.

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

impl<'a, T, T1, T2> IntoIterator for &'a CppBox<T>
where T: CppDeletable + '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,

Source§

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

The type of the elements being iterated over.
Source§

type IntoIter = CppIterator<T1, T2>

Which kind of iterator are we turning this into?
Source§

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value. Read more
Source§

impl<'a, T, T1, T2> IntoIterator for &'a mut CppBox<T>
where T: CppDeletable + 'static, &'static mut T: BeginMut<Output = CppBox<T1>> + EndMut<Output = CppBox<T2>>, T1: CppDeletable + PartialEq<Ref<T2>> + 'static, T2: CppDeletable, &'static T1: Indirection, &'static mut T1: Increment,

Source§

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

The type of the elements being iterated over.
Source§

type IntoIter = CppIterator<T1, T2>

Which kind of iterator are we turning this into?
Source§

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value. Read more
Source§

impl<'a, T: CppDeletable, U> Mul<U> for &'a CppBox<T>
where &'a T: Mul<U>,

Source§

type Output = <&'a 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> MulAssign<U> for CppBox<T>
where T: MulAssign<U> + CppDeletable,

Source§

fn mul_assign(&mut self, rhs: U)

Performs the *= operation. Read more
Source§

impl<T, U> PartialEq<U> for CppBox<T>
where T: PartialEq<U> + CppDeletable,

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 CppBox<T>
where T: Lt<U> + Le<U> + Gt<U> + Ge<U> + PartialEq<U> + CppDeletable,

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<'a, T: CppDeletable, U> Rem<U> for &'a CppBox<T>
where &'a T: Rem<U>,

Source§

type Output = <&'a 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, U> RemAssign<U> for CppBox<T>
where T: RemAssign<U> + CppDeletable,

Source§

fn rem_assign(&mut self, rhs: U)

Performs the %= operation. Read more
Source§

impl<'a, T: CppDeletable, U> Shl<U> for &'a CppBox<T>
where &'a T: Shl<U>,

Source§

type Output = <&'a 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, U> ShlAssign<U> for CppBox<T>
where T: ShlAssign<U> + CppDeletable,

Source§

fn shl_assign(&mut self, rhs: U)

Performs the <<= operation. Read more
Source§

impl<'a, T: CppDeletable, U> Shr<U> for &'a CppBox<T>
where &'a T: Shr<U>,

Source§

type Output = <&'a 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, U> ShrAssign<U> for CppBox<T>
where T: ShrAssign<U> + CppDeletable,

Source§

fn shr_assign(&mut self, rhs: U)

Performs the >>= operation. Read more
Source§

impl<'a, T: CppDeletable, U> Sub<U> for &'a CppBox<T>
where &'a T: Sub<U>,

Source§

type Output = <&'a 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, U> SubAssign<U> for CppBox<T>
where T: SubAssign<U> + CppDeletable,

Source§

fn sub_assign(&mut self, rhs: U)

Performs the -= operation. Read more

Auto Trait Implementations§

§

impl<T> Freeze for CppBox<T>

§

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

§

impl<T> !Send for CppBox<T>

§

impl<T> !Sync for CppBox<T>

§

impl<T> Unpin for CppBox<T>

§

impl<T> UnwindSafe for CppBox<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> 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§

unsafe fn static_upcast_mut(ptr: MutPtr<T>) -> MutPtr<T>

Convert type of a mutable pointer. 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.