| # Rust bindings for C++ operators and special member functions | |
| Here we describe how Crubit bindings work with C++ special member functions and | |
| operator overloading (e.g. the copy constructor, or `operator==`) and with | |
| traits from the Rust standard library (e.g., the `Clone` or `PartialEq` traits). | |
| Rust traits which return `Self` by value (e.g., `Default` or `Clone`) or use | |
| mutable references (e.g., `AddAssign`) are only implemented in Rust bindings for | |
| a given C++ type if that type [is `Unpin`](../design/unpin.md). | |
| ## Bidirectional map | |
| The following special member functions and traits are mapped bidirectionally: | |
| | C++ | Rust | | |
| | :--------------------------- | :-------- | | |
| | Default constructor | `Default` | | |
| | Trivial copy constructor | `Copy` | | |
| | Non-trivial copy constructor | `Clone` | | |
| | Destructor | `Drop` | | |
| > [!NOTE] | |
| > Rust bindings for a C++ type only implement `Copy` if the C++ type | |
| > is non-abstract and has a public, trivial copy constructor and destructor. | |
| ## One-way map of C++ special member functions into Rust traits | |
| If the C++ type [is `Unpin`](../design/unpin.md), then the C++ special member | |
| functions below are mapped one-way into the corresponding Rust traits as | |
| follows: | |
| | C++ API | Rust bindings | | |
| | :---------------------------------------- | :------------ | | |
| | Constructor taking a single `T` parameter | `From<T>` | | |
| > [!NOTE] | |
| > This applies regardless of whether the constructor is `explicit` in | |
| > the C++ API. | |
| The C++ binary operators below are mapped one-way into the corresponding Rust | |
| traits as follows: | |
| | C++ API | Rust bindings | | |
| | :------------ | :--------------------------------------------------------------------------------------------------- | | |
| | `operator==` | `PartialEq` | | |
| | `operator<=>` | `PartialOrd` (and `Eq` + `Ord` for `std::strong_ordering` and, if enabled, for `std::weak_ordering`) | | |
| | `operator<` | `PartialOrd` | | |
| | `operator>` | `PartialOrd` | | |
| | `operator<=` | `PartialOrd` | | |
| | `operator>=` | `PartialOrd` | | |
| | `operator+` | `Add` | | |
| | `operator-` | `Sub` | | |
| | `operator*` | `Mul` | | |
| | `operator/` | `Div` | | |
| | `operator%` | `Rem` | | |
| | `operator&` | `BitAnd` | | |
| | `operator\|` | `BitOr` | | |
| | `operator^` | `BitXor` | | |
| | `operator<<` | `Shl` | | |
| | `operator>>` | `Shr` | | |
| | `operator+=` | `AddAssign` | | |
| | `operator-=` | `SubAssign` | | |
| | `operator*=` | `MulAssign` | | |
| | `operator/=` | `DivAssign` | | |
| | `operator%=` | `RemAssign` | | |
| | `operator&=` | `BitAndAssign` | | |
| | `operator\|=` | `BitOrAssign` | | |
| | `operator^=` | `BitXorAssign` | | |
| | `operator<<=` | `ShlAssign` | | |
| | `operator>>=` | `ShrAssign` | | |
| The C++ unary operators below are mapped one-way into the corresponding Rust | |
| traits as follows: | |
| | C++ API | Rust bindings | | |
| | :---------- | :------------ | | |
| | `operator-` | `Neg` | | |
| | `operator!` | `Not` | | |
| ### `PartialOrd` | |
| Rust only permits a single `PartialOrd` impl for a given pair of operand types, | |
| so Crubit picks one of the comparison operators (`<=>`, `<`, `>`, `<=`, `>=`) to | |
| back the impl, in that order of preference. The remaining comparison operators | |
| are not bound directly; they are served by the default `PartialOrd` methods, | |
| which are derived from `partial_cmp`. | |
| `operator<=>` (the "spaceship" operator) implements `partial_cmp` directly. It | |
| must return `std::strong_ordering`, `std::weak_ordering`, or | |
| `std::partial_ordering` (`std::partial_ordering::unordered` maps to `None`). For | |
| the other operators, Crubit synthesizes `partial_cmp` from the operator together | |
| with `operator==`. | |
| A `PartialOrd` impl is only generated if `operator==` is also available for the | |
| same operand types. `operator<=>` supports operands of different record types | |
| (`impl PartialOrd<Rhs> for Lhs`), whereas `<`, `>`, `<=`, and `>=` require the | |
| left- and right-hand operands to have the same type. | |
| ### `Eq` and `Ord` | |
| If `operator<=>` returns `std::strong_ordering` or `std::weak_ordering` (and | |
| Crubit implements `PartialOrd<Self>` with it), then Crubit also implements `Eq` | |
| and `Ord`. This lets you use the type in a `BTreeMap` or `BTreeSet`, and sort it | |
| with `sort()`. | |
| * For `std::strong_ordering`, this is enabled by default. | |
| * For `std::weak_ordering`, this requires the `weak_ordering_traits` Crubit | |
| feature . | |
| Crubit doesn't implement `Eq` and `Ord` for `std::partial_ordering`, because it | |
| allows unordered values. | |
| ### Operators inherited from base classes | |
| C++ operators are sometimes defined as "hidden friends" of a base class, for | |
| example by a CRTP mixin which implements comparison operators for the derived | |
| class: | |
| ```c++ | |
| template <typename T> | |
| struct EqualityMixin { | |
| friend bool operator==(const T& lhs, const T& rhs) { ... } | |
| }; | |
| struct S final : EqualityMixin<S> { ... }; | |
| ``` | |
| Argument-dependent lookup finds such operators for `S`, even though `S` doesn't | |
| declare them itself. To map them into Rust traits as well (e.g. `PartialEq` for | |
| `S`), enable the `inherited_friend_operators` Crubit | |
| feature | |
| on the target that defines `S`. Only operators whose first parameter is (a | |
| reference to) `S` are mapped. | |
| This is opt-in, because the generated trait implementations conflict with any | |
| existing manual implementations of the same traits. | |
| ## One-way map into `Display` | |
| By default: for a C++ type `T`, Crubit maps one-way the following C++ signatures | |
| into the Rust trait `Display`: | |
| * `template <typename Sink> void AbslStringify(Sink&, const T&)` | |
| * `template <typename Sink> void AbslStringify(Sink&, T)` | |
| * `std::ostream& operator<<(std::ostream&, const T&)` | |
| * `std::ostream& operator<<(std::ostream&, T)` | |
| Crubit prefers | |
| [`AbslStringify`](https://abseil.io/docs/cpp/guides/abslstringify) but falls | |
| back to `operator<<`. | |
| The [attribute macro](customizing.md) `CRUBIT_OVERRIDE_DISPLAY` forces whether | |
| to implement the `Display` binding. See the macro's documentation: | |
| ```live-snippet | |
| cs/file:support/annotations.h symbol:CRUBIT_OVERRIDE_DISPLAY | |
| ``` |