{{#title std::string — Rust ♡ C++}}
# std::string

The Rust binding of std::string is called **[`CxxString`]**. See the link for
documentation of the Rust API.

[`CxxString`]: https://docs.rs/cxx/*/cxx/struct.CxxString.html

### Restrictions:

Rust code can never obtain a CxxString by value. C++'s string requires a move
constructor and may hold internal pointers, which is not compatible with Rust's
move behavior. Instead in Rust code we will only ever look at a CxxString
through a reference or smart pointer, as in &CxxString or Pin\<&mut CxxString\>
or UniquePtr\.

In order to construct a CxxString on the stack from Rust, you must use the
[`let_cxx_string!`] macro which will pin the string properly. The code below
uses this in one place, and the link covers the syntax.

[`let_cxx_string!`]: https://docs.rs/cxx/*/cxx/macro.let_cxx_string.html

## Example

This example uses C++17's std::variant to build a toy JSON type. JSON can hold
various types including strings, and JSON's object type is a map with string
keys. The example demonstrates Rust indexing into one of those maps.

```rust,noplayground
// src/main.rs

use cxx::let_cxx_string;

#[cxx::bridge]
mod ffi {
    unsafe extern "C++" {
        include!("example/include/json.h");

        #[cxx_name = "json"]
        type Json;
        #[cxx_name = "object"]
        type Object;

        fn isNull(self: &Json) -> bool;
        fn isNumber(self: &Json) -> bool;
        fn isString(self: &Json) -> bool;
        fn isArray(self: &Json) -> bool;
        fn isObject(self: &Json) -> bool;

        fn getNumber(self: &Json) -> f64;
        fn getString(self: &Json) -> &CxxString;
        fn getArray(self: &Json) -> &CxxVector;
        fn getObject(self: &Json) -> &Object;

        #[cxx_name = "at"]
        fn get<'a>(self: &'a Object, key: &CxxString) -> &'a Json;

        fn load_config() -> UniquePtr;
    }
}

fn main() {
    let config = ffi::load_config();

    let_cxx_string!(key = "name");
    println!("{}", config.getObject().get(&key).getString());
}
```

```cpp
// include/json.h

#pragma once
#include