1 // Copyright (C) 2020-2023 Free Software Foundation, Inc.
2
3 // This file is part of GCC.
4
5 // GCC is free software; you can redistribute it and/or modify it under
6 // the terms of the GNU General Public License as published by the Free
7 // Software Foundation; either version 3, or (at your option) any later
8 // version.
9
10 // GCC is distributed in the hope that it will be useful, but WITHOUT ANY
11 // WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 // FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 // for more details.
14
15 // You should have received a copy of the GNU General Public License
16 // along with GCC; see the file COPYING3. If not see
17 // <http://www.gnu.org/licenses/>.
18
19 #ifndef RUST_OPTIONAL_H
20 #define RUST_OPTIONAL_H
21
22 #include "config.h"
23 #include "rust-system.h"
24
25 #include "selftest.h"
26
27 namespace Rust {
28
29 /**
30 * Tagged union to try and simulate a sum type. This is safer and more ergonomic
31 * than one of the two alternatives we're currently using in the compiler:
32 *
33 * 1. Storing a raw pointer, which can be `nullptr` or valid
34 *
35 * This is wildly unsafe, and usable in conjunction with local references, stack
36 * variables, or pointers managed elsewhere, which can cause crashes, hard to
37 * debug issues or undefined behavior. Likewise, if you do not check for the
38 * pointer's validity, this will cause a crash.
39 *
40 * 2. Storing an extra boolean alongside the object
41 *
42 * This causes implementors to use a "dummy object": Either an empty version or
43 * an error version. But what happens if what you really wanted to store was
44 * the empty or error version? You can also easily incorporate logic bugs if you
45 * forget to check for the associated boolean.
46 *
47 * The `Optional<T>` type has the same "ergonomic" cost: You need to check
48 * whether your option is valid or not. However, the main advantage is that it
49 * is more restrictive: You can only acess the member it contains "safely".
50 * It is similar to storing a value + an associated boolean, but has the
51 * advantage of making up only one member in your class.
52 * You also benefit from some helper methods such as `map()`.
53 *
54 * You also get helper functions and operator overloading to "seamlessly"
55 * replace raw pointer alternatives.
56 *
57 * ```c++
58 * MyType *raw_pointer = something_that_can_fail();
59 * if (raw_pointer)
60 * raw_pointer->method();
61 *
62 * // or
63 *
64 * Optional<MyType> opt = something_that_can_fail2();
65 * if (opt)
66 * opt->method();
67 *
68 * // equivalent to
69 *
70 * if (opt.is_some())
71 * opt.get().method();
72 * ```
73 */
74 template <typename T> class Optional
75 {
76 private:
77 struct Empty
78 {
79 };
80
81 enum Kind
82 {
83 Some,
84 None
85 } kind;
86
87 union Content
88 {
89 Empty empty;
90 T value;
91
92 Content () = default;
93 } content;
94
95 Optional<T> (Kind kind, Content content) : kind (kind), content (content) {}
96
97 public:
98 Optional (const Optional &other) = default;
99 Optional &operator= (const Optional &other) = default;
100 Optional (Optional &&other) = default;
101
102 static Optional<T> some (T value)
103 {
104 Content content;
105 content.value = value;
106
107 return Optional (Kind::Some, content);
108 }
109
110 static Optional<T> none ()
111 {
112 Content content;
113 content.empty = Empty ();
114
115 return Optional (Kind::None, content);
116 }
117
118 bool is_some () const { return kind == Kind::Some; }
119 bool is_none () const { return !is_some (); }
120
121 /**
122 * Enable boolean-like comparisons.
123 */
124 operator bool () { return is_some (); }
125
126 /**
127 * Enables dereferencing to access the contained value
128 */
129 T &operator* () { return get (); }
130 const T &operator* () const { return get (); }
131 T *operator-> () { return &get (); }
132 const T *operator-> () const { return &get (); }
133
134 const T &get () const
135 {
136 rust_assert (is_some ());
137
138 return content.value;
139 }
140
141 T &get ()
142 {
143 rust_assert (is_some ());
144
145 return content.value;
146 }
147
148 T take ()
149 {
150 rust_assert (is_some ());
151
152 auto to_return = std::move (content.value);
153
154 content.empty = Empty ();
155 kind = Kind::None;
156
157 return to_return;
158 }
159
160 template <typename U> Optional<U> map (std::function<U (T)> functor)
161 {
162 if (is_none ())
163 return Optional::none ();
164
165 auto value = functor (take ());
166
167 return Optional::some (value);
168 }
169 };
170
171 template <typename T> class Optional<T &>
172 {
173 private:
174 struct Empty
175 {
176 };
177
178 enum Kind
179 {
180 Some,
181 None
182 } kind;
183
184 union Content
185 {
186 Empty empty;
187 T *value;
188
189 Content () = default;
190 } content;
191
192 Optional<T &> (Kind kind, Content content) : kind (kind), content (content) {}
193
194 public:
195 Optional (const Optional &other) = default;
196 Optional (Optional &&other) = default;
197 Optional &operator= (Optional &&other) = default;
198
199 static Optional<T &> some (T &value)
200 {
201 Content content;
202 content.value = &value;
203
204 return Optional (Kind::Some, content);
205 }
206
207 static Optional<T &> none ()
208 {
209 Content content;
210 content.empty = Empty ();
211
212 return Optional (Kind::None, content);
213 }
214
215 bool is_some () const { return kind == Kind::Some; }
216 bool is_none () const { return !is_some (); }
217
218 // FIXME: Can we factor this in a single class?
219
220 /**
221 * Enable boolean-like comparisons.
222 */
223 operator bool () { return is_some (); }
224
225 /**
226 * Enables dereferencing to access the contained value
227 */
228 T &operator* () { return get (); }
229 const T &operator* () const { return get (); }
230 T *operator-> () { return &get (); }
231 const T *operator-> () const { return &get (); }
232
233 const T &get () const
234 {
235 rust_assert (is_some ());
236
237 return *content.value;
238 }
239
240 T &get ()
241 {
242 rust_assert (is_some ());
243
244 return *content.value;
245 }
246
247 T &take ()
248 {
249 rust_assert (is_some ());
250
251 auto to_return = std::move (content.value);
252
253 content.empty = Empty ();
254 kind = Kind::None;
255
256 return *to_return;
257 }
258
259 template <typename U> Optional<U &> map (std::function<U &(T &)> functor)
260 {
261 if (is_none ())
262 return Optional::none ();
263
264 auto value = functor (take ());
265
266 return Optional::some (value);
267 }
268 };
269
270 } // namespace Rust
271
272 #ifdef CHECKING_P
273
274 void
275 rust_optional_test ();
276
277 #endif // !CHECKING_P
278
279 #endif // !RUST_OPTIONAL_H