Utilities for interoperability with C++
See the project's [README](https://github.com/rust-qt/ritual) for more information.
The API is not stable yet. Breaking changes may occur in new minor versions.
# Pointers
`cpp_utils` provides three kinds of pointers:
- `CppBox`: owned, non-null (corresponds to C++ objects passed by value)
- `Ptr` and `MutPtr`: possibly owned, possibly null (correspond to C++ pointers)
- `Ref` and `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 `operator+`.
Pointer types implement `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,
pointer types will implement `IntoIterator`, so you can iterate on them directly.
# Casts
The following traits provide access to casting between C++ class types:
- `StaticUpcast` safely converts from a derived class to a base class
(backed by C++'s `static_cast`).
- `DynamicCast` performs a checked conversion from a base class to a derived class
(backed by C++'s `dynamic_cast`).
- `StaticDowncast` converts from a base class to a derived class without a runtime
check (also backed by C++'s `static_cast`).
Instead of using these traits directly, it's more convenient to use `static_upcast`,
`static_downcast`, `dynamic_cast` helpers on pointer types.
The `CastFrom` and `CastInto` traits represent some of the implicit coercions
available in C++. For example, if a method accepts `impl CastInto>`,
you can pass a `Ptr`, `MutPtr`, `&CppBox`,
or even `Ptr` (where `DerivedClass` inherits `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).