cpp_core/
lib.rs

1//! Utilities for interoperability with C++
2//!
3//! See the project's [README](https://github.com/rust-qt/ritual) for more information.
4//!
5//! The API is not stable yet. Breaking changes may occur in new minor versions.
6//!
7//! # Pointers
8//!
9//! `cpp_core` provides three kinds of pointers:
10//!
11//! - `CppBox`: owned, non-null (corresponds to C++ objects passed by value)
12//! - `Ptr`: possibly owned, possibly null (correspond to C++ pointers)
13//! - `Ref`: not owned, non-null (correspond to C++ references)
14//!
15//! Accessing objects through these pointers is inherently unsafe,
16//! as the compiler cannot make any guarantee about the validity of pointers to objects
17//! managed by C++ libraries.
18//!
19//! Unlike Rust references, these pointers can be freely copied,
20//! producing multiple mutable pointers to the same object, which is usually necessary
21//! to do when working with C++ libraries.
22//!
23//! Pointer types implement operator traits and delegate them to the corresponding C++ operators.
24//! This means that you can use `ptr1 + ptr2` to access the object's `operator+`.
25//!
26//! Pointer types implement `Deref`, allowing to call the object's methods
27//! directly. In addition, methods of the object's first base class are also directly available
28//! thanks to nested `Deref` implementations.
29//!
30//! If the object provides an iterator interface through `begin()` and `end()` functions,
31//! pointer types will implement `IntoIterator`, so you can iterate on them directly.
32//!
33//! # Casts
34//!
35//! The following traits provide access to casting between C++ class types:
36//!
37//! - `StaticUpcast` safely converts from a derived class to a base class
38//! (backed by C++'s `static_cast`).
39//! - `DynamicCast` performs a checked conversion from a base class to a derived class
40//! (backed by C++'s `dynamic_cast`).
41//! - `StaticDowncast` converts from a base class to a derived class without a runtime
42//! check (also backed by C++'s `static_cast`).
43//!
44//! Instead of using these traits directly, it's more convenient to use `static_upcast`,
45//! `static_downcast`, `dynamic_cast` helpers on pointer types.
46//!
47//! The `CastFrom` and `CastInto` traits represent some of the implicit coercions
48//! available in C++. For example, if a method accepts `impl CastInto<Ptr<SomeClass>>`,
49//! you can pass a `Ptr<SomeClass>`, `&CppBox<SomeClass>`,
50//! or even `Ptr<DerivedClass>` (where `DerivedClass` inherits `SomeClass`). You can also
51//! pass a null pointer object (`NullPtr`) if you don't have a value
52//! (`Ptr::null()` is also an option but it can cause type inference issues).
53
54#![deny(missing_docs)]
55
56pub use crate::casts::{DynamicCast, StaticDowncast, StaticUpcast};
57pub use crate::convert::{CastFrom, CastInto};
58pub use crate::cpp_box::{CppBox, CppDeletable};
59pub use crate::iterator::{cpp_iter, CppIterator, EndPtr};
60pub use crate::ptr::{NullPtr, Ptr};
61pub use crate::ref_::Ref;
62pub use libc::wchar_t;
63
64mod casts;
65pub mod cmp;
66mod convert;
67mod cpp_box;
68mod iterator;
69pub mod ops;
70mod ops_impls;
71mod ptr;
72mod ref_;
73pub mod vector_ops;
74
75// C++ doesn't guarantee these types to be exactly u16 and u32,
76// but they are on all supported platforms.
77
78/// Type for UTF-16 character representation, required to be large enough to represent
79/// any UTF-16 code unit (16 bits). Same as C++'s `char16_6` type.
80#[allow(non_camel_case_types)]
81pub type char16_t = u16;
82/// Type for UTF-32 character representation, required to be large enough to represent
83/// any UTF-32 code unit (32 bits). Same as C++'s `char32_t` type.
84#[allow(non_camel_case_types)]
85pub type char32_t = u32;
cpp_core/lib.rs

cpp_core/
lib.rs
