• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1{{#title rust::String — Rust ♡ C++}}
2# rust::String
3
4### Public API:
5
6```cpp,hidelines
7// rust/cxx.h
8#
9# #include <iosfwd>
10# #include <string>
11#
12# namespace rust {
13
14class String final {
15public:
16  String() noexcept;
17  String(const String &) noexcept;
18  String(String &&) noexcept;
19  ~String() noexcept;
20
21  // Throws std::invalid_argument if not UTF-8.
22  String(const std::string &);
23  String(const char *);
24  String(const char *, size_t);
25
26  // Replaces invalid UTF-8 data with the replacement character (U+FFFD).
27  static String lossy(const std::string &) noexcept;
28  static String lossy(const char *) noexcept;
29  static String lossy(const char *, size_t) noexcept;
30
31  // Throws std::invalid_argument if not UTF-16.
32  String(const char16_t *);
33  String(const char16_t *, size_t);
34
35  // Replaces invalid UTF-16 data with the replacement character (U+FFFD).
36  static String lossy(const char16_t *) noexcept;
37  static String lossy(const char16_t *, size_t) noexcept;
38
39  String &operator=(const String &) noexcept;
40  String &operator=(String &&) noexcept;
41
42  explicit operator std::string() const;
43
44  // Note: no null terminator.
45  const char *data() const noexcept;
46  size_t size() const noexcept;
47  size_t length() const noexcept;
48  bool empty() const noexcept;
49
50  const char *c_str() noexcept;
51
52  size_t capacity() const noexcept;
53  void reserve(size_t new_cap) noexcept;
54
55  using iterator = char *;
56  iterator begin() noexcept;
57  iterator end() noexcept;
58
59  using const_iterator = const char *;
60  const_iterator begin() const noexcept;
61  const_iterator end() const noexcept;
62  const_iterator cbegin() const noexcept;
63  const_iterator cend() const noexcept;
64
65  bool operator==(const String &) const noexcept;
66  bool operator!=(const String &) const noexcept;
67  bool operator<(const String &) const noexcept;
68  bool operator<=(const String &) const noexcept;
69  bool operator>(const String &) const noexcept;
70  bool operator>=(const String &) const noexcept;
71
72  void swap(String &) noexcept;
73};
74
75std::ostream &operator<<(std::ostream &, const String &);
76#
77# } // namespace rust
78```
79
80### Restrictions:
81
82None. Strings may be used as function arguments and function return values, by
83value or by reference, as well as fields of shared structs.
84
85## Example
86
87```rust,noplayground
88// src/main.rs
89
90#[cxx::bridge]
91mod ffi {
92    struct ConcatRequest {
93        fst: String,
94        snd: String,
95    }
96
97    unsafe extern "C++" {
98        include!("example/include/concat.h");
99        fn concat(r: ConcatRequest) -> String;
100    }
101}
102
103fn main() {
104    let concatenated = ffi::concat(ffi::ConcatRequest {
105        fst: "fearless".to_owned(),
106        snd: "concurrency".to_owned(),
107    });
108    println!("concatenated: {:?}", concatenated);
109}
110```
111
112```cpp
113// include/concat.h
114
115#pragma once
116#include "example/src/main.rs.h"
117#include "rust/cxx.h"
118
119rust::String concat(ConcatRequest r);
120```
121
122```cpp
123// src/concat.cc
124
125#include "example/include/concat.h"
126
127rust::String concat(ConcatRequest r) {
128  // The full suite of operator overloads hasn't been added
129  // yet on rust::String, but we can get it done like this:
130  return std::string(r.fst) + std::string(r.snd);
131}
132```
133