1{{#title rust::Vec<T> — Rust ♡ C++}}
2# rust::Vec\<T\>
3
4### Public API:
5
6```cpp,hidelines=...
7// rust/cxx.h
8...
9...#include <initializer_list>
10...#include <iterator>
11...#include <type_traits>
12...
13...namespace rust {
14
15template <typename T>
16class Vec final {
17public:
18  using value_type = T;
19
20  Vec() noexcept;
21  Vec(std::initializer_list<T>);
22  Vec(const Vec &);
23  Vec(Vec &&) noexcept;
24  ~Vec() noexcept;
25
26  Vec &operator=(Vec &&) noexcept;
27  Vec &operator=(const Vec &);
28
29  size_t size() const noexcept;
30  bool empty() const noexcept;
31  const T *data() const noexcept;
32  T *data() noexcept;
33  size_t capacity() const noexcept;
34
35  const T &operator[](size_t n) const noexcept;
36  const T &at(size_t n) const;
37  const T &front() const;
38  const T &back() const;
39
40  T &operator[](size_t n) noexcept;
41  T &at(size_t n);
42  T &front();
43  T &back();
44
45  void reserve(size_t new_cap);
46  void push_back(const T &value);
47  void push_back(T &&value);
48  template <typename... Args>
49  void emplace_back(Args &&...args);
50  void truncate(size_t len);
51  void clear();
52
53  class iterator;
54  iterator begin() noexcept;
55  iterator end() noexcept;
56
57  class const_iterator;
58  const_iterator begin() const noexcept;
59  const_iterator end() const noexcept;
60  const_iterator cbegin() const noexcept;
61  const_iterator cend() const noexcept;
62
63  void swap(Vec &) noexcept;
64};
65...
66...template <typename T>
67...class Vec<T>::iterator final {
68...public:
69...  using iterator_category = std::random_access_iterator_tag;
70...  using value_type = T;
71...  using pointer = T *;
72...  using reference = T &;
73...
74...  T &operator*() const noexcept;
75...  T *operator->() const noexcept;
76...  T &operator[](ptrdiff_t) const noexcept;
77...
78...  iterator &operator++() noexcept;
79...  iterator operator++(int) noexcept;
80...  iterator &operator--() noexcept;
81...  iterator operator--(int) noexcept;
82...
83...  iterator &operator+=(ptrdiff_t) noexcept;
84...  iterator &operator-=(ptrdiff_t) noexcept;
85...  iterator operator+(ptrdiff_t) const noexcept;
86...  iterator operator-(ptrdiff_t) const noexcept;
87...  ptrdiff_t operator-(const iterator &) const noexcept;
88...
89...  bool operator==(const iterator &) const noexcept;
90...  bool operator!=(const iterator &) const noexcept;
91...  bool operator<(const iterator &) const noexcept;
92...  bool operator<=(const iterator &) const noexcept;
93...  bool operator>(const iterator &) const noexcept;
94...  bool operator>=(const iterator &) const noexcept;
95...};
96...
97...template <typename T>
98...class Vec<T>::const_iterator final {
99...public:
100...  using iterator_category = std::random_access_iterator_tag;
101...  using value_type = const T;
102...  using pointer = const T *;
103...  using reference = const T &;
104...
105...  const T &operator*() const noexcept;
106...  const T *operator->() const noexcept;
107...  const T &operator[](ptrdiff_t) const noexcept;
108...
109...  const_iterator &operator++() noexcept;
110...  const_iterator operator++(int) noexcept;
111...  const_iterator &operator--() noexcept;
112...  const_iterator operator--(int) noexcept;
113...
114...  const_iterator &operator+=(ptrdiff_t) noexcept;
115...  const_iterator &operator-=(ptrdiff_t) noexcept;
116...  const_iterator operator+(ptrdiff_t) const noexcept;
117...  const_iterator operator-(ptrdiff_t) const noexcept;
118...  ptrdiff_t operator-(const const_iterator &) const noexcept;
119...
120...  bool operator==(const const_iterator &) const noexcept;
121...  bool operator!=(const const_iterator &) const noexcept;
122...  bool operator<(const const_iterator &) const noexcept;
123...  bool operator<=(const const_iterator &) const noexcept;
124...  bool operator>(const const_iterator &) const noexcept;
125...  bool operator>=(const const_iterator &) const noexcept;
126...};
127...
128...} // namespace rust
129```
130
131### Restrictions:
132
133Vec\<T\> does not support T being an opaque C++ type. You should use
134CxxVector\<T\> (C++ std::vector\<T\>) instead for collections of opaque C++
135types on the language boundary.
136
137## Example
138
139```rust,noplayground
140// src/main.rs
141
142#[cxx::bridge]
143mod ffi {
144    struct Shared {
145        v: u32,
146    }
147
148    unsafe extern "C++" {
149        include!("example/include/example.h");
150
151        fn f(elements: Vec<Shared>);
152    }
153}
154
155fn main() {
156    let shared = |v| ffi::Shared { v };
157    let elements = vec![shared(3), shared(2), shared(1)];
158    ffi::f(elements);
159}
160```
161
162```cpp
163// include/example.h
164
165#pragma once
166#include "example/src/main.rs.h"
167#include "rust/cxx.h"
168
169void f(rust::Vec<Shared> elements);
170```
171
172```cpp
173// src/example.cc
174
175#include "example/include/example.h"
176#include <algorithm>
177#include <cassert>
178#include <iostream>
179#include <iterator>
180#include <vector>
181
182void f(rust::Vec<Shared> v) {
183  for (auto shared : v) {
184    std::cout << shared.v << std::endl;
185  }
186
187  // Copy the elements to a C++ std::vector using STL algorithm.
188  std::vector<Shared> stdv;
189  std::copy(v.begin(), v.end(), std::back_inserter(stdv));
190  assert(v.size() == stdv.size());
191}
192```
193