blob: 7a2075e661b9e579d4a49c6b707ac7ee29a0596f [file] [view]
# Rust bindings for C++ standard library (`std`) types
When generating Rust bindings for a C++ target, bindings to the C++ standard
library types are provided by the `cpp_std` support library (which re-exports
the legacy `cc_std::std::*`). This contains a combination of manually written
types and automatically generated bindings.
You can then use standard library types directly via `cpp_std::{sometype}`,
e.g., `cpp_std::unique_ptr<T>`.
TODO(b/454337872): The following is stub documentation in the absence of rustdoc
support. Instead of linking to API docs, we link to Rust source files.
## `std::string` {#string}
When passed or returned directly by value, `std::string` is bridged to
`cpp_std::string_wrapper` unless the
`//features:layout_compat_string` feature flag is enabled
(b/408961701). References (`const std::string&`, `std::string&`), struct fields,
and layout-compatible generic containers (such as `std::optional<std::string>`
and `absl::StatusOr<std::string>`) use the layout-compatible, `!Unpin`
`cpp_std::string` type.
Both `cpp_std::string` and `cpp_std::string_wrapper` convert to
`cpp_std::string_view` via `From<&string>` and `From<&string_wrapper>`. In the
reverse direction, `string_wrapper` implements `From<string_view>`, and `string`
implements `ctor::CtorNew<string_view>` (and can be cloned in place via
`ctor::emplace!(ctor::copy(s))`).
API: support/cc_std_impl/string.rs
## `std::string_view` and `absl::string_view` {#string_view}
C++'s `std::string_view` type has two analogues in Rust. If no lifetime can be
specified or inferred, or the data may be mutably aliased, then one should use
`cpp_std::raw_string_view`. This is analogous to a `*const [u8]` in Rust.
Otherwise, `cpp_std::string_view<'a>`.
API: support/cc_std_impl/string_view.rs
## `std::unique_ptr<T>` {#unique_ptr}
C++'s `std::unique_ptr<T>` type has two non-null analogues in Rust. If the type
has a virtual destructor, or an overloaded `operator delete`, then it becomes a
`cpp_std::virtual_unique_ptr<T>`. In particular, polymorphic types will be
stored in a `cpp_std::virtual_unique_ptr<T>`.
Otherwise, when the destructor is directly callable and not virtual, it becomes
a `cpp_std::unique_ptr<T>`.
When a `std::unique_ptr<T>` is known to be non-null (for example, annotated with
`absl_nonnull` or `_Nonnull`, or under `ABSL_POINTERS_DEFAULT_NONNULL`), Crubit
maps it directly to `cpp_std::unique_ptr<T>` or
`cpp_std::virtual_unique_ptr<T>`. When it may be null (unannotated or
`absl_nullable`), Crubit wraps it in `cpp_std::Nullable<Ptr>`. Convert either to
`Option<Ptr>` using `cpp_std::OptionLike` (`into_option`, `as_option`,
`as_option_mut`), which is implemented on both `Nullable<Ptr>` and bare `Ptr` so
callers keep compiling when nullability annotations are added.
Both `unique_ptr<T>` and `virtual_unique_ptr<T>` implement `Deref<Target = T>`
and `DerefMut<Target = T>` (when `T: Unpin`). To heap-construct a
non-Rust-movable (`!Unpin`) `T` in place from a `ctor::Ctor`, use
`cpp_std::unique_ptr::emplace` (or `try_emplace`). While C++ `std::unique_ptr`
is only shallow-const (i.e. `const std::unique_ptr<T>&` allows mutating the
underlying `T`), it is conventionally treated as deep-const. In order for
`&unique_ptr<T>` to be usable at all from Rust, we treat it as deep-const. C++
code which mutates a value of type `T` while Rust has obtained a `&T` via
`&unique_ptr<T>` -\> `&T` deref will result in undefined behavior.
API: support/cc_std_impl/unique_ptr.rs,
support/cc_std_impl/nullable.rs
See also: crubit.rs/errors/delete
## `std::shared_ptr<T>` {#shared_ptr}
A non-null C++ `std::shared_ptr<T>` (`absl_nonnull` or `_Nonnull`) becomes a
Rust `cpp_std::shared_ptr<T>`, while an unannotated or `absl_nullable`
`std::shared_ptr<T>` becomes `cpp_std::Nullable<cpp_std::shared_ptr<T>>`
(convertible to `Option` via `cpp_std::OptionLike`). `cpp_std::shared_ptr<T>`
implements `Deref<Target = T>`, allowing `&shared_ptr<T>` to be dereferenced to
`&T`, and provides `shared_ptr::emplace` (and `try_emplace`) to construct
`!Unpin` pointees in place from a `ctor::Ctor`.
API: support/cc_std_impl/shared_ptr.rs
## `std::vector<T>` {#vector}
A C++ `std::vector<T>` becomes a Rust `cpp_std::vector<T>`.
API: support/cc_std_impl/vector.rs
## `std::optional<T>` {#optional}
`std::optional<T>` in C++ is bound as `cpp_std::optional<T>` or
`cpp_std::trivial_optional<T>` in Rust. `trivial_optional` is used when
`T: Copy`, which allows `optional` of trivially copyable types to also be
trivially copyable (see the `trivial_optional` docs in the API below). Convert
to and from a Rust `Option<T>` with `.into_option()` or `From`/`Into`, e.g.
`opt.into_option()`, `Option::from(opt)`, or `Some(x).into()`. When `T` is
`!Unpin`, construct `cpp_std::optional<T>` in place via
`ctor::CtorNew<Option<A>>` (`optional::<T>::ctor_new(opt)`) or
`optional::ctor_from_option`.
API: support/cc_std_impl/optional.rs
## Unsupported `std` templates
Concrete instantiations of unsupported `std` templates still receive opaque
bindings you can pass around (by `Ctor!` or `Pin`) but not inspect. For example,
a C++ function returning `std::map<int, Reading>` is not rejected; Crubit binds
the concrete instantiation as an opaque, non-Rust-movable type:
```rust
pub fn LatestReadings() -> ::ctor::Ctor![crate::__CcTemplateInstNSt3__u3mapIi…];
```
Member types like `value_compare` are reported as
`// error: … could not be bound`. Supported `std` types (`string_view`,
`unique_ptr`, `vector`, `optional`, etc.) get ergonomic `cpp_std` mappings. Use
`--config=crubit-genfiles` to see which you got.