Debian Codegraph @

src/3rdparty/gsl/pointers

raw
1 ///////////////////////////////////////////////////////////////////////////////
2 //
3 // Copyright (c) 2015 Microsoft Corporation. All rights reserved.
4 //
5 // This code is licensed under the MIT License (MIT).
6 //
7 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
8 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
9 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
10 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
11 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
12 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
13 // THE SOFTWARE.
14 //
15 ///////////////////////////////////////////////////////////////////////////////
16
17 #ifndef GSL_POINTERS_H
18 #define GSL_POINTERS_H
19
20 #include "./assert" // for Ensures, Expects
21 #include "./util" // for GSL_DEPRECATED
22
23 #include <cstddef> // for ptrdiff_t, nullptr_t, size_t
24 #include <functional> // for less, greater
25 #include <memory> // for shared_ptr, unique_ptr, hash
26 #include <type_traits> // for enable_if_t, is_convertible, is_assignable
27 #include <utility> // for declval, forward
28
29 #if !defined(GSL_NO_IOSTREAMS)
30 #include <iosfwd> // for ostream
31 #endif // !defined(GSL_NO_IOSTREAMS)
32
33 namespace gsl
34 {
35
36 namespace details
37 {
38 template <typename T, typename = void>
39 struct is_comparable_to_nullptr : std::false_type
40 {
41 };
42
43 template <typename T>
44 struct is_comparable_to_nullptr<
45 T,
46 std::enable_if_t<std::is_convertible<decltype(std::declval<T>() != nullptr), bool>::value>>
47 : std::true_type
48 {
49 };
50
51 // Resolves to the more efficient of `const T` or `const T&`, in the context of returning a const-qualified value
52 // of type T.
53 //
54 // Copied from cppfront's implementation of the CppCoreGuidelines F.16 (https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-in)
55 template<typename T>
56 using value_or_reference_return_t = std::conditional_t<
57 sizeof(T) < 2*sizeof(void*) && std::is_trivially_copy_constructible<T>::value,
58 const T,
59 const T&>;
60
61 } // namespace details
62
63 //
64 // GSL.owner: ownership pointers
65 //
66 template <typename... Ts>
67 using shared_ptr GSL_DEPRECATED("Use std::shared_ptr instead") = std::shared_ptr<Ts...>;
68
69 template <typename... Ts>
70 using unique_ptr GSL_DEPRECATED("Use std::unique_ptr instead") = std::unique_ptr<Ts...>;
71
72 //
73 // owner
74 //
75 // `gsl::owner<T>` is designed as a safety mechanism for code that must deal directly with raw pointers that own memory.
76 // Ideally such code should be restricted to the implementation of low-level abstractions. `gsl::owner` can also be used
77 // as a stepping point in converting legacy code to use more modern RAII constructs, such as smart pointers.
78 //
79 // T must be a pointer type
80 // - disallow construction from any type other than pointer type
81 //
82 template <class T, std::enable_if_t<std::is_pointer<T>::value, bool> = true>
83 using owner = T;
84
85 //
86 // not_null
87 //
88 // Restricts a pointer or smart pointer to only hold non-null values.
89 //
90 // Has zero size overhead over T.
91 //
92 // If T is a pointer (i.e. T == U*) then
93 // - allow construction from U*
94 // - disallow construction from nullptr_t
95 // - disallow default construction
96 // - ensure construction from null U* fails
97 // - allow implicit conversion to U*
98 //
99 template <class T>
100 class not_null
101 {
102 public:
103 static_assert(details::is_comparable_to_nullptr<T>::value, "T cannot be compared to nullptr.");
104
105 using element_type = T;
106
107 template <typename U, typename = std::enable_if_t<std::is_convertible<U, T>::value>>
108 constexpr not_null(U&& u) noexcept(std::is_nothrow_move_constructible<T>::value) : ptr_(std::forward<U>(u))
109 {
110 Expects(ptr_ != nullptr);
111 }
112
113 template <typename = std::enable_if_t<!std::is_same<std::nullptr_t, T>::value>>
114 constexpr not_null(T u) noexcept(std::is_nothrow_move_constructible<T>::value) : ptr_(std::move(u))
115 {
116 Expects(ptr_ != nullptr);
117 }
118
119 template <typename U, typename = std::enable_if_t<std::is_convertible<U, T>::value>>
120 constexpr not_null(const not_null<U>& other) noexcept(std::is_nothrow_move_constructible<T>::value) : not_null(other.get())
121 {}
122
123 not_null(const not_null& other) = default;
124 not_null& operator=(const not_null& other) = default;
125 constexpr details::value_or_reference_return_t<T> get() const
126 noexcept(noexcept(details::value_or_reference_return_t<T>(std::declval<T&>())))
127 {
128 return ptr_;
129 }
130
131 constexpr operator T() const { return get(); }
132 constexpr decltype(auto) operator->() const { return get(); }
133 constexpr decltype(auto) operator*() const { return *get(); }
134
135 // prevents compilation when someone attempts to assign a null pointer constant
136 not_null(std::nullptr_t) = delete;
137 not_null& operator=(std::nullptr_t) = delete;
138
139 // unwanted operators...pointers only point to single objects!
140 not_null& operator++() = delete;
141 not_null& operator--() = delete;
142 not_null operator++(int) = delete;
143 not_null operator--(int) = delete;
144 not_null& operator+=(std::ptrdiff_t) = delete;
145 not_null& operator-=(std::ptrdiff_t) = delete;
146 void operator[](std::ptrdiff_t) const = delete;
147
148 void swap(not_null<T>& other) { std::swap(ptr_, other.ptr_); }
149
150 private:
151 T ptr_;
152 };
153
154 template <typename T, std::enable_if_t<std::is_move_assignable<T>::value && std::is_move_constructible<T>::value, bool> = true>
155 void swap(not_null<T>& a, not_null<T>& b)
156 {
157 a.swap(b);
158 }
159
160 template <class T>
161 auto make_not_null(T&& t) noexcept
162 {
163 return not_null<std::remove_cv_t<std::remove_reference_t<T>>>{std::forward<T>(t)};
164 }
165
166 #if !defined(GSL_NO_IOSTREAMS)
167 template <class T>
168 std::ostream& operator<<(std::ostream& os, const not_null<T>& val)
169 {
170 os << val.get();
171 return os;
172 }
173 #endif // !defined(GSL_NO_IOSTREAMS)
174
175 template <class T, class U>
176 auto operator==(const not_null<T>& lhs,
177 const not_null<U>& rhs) noexcept(noexcept(lhs.get() == rhs.get()))
178 -> decltype(lhs.get() == rhs.get())
179 {
180 return lhs.get() == rhs.get();
181 }
182
183 template <class T, class U>
184 auto operator!=(const not_null<T>& lhs,
185 const not_null<U>& rhs) noexcept(noexcept(lhs.get() != rhs.get()))
186 -> decltype(lhs.get() != rhs.get())
187 {
188 return lhs.get() != rhs.get();
189 }
190
191 template <class T, class U>
192 auto operator<(const not_null<T>& lhs,
193 const not_null<U>& rhs) noexcept(noexcept(std::less<>{}(lhs.get(), rhs.get())))
194 -> decltype(std::less<>{}(lhs.get(), rhs.get()))
195 {
196 return std::less<>{}(lhs.get(), rhs.get());
197 }
198
199 template <class T, class U>
200 auto operator<=(const not_null<T>& lhs,
201 const not_null<U>& rhs) noexcept(noexcept(std::less_equal<>{}(lhs.get(), rhs.get())))
202 -> decltype(std::less_equal<>{}(lhs.get(), rhs.get()))
203 {
204 return std::less_equal<>{}(lhs.get(), rhs.get());
205 }
206
207 template <class T, class U>
208 auto operator>(const not_null<T>& lhs,
209 const not_null<U>& rhs) noexcept(noexcept(std::greater<>{}(lhs.get(), rhs.get())))
210 -> decltype(std::greater<>{}(lhs.get(), rhs.get()))
211 {
212 return std::greater<>{}(lhs.get(), rhs.get());
213 }
214
215 template <class T, class U>
216 auto operator>=(const not_null<T>& lhs,
217 const not_null<U>& rhs) noexcept(noexcept(std::greater_equal<>{}(lhs.get(), rhs.get())))
218 -> decltype(std::greater_equal<>{}(lhs.get(), rhs.get()))
219 {
220 return std::greater_equal<>{}(lhs.get(), rhs.get());
221 }
222
223 // more unwanted operators
224 template <class T, class U>
225 std::ptrdiff_t operator-(const not_null<T>&, const not_null<U>&) = delete;
226 template <class T>
227 not_null<T> operator-(const not_null<T>&, std::ptrdiff_t) = delete;
228 template <class T>
229 not_null<T> operator+(const not_null<T>&, std::ptrdiff_t) = delete;
230 template <class T>
231 not_null<T> operator+(std::ptrdiff_t, const not_null<T>&) = delete;
232
233
234 template <class T, class U = decltype(std::declval<const T&>().get()), bool = std::is_default_constructible<std::hash<U>>::value>
235 struct not_null_hash
236 {
237 std::size_t operator()(const T& value) const { return std::hash<U>{}(value.get()); }
238 };
239
240 template <class T, class U>
241 struct not_null_hash<T, U, false>
242 {
243 not_null_hash() = delete;
244 not_null_hash(const not_null_hash&) = delete;
245 not_null_hash& operator=(const not_null_hash&) = delete;
246 };
247
248 } // namespace gsl
249
250 namespace std
251 {
252 template <class T>
253 struct hash<gsl::not_null<T>> : gsl::not_null_hash<gsl::not_null<T>>
254 {
255 };
256
257 } // namespace std
258
259 namespace gsl
260 {
261
262 //
263 // strict_not_null
264 //
265 // Restricts a pointer or smart pointer to only hold non-null values,
266 //
267 // - provides a strict (i.e. explicit constructor from T) wrapper of not_null
268 // - to be used for new code that wishes the design to be cleaner and make not_null
269 // checks intentional, or in old code that would like to make the transition.
270 //
271 // To make the transition from not_null, incrementally replace not_null
272 // by strict_not_null and fix compilation errors
273 //
274 // Expect to
275 // - remove all unneeded conversions from raw pointer to not_null and back
276 // - make API clear by specifying not_null in parameters where needed
277 // - remove unnecessary asserts
278 //
279 template <class T>
280 class strict_not_null : public not_null<T>
281 {
282 public:
283 template <typename U, typename = std::enable_if_t<std::is_convertible<U, T>::value>>
284 constexpr explicit strict_not_null(U&& u) noexcept(std::is_nothrow_move_constructible<T>::value) : not_null<T>(std::forward<U>(u))
285 {}
286
287 template <typename = std::enable_if_t<!std::is_same<std::nullptr_t, T>::value>>
288 constexpr explicit strict_not_null(T u) noexcept(std::is_nothrow_move_constructible<T>::value) : not_null<T>(std::move(u))
289 {}
290
291 template <typename U, typename = std::enable_if_t<std::is_convertible<U, T>::value>>
292 constexpr strict_not_null(const not_null<U>& other) noexcept(std::is_nothrow_move_constructible<T>::value) : not_null<T>(other)
293 {}
294
295 template <typename U, typename = std::enable_if_t<std::is_convertible<U, T>::value>>
296 constexpr strict_not_null(const strict_not_null<U>& other) noexcept(std::is_nothrow_move_constructible<T>::value) : not_null<T>(other)
297 {}
298
299 // To avoid invalidating the "not null" invariant, the contained pointer is actually copied
300 // instead of moved. If it is a custom pointer, its constructor could in theory throw exceptions.
301 strict_not_null(strict_not_null&& other) noexcept(std::is_nothrow_copy_constructible<T>::value) = default;
302 strict_not_null(const strict_not_null& other) = default;
303 strict_not_null& operator=(const strict_not_null& other) = default;
304 strict_not_null& operator=(const not_null<T>& other)
305 {
306 not_null<T>::operator=(other);
307 return *this;
308 }
309
310 // prevents compilation when someone attempts to assign a null pointer constant
311 strict_not_null(std::nullptr_t) = delete;
312 strict_not_null& operator=(std::nullptr_t) = delete;
313
314 // unwanted operators...pointers only point to single objects!
315 strict_not_null& operator++() = delete;
316 strict_not_null& operator--() = delete;
317 strict_not_null operator++(int) = delete;
318 strict_not_null operator--(int) = delete;
319 strict_not_null& operator+=(std::ptrdiff_t) = delete;
320 strict_not_null& operator-=(std::ptrdiff_t) = delete;
321 void operator[](std::ptrdiff_t) const = delete;
322 };
323
324 // more unwanted operators
325 template <class T, class U>
326 std::ptrdiff_t operator-(const strict_not_null<T>&, const strict_not_null<U>&) = delete;
327 template <class T>
328 strict_not_null<T> operator-(const strict_not_null<T>&, std::ptrdiff_t) = delete;
329 template <class T>
330 strict_not_null<T> operator+(const strict_not_null<T>&, std::ptrdiff_t) = delete;
331 template <class T>
332 strict_not_null<T> operator+(std::ptrdiff_t, const strict_not_null<T>&) = delete;
333
334 template <class T>
335 auto make_strict_not_null(T&& t) noexcept
336 {
337 return strict_not_null<std::remove_cv_t<std::remove_reference_t<T>>>{std::forward<T>(t)};
338 }
339
340 #if (defined(__cpp_deduction_guides) && (__cpp_deduction_guides >= 201611L))
341
342 // deduction guides to prevent the ctad-maybe-unsupported warning
343 template <class T>
344 not_null(T) -> not_null<T>;
345 template <class T>
346 strict_not_null(T) -> strict_not_null<T>;
347
348 #endif // ( defined(__cpp_deduction_guides) && (__cpp_deduction_guides >= 201611L) )
349
350 } // namespace gsl
351
352 namespace std
353 {
354 template <class T>
355 struct hash<gsl::strict_not_null<T>> : gsl::not_null_hash<gsl::strict_not_null<T>>
356 {
357 };
358
359 } // namespace std
360
361 #endif // GSL_POINTERS_H