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>
impl<T: CppDeletable> CppBox<T>
Sourcepub unsafe fn new(ptr: MutPtr<T>) -> Option<Self>
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.
Sourcepub unsafe fn from_raw(ptr: *mut T) -> Option<Self>
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>
impl<T: CppDeletable> CppBox<T>
Sourcepub unsafe fn as_ptr(&self) -> Ptr<T>
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.
Sourcepub unsafe fn as_mut_ptr(&mut self) -> MutPtr<T>
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.
Sourcepub fn as_mut_raw_ptr(&mut self) -> *mut T
pub fn as_mut_raw_ptr(&mut self) -> *mut T
Returns a constant raw pointer to the value in the box.
Sourcepub fn as_raw_ptr(&self) -> *const T
pub fn as_raw_ptr(&self) -> *const T
Returns a mutable raw pointer to the value in the box.
Sourcepub fn into_raw_ptr(self) -> *mut T
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.
Sourcepub unsafe fn into_ptr(self) -> MutPtr<T>
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.
Sourcepub unsafe fn as_ref(&self) -> Ref<T>
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.
Sourcepub unsafe fn as_mut_ref(&mut self) -> MutRef<T>
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.
Sourcepub unsafe fn static_upcast<U>(&self) -> Ref<U>where
T: StaticUpcast<U>,
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.
Sourcepub unsafe fn static_downcast<U>(&self) -> Ref<U>where
T: StaticDowncast<U>,
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
.
Sourcepub unsafe fn dynamic_cast<U>(&self) -> Option<Ref<U>>where
T: DynamicCast<U>,
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.
Sourcepub unsafe fn static_upcast_mut<U>(&mut self) -> MutRef<U>where
T: StaticUpcast<U>,
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.
Sourcepub unsafe fn static_downcast_mut<U>(&mut self) -> MutRef<U>where
T: StaticDowncast<U>,
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
.
Sourcepub unsafe fn dynamic_cast_mut<U>(&mut self) -> Option<MutRef<U>>where
T: DynamicCast<U>,
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.
Sourcepub unsafe fn begin(&self) -> <&'static T as Begin>::Outputwhere
&'static T: Begin,
pub unsafe fn begin(&self) -> <&'static T as Begin>::Outputwhere
&'static T: Begin,
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.
Sourcepub unsafe fn begin_mut(&mut self) -> <&'static mut T as BeginMut>::Outputwhere
&'static mut T: BeginMut,
pub unsafe fn begin_mut(&mut self) -> <&'static mut T as BeginMut>::Outputwhere
&'static mut T: BeginMut,
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.
Sourcepub unsafe fn end(&self) -> <&'static T as End>::Outputwhere
&'static T: End,
pub unsafe fn end(&self) -> <&'static T as End>::Outputwhere
&'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.
Sourcepub unsafe fn end_mut(&mut self) -> <&'static mut T as EndMut>::Outputwhere
&'static mut T: EndMut,
pub unsafe fn end_mut(&mut self) -> <&'static mut T as EndMut>::Outputwhere
&'static mut T: EndMut,
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.
Sourcepub unsafe fn as_slice<'a, T1>(&'a self) -> &'a [T1]
pub unsafe fn as_slice<'a, T1>(&'a self) -> &'a [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.
Sourcepub unsafe fn as_mut_slice<'a, T1>(&'a mut self) -> &'a mut [T1]
pub unsafe fn as_mut_slice<'a, T1>(&'a mut self) -> &'a mut [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>
impl<'a, T: CppDeletable, U> Add<U> for &'a CppBox<T>
Source§impl<T, U> AddAssign<U> for CppBox<T>where
T: AddAssign<U> + CppDeletable,
impl<T, U> AddAssign<U> for CppBox<T>where
T: AddAssign<U> + CppDeletable,
Source§fn add_assign(&mut self, rhs: U)
fn add_assign(&mut self, rhs: U)
+=
operation. Read moreSource§impl<'a, T: CppDeletable, U> BitAnd<U> for &'a CppBox<T>
impl<'a, T: CppDeletable, U> BitAnd<U> for &'a CppBox<T>
Source§impl<T, U> BitAndAssign<U> for CppBox<T>where
T: BitAndAssign<U> + CppDeletable,
impl<T, U> BitAndAssign<U> for CppBox<T>where
T: BitAndAssign<U> + CppDeletable,
Source§fn bitand_assign(&mut self, rhs: U)
fn bitand_assign(&mut self, rhs: U)
&=
operation. Read moreSource§impl<'a, T: CppDeletable, U> BitOr<U> for &'a CppBox<T>
impl<'a, T: CppDeletable, U> BitOr<U> for &'a CppBox<T>
Source§impl<T, U> BitOrAssign<U> for CppBox<T>where
T: BitOrAssign<U> + CppDeletable,
impl<T, U> BitOrAssign<U> for CppBox<T>where
T: BitOrAssign<U> + CppDeletable,
Source§fn bitor_assign(&mut self, rhs: U)
fn bitor_assign(&mut self, rhs: U)
|=
operation. Read moreSource§impl<'a, T: CppDeletable, U> BitXor<U> for &'a CppBox<T>
impl<'a, T: CppDeletable, U> BitXor<U> for &'a CppBox<T>
Source§impl<T, U> BitXorAssign<U> for CppBox<T>where
T: BitXorAssign<U> + CppDeletable,
impl<T, U> BitXorAssign<U> for CppBox<T>where
T: BitXorAssign<U> + CppDeletable,
Source§fn bitxor_assign(&mut self, rhs: U)
fn bitxor_assign(&mut self, rhs: U)
^=
operation. Read moreSource§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<'a, T, U> CastFrom<&'a CppBox<U>> for Ref<T>where
U: StaticUpcast<T> + CppDeletable,
impl<'a, T, U> CastFrom<&'a CppBox<U>> for Ref<T>where
U: StaticUpcast<T> + CppDeletable,
Source§impl<'a, T, U> CastFrom<&'a mut CppBox<U>> for MutPtr<T>where
U: StaticUpcast<T> + CppDeletable,
impl<'a, T, U> CastFrom<&'a mut CppBox<U>> for MutPtr<T>where
U: StaticUpcast<T> + CppDeletable,
Source§impl<'a, T, U> CastFrom<&'a mut CppBox<U>> for MutRef<T>where
U: StaticUpcast<T> + CppDeletable,
impl<'a, T, U> CastFrom<&'a mut CppBox<U>> for MutRef<T>where
U: StaticUpcast<T> + CppDeletable,
Source§impl<T: CppDeletable> Debug for CppBox<T>
impl<T: CppDeletable> Debug for CppBox<T>
Source§impl<T: CppDeletable> Deref for CppBox<T>
Allows to call member functions of T
and its base classes directly on the pointer.
impl<T: CppDeletable> Deref for CppBox<T>
Allows to call member functions of T
and its base classes directly on the pointer.
Source§impl<T: CppDeletable> DerefMut for CppBox<T>
Allows to call member functions of T
and its base classes directly on the pointer.
impl<T: CppDeletable> DerefMut for CppBox<T>
Allows to call member functions of T
and its base classes directly on the pointer.
Source§impl<'a, T: CppDeletable, U> Div<U> for &'a CppBox<T>
impl<'a, T: CppDeletable, U> Div<U> for &'a CppBox<T>
Source§impl<T, U> DivAssign<U> for CppBox<T>where
T: DivAssign<U> + CppDeletable,
impl<T, U> DivAssign<U> for CppBox<T>where
T: DivAssign<U> + CppDeletable,
Source§fn div_assign(&mut self, rhs: U)
fn div_assign(&mut self, rhs: U)
/=
operation. Read moreSource§impl<T: CppDeletable> Drop for CppBox<T>
Deletes the stored object using C++’s delete
operator.
impl<T: CppDeletable> Drop for CppBox<T>
Deletes the stored object using C++’s delete
operator.
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,
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
type Item = <&'static T1 as Indirection>::Output
Source§type IntoIter = CppIterator<T1, T2>
type IntoIter = CppIterator<T1, T2>
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,
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
type Item = <&'static T1 as Indirection>::Output
Source§type IntoIter = CppIterator<T1, T2>
type IntoIter = CppIterator<T1, T2>
Source§impl<'a, T: CppDeletable, U> Mul<U> for &'a CppBox<T>
impl<'a, T: CppDeletable, U> Mul<U> for &'a CppBox<T>
Source§impl<T, U> MulAssign<U> for CppBox<T>where
T: MulAssign<U> + CppDeletable,
impl<T, U> MulAssign<U> for CppBox<T>where
T: MulAssign<U> + CppDeletable,
Source§fn mul_assign(&mut self, rhs: U)
fn mul_assign(&mut self, rhs: U)
*=
operation. Read moreSource§impl<T, U> PartialOrd<U> for CppBox<T>
impl<T, U> PartialOrd<U> for CppBox<T>
Source§impl<'a, T: CppDeletable, U> Rem<U> for &'a CppBox<T>
impl<'a, T: CppDeletable, U> Rem<U> for &'a CppBox<T>
Source§impl<T, U> RemAssign<U> for CppBox<T>where
T: RemAssign<U> + CppDeletable,
impl<T, U> RemAssign<U> for CppBox<T>where
T: RemAssign<U> + CppDeletable,
Source§fn rem_assign(&mut self, rhs: U)
fn rem_assign(&mut self, rhs: U)
%=
operation. Read moreSource§impl<'a, T: CppDeletable, U> Shl<U> for &'a CppBox<T>
impl<'a, T: CppDeletable, U> Shl<U> for &'a CppBox<T>
Source§impl<T, U> ShlAssign<U> for CppBox<T>where
T: ShlAssign<U> + CppDeletable,
impl<T, U> ShlAssign<U> for CppBox<T>where
T: ShlAssign<U> + CppDeletable,
Source§fn shl_assign(&mut self, rhs: U)
fn shl_assign(&mut self, rhs: U)
<<=
operation. Read moreSource§impl<'a, T: CppDeletable, U> Shr<U> for &'a CppBox<T>
impl<'a, T: CppDeletable, U> Shr<U> for &'a CppBox<T>
Source§impl<T, U> ShrAssign<U> for CppBox<T>where
T: ShrAssign<U> + CppDeletable,
impl<T, U> ShrAssign<U> for CppBox<T>where
T: ShrAssign<U> + CppDeletable,
Source§fn shr_assign(&mut self, rhs: U)
fn shr_assign(&mut self, rhs: U)
>>=
operation. Read moreSource§impl<'a, T: CppDeletable, U> Sub<U> for &'a CppBox<T>
impl<'a, T: CppDeletable, U> Sub<U> for &'a CppBox<T>
Source§impl<T, U> SubAssign<U> for CppBox<T>where
T: SubAssign<U> + CppDeletable,
impl<T, U> SubAssign<U> for CppBox<T>where
T: SubAssign<U> + CppDeletable,
Source§fn sub_assign(&mut self, rhs: U)
fn sub_assign(&mut self, rhs: U)
-=
operation. Read more