1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85
//! 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_core` provides three kinds of pointers: //! //! - `CppBox`: owned, non-null (corresponds to C++ objects passed by value) //! - `Ptr`: possibly owned, possibly null (correspond to C++ pointers) //! - `Ref`: 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`, 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<Ptr<SomeClass>>`, //! you can pass a `Ptr<SomeClass>`, `&CppBox<SomeClass>`, //! or even `Ptr<DerivedClass>` (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). #![deny(missing_docs)] pub use crate::casts::{DynamicCast, StaticDowncast, StaticUpcast}; pub use crate::convert::{CastFrom, CastInto}; pub use crate::cpp_box::{CppBox, CppDeletable}; pub use crate::iterator::{cpp_iter, CppIterator, EndPtr}; pub use crate::ptr::{NullPtr, Ptr}; pub use crate::ref_::Ref; pub use libc::wchar_t; mod casts; pub mod cmp; mod convert; mod cpp_box; mod iterator; pub mod ops; mod ops_impls; mod ptr; mod ref_; pub mod vector_ops; // C++ doesn't guarantee these types to be exactly u16 and u32, // but they are on all supported platforms. /// Type for UTF-16 character representation, required to be large enough to represent /// any UTF-16 code unit (16 bits). Same as C++'s `char16_6` type. #[allow(non_camel_case_types)] pub type char16_t = u16; /// Type for UTF-32 character representation, required to be large enough to represent /// any UTF-32 code unit (32 bits). Same as C++'s `char32_t` type. #[allow(non_camel_case_types)] pub type char32_t = u32;