• 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 
14 class String final {
15 public:
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 
75 std::ostream &operator<<(std::ostream &, const String &);
76 #
77 # } // namespace rust
78 ```
79 
80 ### Restrictions:
81 
82 None. Strings may be used as function arguments and function return values, by
83 value 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]
91 mod 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 
103 fn 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 
119 rust::String concat(ConcatRequest r);
120 ```
121 
122 ```cpp
123 // src/concat.cc
124 
125 #include "example/include/concat.h"
126 
127 rust::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