Utilities for interoperability with C++
See the project's README for more information.
The API is not stable yet. Breaking changes may occur in new minor versions.
cpp_utils provides three kinds of pointers:
CppBox: owned, non-null (corresponds to C++ objects passed by value)
MutPtr: possibly owned, possibly null (correspond to C++ pointers)
MutRef: not owned, non-null (correspond to C++ references)
Accessing objects through these pointers is inherently unsafe, as the compiler cannot make any guarantee about the validity of pointers to objects managed by C++ libraries.
Unlike Rust references, these pointers can be freely copied, producing multiple mutable pointers to the same object, which is usually necessary to do when working with C++ libraries.
Pointer types implement operator traits and delegate them to the corresponding C++ operators.
This means that you can use
ptr1 + ptr2 to access the object's
Pointer types implement
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
If the object provides an iterator interface through
pointer types will implement
IntoIterator, so you can iterate on them directly.
The following traits provide access to casting between C++ class types:
StaticUpcastsafely converts from a derived class to a base class (backed by C++'s
DynamicCastperforms a checked conversion from a base class to a derived class (backed by C++'s
StaticDowncastconverts from a base class to a derived class without a runtime check (also backed by C++'s
Instead of using these traits directly, it's more convenient to use
dynamic_cast helpers on pointer types.
CastInto traits represent some of the implicit coercions
available in C++. For example, if a method accepts
you can pass a
SomeClass). You can also
pass a null pointer object (
NullPtr) if you don't have a value
Ptr::null() is also an option but it can cause type inference issues).