Built-in bindings reference

In addition to all the primitive types (i32 <=> int32_t), the following common types may be used in the fields of shared structs and the arguments and returns of extern functions.

<table> <tr><th>name in Rust</th><th>name in C++</th><th>restrictions</th></tr> <tr><td style="padding:3px 6px">String</td><td style="padding:3px 6px"><a href="binding/string.md">rust::String</a></td><td style="padding:3px 6px"></td></tr> <tr><td style="padding:3px 6px">&str</td><td style="padding:3px 6px"><a href="binding/str.md">rust::Str</a></td><td style="padding:3px 6px"></td></tr> <tr><td style="padding:3px 6px">&[T]</td><td style="padding:3px 6px"><a href="binding/slice.md">rust::Slice<const T></a></td><td style="padding:3px 6px">cannot hold opaque C++ type</td></tr> <tr><td style="padding:3px 6px">&mut [T]</td><td style="padding:3px 6px"><a href="binding/slice.md">rust::Slice<T></a></td><td style="padding:3px 6px">cannot hold opaque C++ type</td></tr> <tr><td style="padding:3px 6px"><a href="binding/cxxstring.md">CxxString</a></td><td style="padding:3px 6px">std::string</td><td style="padding:3px 6px">cannot be passed by value</td></tr> <tr><td style="padding:3px 6px">Box<T></td><td style="padding:3px 6px"><a href="binding/box.md">rust::Box<T></a></td><td style="padding:3px 6px">cannot hold opaque C++ type</td></tr> <tr><td style="padding:3px 6px"><a href="binding/uniqueptr.md">UniquePtr<T></a></td><td style="padding:3px 6px">std::unique_ptr<T></td><td style="padding:3px 6px">cannot hold opaque Rust type</td></tr> <tr><td style="padding:3px 6px"><a href="binding/sharedptr.md">SharedPtr<T></a></td><td style="padding:3px 6px">std::shared_ptr<T></td><td style="padding:3px 6px">cannot hold opaque Rust type</td></tr> <tr><td style="padding:3px 6px">[T; N]</td><td style="padding:3px 6px">std::array<T, N></td><td style="padding:3px 6px">cannot hold opaque C++ type</td></tr> <tr><td style="padding:3px 6px">Vec<T></td><td style="padding:3px 6px"><a href="binding/vec.md">rust::Vec<T></a></td><td style="padding:3px 6px">cannot hold opaque C++ type</td></tr> <tr><td style="padding:3px 6px"><a href="binding/cxxvector.md">CxxVector<T></a></td><td style="padding:3px 6px">std::vector<T></td><td style="padding:3px 6px">cannot be passed by value, cannot hold opaque Rust type</td></tr> <tr><td style="padding:3px 6px"><a href="binding/rawptr.md">*mut T, *const T</a></td><td style="padding:3px 6px">T*, const T*</td><td style="padding:3px 6px">fn with a raw pointer argument must be declared unsafe to call</td></tr> <tr><td style="padding:3px 6px">fn(T, U) -> V</td><td style="padding:3px 6px"><a href="binding/fn.md">rust::Fn<V(T, U)></a></td><td style="padding:3px 6px">only passing from Rust to C++ is implemented so far</td></tr> <tr><td style="padding:3px 6px"><a href="binding/result.md">Result<T></a></td><td style="padding:3px 6px">throw/catch</td><td style="padding:3px 6px">allowed as return type only</td></tr> </table>

The C++ API of the rust namespace is defined by the include/cxx.h file in the CXX GitHub repo. You will need to include this header in your C++ code when working with those types. When using Cargo and the cxx-build crate, the header is made available to you at #include "rust/cxx.h".

The rust namespace additionally provides lowercase type aliases of all the types mentioned in the table, for use in codebases preferring that style. For example rust::String, rust::Vec may alternatively be written rust::string, rust::vec etc.

Pending bindings

The following types are intended to be supported "soon" but are just not implemented yet. I don't expect any of these to be hard to make work but it's a matter of designing a nice API for each in its non-native language.

<table> <tr><th>name in Rust</th><th>name in C++</th></tr> <tr><td>BTreeMap<K, V></td><td>tbd</td></tr> <tr><td>HashMap<K, V></td><td>tbd</td></tr> <tr><td>Arc<T></td><td>tbd</td></tr> <tr><td>Option<T></td><td>tbd</td></tr> <tr><td>tbd</td><td>std::map<K, V></td></tr> <tr><td>tbd</td><td>std::unordered_map<K, V></td></tr> </table>