]>
Commit | Line | Data |
---|---|---|
dc9dc135 XL |
1 | //! Basic functions for dealing with memory. |
2 | //! | |
3 | //! This module contains functions for querying the size and alignment of | |
4 | //! types, initializing and manipulating memory. | |
5 | ||
6 | #![stable(feature = "rust1", since = "1.0.0")] | |
5869c6ff | 7 | #![cfg_attr(bootstrap, allow(unused_unsafe))] |
dc9dc135 XL |
8 | |
9 | use crate::clone; | |
10 | use crate::cmp; | |
11 | use crate::fmt; | |
12 | use crate::hash; | |
13 | use crate::intrinsics; | |
f9f354fc | 14 | use crate::marker::{Copy, DiscriminantKind, Sized}; |
dc9dc135 XL |
15 | use crate::ptr; |
16 | ||
17 | mod manually_drop; | |
18 | #[stable(feature = "manually_drop", since = "1.20.0")] | |
19 | pub use manually_drop::ManuallyDrop; | |
20 | ||
21 | mod maybe_uninit; | |
22 | #[stable(feature = "maybe_uninit", since = "1.36.0")] | |
23 | pub use maybe_uninit::MaybeUninit; | |
24 | ||
25 | #[stable(feature = "rust1", since = "1.0.0")] | |
26 | #[doc(inline)] | |
27 | pub use crate::intrinsics::transmute; | |
28 | ||
29 | /// Takes ownership and "forgets" about the value **without running its destructor**. | |
30 | /// | |
31 | /// Any resources the value manages, such as heap memory or a file handle, will linger | |
32 | /// forever in an unreachable state. However, it does not guarantee that pointers | |
33 | /// to this memory will remain valid. | |
34 | /// | |
1b1a35ee XL |
35 | /// * If you want to leak memory, see [`Box::leak`]. |
36 | /// * If you want to obtain a raw pointer to the memory, see [`Box::into_raw`]. | |
dc9dc135 | 37 | /// * If you want to dispose of a value properly, running its destructor, see |
1b1a35ee | 38 | /// [`mem::drop`]. |
dc9dc135 XL |
39 | /// |
40 | /// # Safety | |
41 | /// | |
42 | /// `forget` is not marked as `unsafe`, because Rust's safety guarantees | |
43 | /// do not include a guarantee that destructors will always run. For example, | |
44 | /// a program can create a reference cycle using [`Rc`][rc], or call | |
45 | /// [`process::exit`][exit] to exit without running destructors. Thus, allowing | |
46 | /// `mem::forget` from safe code does not fundamentally change Rust's safety | |
47 | /// guarantees. | |
48 | /// | |
60c5eb7d XL |
49 | /// That said, leaking resources such as memory or I/O objects is usually undesirable. |
50 | /// The need comes up in some specialized use cases for FFI or unsafe code, but even | |
51 | /// then, [`ManuallyDrop`] is typically preferred. | |
dc9dc135 XL |
52 | /// |
53 | /// Because forgetting a value is allowed, any `unsafe` code you write must | |
54 | /// allow for this possibility. You cannot return a value and expect that the | |
55 | /// caller will necessarily run the value's destructor. | |
56 | /// | |
57 | /// [rc]: ../../std/rc/struct.Rc.html | |
58 | /// [exit]: ../../std/process/fn.exit.html | |
59 | /// | |
60 | /// # Examples | |
61 | /// | |
ba9703b0 XL |
62 | /// The canonical safe use of `mem::forget` is to circumvent a value's destructor |
63 | /// implemented by the `Drop` trait. For example, this will leak a `File`, i.e. reclaim | |
64 | /// the space taken by the variable but never close the underlying system resource: | |
dc9dc135 XL |
65 | /// |
66 | /// ```no_run | |
67 | /// use std::mem; | |
68 | /// use std::fs::File; | |
69 | /// | |
70 | /// let file = File::open("foo.txt").unwrap(); | |
71 | /// mem::forget(file); | |
72 | /// ``` | |
73 | /// | |
ba9703b0 XL |
74 | /// This is useful when the ownership of the underlying resource was previously |
75 | /// transferred to code outside of Rust, for example by transmitting the raw | |
76 | /// file descriptor to C code. | |
77 | /// | |
78 | /// # Relationship with `ManuallyDrop` | |
79 | /// | |
80 | /// While `mem::forget` can also be used to transfer *memory* ownership, doing so is error-prone. | |
81 | /// [`ManuallyDrop`] should be used instead. Consider, for example, this code: | |
82 | /// | |
83 | /// ``` | |
84 | /// use std::mem; | |
85 | /// | |
86 | /// let mut v = vec![65, 122]; | |
87 | /// // Build a `String` using the contents of `v` | |
88 | /// let s = unsafe { String::from_raw_parts(v.as_mut_ptr(), v.len(), v.capacity()) }; | |
89 | /// // leak `v` because its memory is now managed by `s` | |
90 | /// mem::forget(v); // ERROR - v is invalid and must not be passed to a function | |
91 | /// assert_eq!(s, "Az"); | |
92 | /// // `s` is implicitly dropped and its memory deallocated. | |
93 | /// ``` | |
94 | /// | |
95 | /// There are two issues with the above example: | |
96 | /// | |
97 | /// * If more code were added between the construction of `String` and the invocation of | |
98 | /// `mem::forget()`, a panic within it would cause a double free because the same memory | |
99 | /// is handled by both `v` and `s`. | |
100 | /// * After calling `v.as_mut_ptr()` and transmitting the ownership of the data to `s`, | |
101 | /// the `v` value is invalid. Even when a value is just moved to `mem::forget` (which won't | |
102 | /// inspect it), some types have strict requirements on their values that | |
103 | /// make them invalid when dangling or no longer owned. Using invalid values in any | |
104 | /// way, including passing them to or returning them from functions, constitutes | |
105 | /// undefined behavior and may break the assumptions made by the compiler. | |
106 | /// | |
107 | /// Switching to `ManuallyDrop` avoids both issues: | |
60c5eb7d XL |
108 | /// |
109 | /// ``` | |
110 | /// use std::mem::ManuallyDrop; | |
111 | /// | |
112 | /// let v = vec![65, 122]; | |
113 | /// // Before we disassemble `v` into its raw parts, make sure it | |
114 | /// // does not get dropped! | |
115 | /// let mut v = ManuallyDrop::new(v); | |
116 | /// // Now disassemble `v`. These operations cannot panic, so there cannot be a leak. | |
ba9703b0 | 117 | /// let (ptr, len, cap) = (v.as_mut_ptr(), v.len(), v.capacity()); |
60c5eb7d | 118 | /// // Finally, build a `String`. |
ba9703b0 | 119 | /// let s = unsafe { String::from_raw_parts(ptr, len, cap) }; |
60c5eb7d XL |
120 | /// assert_eq!(s, "Az"); |
121 | /// // `s` is implicitly dropped and its memory deallocated. | |
122 | /// ``` | |
123 | /// | |
ba9703b0 XL |
124 | /// `ManuallyDrop` robustly prevents double-free because we disable `v`'s destructor |
125 | /// before doing anything else. `mem::forget()` doesn't allow this because it consumes its | |
126 | /// argument, forcing us to call it only after extracting anything we need from `v`. Even | |
127 | /// if a panic were introduced between construction of `ManuallyDrop` and building the | |
128 | /// string (which cannot happen in the code as shown), it would result in a leak and not a | |
129 | /// double free. In other words, `ManuallyDrop` errs on the side of leaking instead of | |
130 | /// erring on the side of (double-)dropping. | |
60c5eb7d | 131 | /// |
ba9703b0 | 132 | /// Also, `ManuallyDrop` prevents us from having to "touch" `v` after transferring the |
f035d41b | 133 | /// ownership to `s` — the final step of interacting with `v` to dispose of it without |
ba9703b0 | 134 | /// running its destructor is entirely avoided. |
dc9dc135 | 135 | /// |
1b1a35ee XL |
136 | /// [`Box`]: ../../std/boxed/struct.Box.html |
137 | /// [`Box::leak`]: ../../std/boxed/struct.Box.html#method.leak | |
138 | /// [`Box::into_raw`]: ../../std/boxed/struct.Box.html#method.into_raw | |
139 | /// [`mem::drop`]: drop | |
dc9dc135 XL |
140 | /// [ub]: ../../reference/behavior-considered-undefined.html |
141 | #[inline] | |
f035d41b | 142 | #[rustc_const_stable(feature = "const_forget", since = "1.46.0")] |
dc9dc135 | 143 | #[stable(feature = "rust1", since = "1.0.0")] |
74b04a01 | 144 | pub const fn forget<T>(t: T) { |
1b1a35ee | 145 | let _ = ManuallyDrop::new(t); |
dc9dc135 XL |
146 | } |
147 | ||
148 | /// Like [`forget`], but also accepts unsized values. | |
149 | /// | |
150 | /// This function is just a shim intended to be removed when the `unsized_locals` feature gets | |
151 | /// stabilized. | |
dc9dc135 | 152 | #[inline] |
dfeec247 | 153 | #[unstable(feature = "forget_unsized", issue = "none")] |
dc9dc135 | 154 | pub fn forget_unsized<T: ?Sized>(t: T) { |
5869c6ff | 155 | #[cfg(bootstrap)] |
60c5eb7d XL |
156 | // SAFETY: the forget intrinsic could be safe, but there's no point in making it safe since |
157 | // we'll be implementing this function soon via `ManuallyDrop` | |
5869c6ff XL |
158 | unsafe { |
159 | intrinsics::forget(t) | |
160 | } | |
161 | #[cfg(not(bootstrap))] | |
162 | intrinsics::forget(t) | |
dc9dc135 XL |
163 | } |
164 | ||
165 | /// Returns the size of a type in bytes. | |
166 | /// | |
167 | /// More specifically, this is the offset in bytes between successive elements | |
168 | /// in an array with that item type including alignment padding. Thus, for any | |
169 | /// type `T` and length `n`, `[T; n]` has a size of `n * size_of::<T>()`. | |
170 | /// | |
171 | /// In general, the size of a type is not stable across compilations, but | |
172 | /// specific types such as primitives are. | |
173 | /// | |
174 | /// The following table gives the size for primitives. | |
175 | /// | |
176 | /// Type | size_of::\<Type>() | |
177 | /// ---- | --------------- | |
178 | /// () | 0 | |
179 | /// bool | 1 | |
180 | /// u8 | 1 | |
181 | /// u16 | 2 | |
182 | /// u32 | 4 | |
183 | /// u64 | 8 | |
184 | /// u128 | 16 | |
185 | /// i8 | 1 | |
186 | /// i16 | 2 | |
187 | /// i32 | 4 | |
188 | /// i64 | 8 | |
189 | /// i128 | 16 | |
190 | /// f32 | 4 | |
191 | /// f64 | 8 | |
192 | /// char | 4 | |
193 | /// | |
194 | /// Furthermore, `usize` and `isize` have the same size. | |
195 | /// | |
196 | /// The types `*const T`, `&T`, `Box<T>`, `Option<&T>`, and `Option<Box<T>>` all have | |
197 | /// the same size. If `T` is Sized, all of those types have the same size as `usize`. | |
198 | /// | |
199 | /// The mutability of a pointer does not change its size. As such, `&T` and `&mut T` | |
200 | /// have the same size. Likewise for `*const T` and `*mut T`. | |
201 | /// | |
202 | /// # Size of `#[repr(C)]` items | |
203 | /// | |
204 | /// The `C` representation for items has a defined layout. With this layout, | |
205 | /// the size of items is also stable as long as all fields have a stable size. | |
206 | /// | |
207 | /// ## Size of Structs | |
208 | /// | |
209 | /// For `structs`, the size is determined by the following algorithm. | |
210 | /// | |
211 | /// For each field in the struct ordered by declaration order: | |
212 | /// | |
213 | /// 1. Add the size of the field. | |
214 | /// 2. Round up the current size to the nearest multiple of the next field's [alignment]. | |
215 | /// | |
216 | /// Finally, round the size of the struct to the nearest multiple of its [alignment]. | |
217 | /// The alignment of the struct is usually the largest alignment of all its | |
218 | /// fields; this can be changed with the use of `repr(align(N))`. | |
219 | /// | |
220 | /// Unlike `C`, zero sized structs are not rounded up to one byte in size. | |
221 | /// | |
222 | /// ## Size of Enums | |
223 | /// | |
224 | /// Enums that carry no data other than the discriminant have the same size as C enums | |
225 | /// on the platform they are compiled for. | |
226 | /// | |
227 | /// ## Size of Unions | |
228 | /// | |
229 | /// The size of a union is the size of its largest field. | |
230 | /// | |
231 | /// Unlike `C`, zero sized unions are not rounded up to one byte in size. | |
232 | /// | |
233 | /// # Examples | |
234 | /// | |
235 | /// ``` | |
236 | /// use std::mem; | |
237 | /// | |
238 | /// // Some primitives | |
239 | /// assert_eq!(4, mem::size_of::<i32>()); | |
240 | /// assert_eq!(8, mem::size_of::<f64>()); | |
241 | /// assert_eq!(0, mem::size_of::<()>()); | |
242 | /// | |
243 | /// // Some arrays | |
244 | /// assert_eq!(8, mem::size_of::<[i32; 2]>()); | |
245 | /// assert_eq!(12, mem::size_of::<[i32; 3]>()); | |
246 | /// assert_eq!(0, mem::size_of::<[i32; 0]>()); | |
247 | /// | |
248 | /// | |
249 | /// // Pointer size equality | |
250 | /// assert_eq!(mem::size_of::<&i32>(), mem::size_of::<*const i32>()); | |
251 | /// assert_eq!(mem::size_of::<&i32>(), mem::size_of::<Box<i32>>()); | |
252 | /// assert_eq!(mem::size_of::<&i32>(), mem::size_of::<Option<&i32>>()); | |
253 | /// assert_eq!(mem::size_of::<Box<i32>>(), mem::size_of::<Option<Box<i32>>>()); | |
254 | /// ``` | |
255 | /// | |
256 | /// Using `#[repr(C)]`. | |
257 | /// | |
258 | /// ``` | |
259 | /// use std::mem; | |
260 | /// | |
261 | /// #[repr(C)] | |
262 | /// struct FieldStruct { | |
263 | /// first: u8, | |
264 | /// second: u16, | |
265 | /// third: u8 | |
266 | /// } | |
267 | /// | |
268 | /// // The size of the first field is 1, so add 1 to the size. Size is 1. | |
269 | /// // The alignment of the second field is 2, so add 1 to the size for padding. Size is 2. | |
270 | /// // The size of the second field is 2, so add 2 to the size. Size is 4. | |
271 | /// // The alignment of the third field is 1, so add 0 to the size for padding. Size is 4. | |
272 | /// // The size of the third field is 1, so add 1 to the size. Size is 5. | |
273 | /// // Finally, the alignment of the struct is 2 (because the largest alignment amongst its | |
274 | /// // fields is 2), so add 1 to the size for padding. Size is 6. | |
275 | /// assert_eq!(6, mem::size_of::<FieldStruct>()); | |
276 | /// | |
277 | /// #[repr(C)] | |
278 | /// struct TupleStruct(u8, u16, u8); | |
279 | /// | |
280 | /// // Tuple structs follow the same rules. | |
281 | /// assert_eq!(6, mem::size_of::<TupleStruct>()); | |
282 | /// | |
283 | /// // Note that reordering the fields can lower the size. We can remove both padding bytes | |
284 | /// // by putting `third` before `second`. | |
285 | /// #[repr(C)] | |
286 | /// struct FieldStructOptimized { | |
287 | /// first: u8, | |
288 | /// third: u8, | |
289 | /// second: u16 | |
290 | /// } | |
291 | /// | |
292 | /// assert_eq!(4, mem::size_of::<FieldStructOptimized>()); | |
293 | /// | |
294 | /// // Union size is the size of the largest field. | |
295 | /// #[repr(C)] | |
296 | /// union ExampleUnion { | |
297 | /// smaller: u8, | |
298 | /// larger: u16 | |
299 | /// } | |
300 | /// | |
301 | /// assert_eq!(2, mem::size_of::<ExampleUnion>()); | |
302 | /// ``` | |
303 | /// | |
1b1a35ee | 304 | /// [alignment]: align_of |
e74abb32 | 305 | #[inline(always)] |
dc9dc135 XL |
306 | #[stable(feature = "rust1", since = "1.0.0")] |
307 | #[rustc_promotable] | |
dfeec247 | 308 | #[rustc_const_stable(feature = "const_size_of", since = "1.32.0")] |
dc9dc135 XL |
309 | pub const fn size_of<T>() -> usize { |
310 | intrinsics::size_of::<T>() | |
311 | } | |
312 | ||
313 | /// Returns the size of the pointed-to value in bytes. | |
314 | /// | |
315 | /// This is usually the same as `size_of::<T>()`. However, when `T` *has* no | |
316 | /// statically-known size, e.g., a slice [`[T]`][slice] or a [trait object], | |
317 | /// then `size_of_val` can be used to get the dynamically-known size. | |
318 | /// | |
319 | /// [slice]: ../../std/primitive.slice.html | |
320 | /// [trait object]: ../../book/ch17-02-trait-objects.html | |
321 | /// | |
322 | /// # Examples | |
323 | /// | |
324 | /// ``` | |
325 | /// use std::mem; | |
326 | /// | |
327 | /// assert_eq!(4, mem::size_of_val(&5i32)); | |
328 | /// | |
329 | /// let x: [u8; 13] = [0; 13]; | |
330 | /// let y: &[u8] = &x; | |
331 | /// assert_eq!(13, mem::size_of_val(y)); | |
332 | /// ``` | |
333 | #[inline] | |
334 | #[stable(feature = "rust1", since = "1.0.0")] | |
3dfed10e XL |
335 | #[rustc_const_unstable(feature = "const_size_of_val", issue = "46571")] |
336 | pub const fn size_of_val<T: ?Sized>(val: &T) -> usize { | |
5869c6ff XL |
337 | // SAFETY: `val` is a reference, so it's a valid raw pointer |
338 | unsafe { intrinsics::size_of_val(val) } | |
dc9dc135 XL |
339 | } |
340 | ||
ba9703b0 XL |
341 | /// Returns the size of the pointed-to value in bytes. |
342 | /// | |
343 | /// This is usually the same as `size_of::<T>()`. However, when `T` *has* no | |
344 | /// statically-known size, e.g., a slice [`[T]`][slice] or a [trait object], | |
345 | /// then `size_of_val_raw` can be used to get the dynamically-known size. | |
346 | /// | |
347 | /// # Safety | |
348 | /// | |
349 | /// This function is only safe to call if the following conditions hold: | |
350 | /// | |
351 | /// - If `T` is `Sized`, this function is always safe to call. | |
352 | /// - If the unsized tail of `T` is: | |
3dfed10e | 353 | /// - a [slice], then the length of the slice tail must be an initialized |
ba9703b0 XL |
354 | /// integer, and the size of the *entire value* |
355 | /// (dynamic tail length + statically sized prefix) must fit in `isize`. | |
356 | /// - a [trait object], then the vtable part of the pointer must point | |
3dfed10e | 357 | /// to a valid vtable acquired by an unsizing coercion, and the size |
ba9703b0 XL |
358 | /// of the *entire value* (dynamic tail length + statically sized prefix) |
359 | /// must fit in `isize`. | |
360 | /// - an (unstable) [extern type], then this function is always safe to | |
361 | /// call, but may panic or otherwise return the wrong value, as the | |
362 | /// extern type's layout is not known. This is the same behavior as | |
f035d41b | 363 | /// [`size_of_val`] on a reference to a type with an extern type tail. |
ba9703b0 XL |
364 | /// - otherwise, it is conservatively not allowed to call this function. |
365 | /// | |
366 | /// [slice]: ../../std/primitive.slice.html | |
367 | /// [trait object]: ../../book/ch17-02-trait-objects.html | |
368 | /// [extern type]: ../../unstable-book/language-features/extern-types.html | |
369 | /// | |
370 | /// # Examples | |
371 | /// | |
372 | /// ``` | |
373 | /// #![feature(layout_for_ptr)] | |
374 | /// use std::mem; | |
375 | /// | |
376 | /// assert_eq!(4, mem::size_of_val(&5i32)); | |
377 | /// | |
378 | /// let x: [u8; 13] = [0; 13]; | |
379 | /// let y: &[u8] = &x; | |
380 | /// assert_eq!(13, unsafe { mem::size_of_val_raw(y) }); | |
381 | /// ``` | |
382 | #[inline] | |
ba9703b0 | 383 | #[unstable(feature = "layout_for_ptr", issue = "69835")] |
5869c6ff XL |
384 | #[rustc_const_unstable(feature = "const_size_of_val_raw", issue = "46571")] |
385 | pub const unsafe fn size_of_val_raw<T: ?Sized>(val: *const T) -> usize { | |
386 | // SAFETY: the caller must provide a valid raw pointer | |
387 | unsafe { intrinsics::size_of_val(val) } | |
ba9703b0 XL |
388 | } |
389 | ||
dc9dc135 XL |
390 | /// Returns the [ABI]-required minimum alignment of a type. |
391 | /// | |
392 | /// Every reference to a value of the type `T` must be a multiple of this number. | |
393 | /// | |
394 | /// This is the alignment used for struct fields. It may be smaller than the preferred alignment. | |
395 | /// | |
396 | /// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface | |
397 | /// | |
398 | /// # Examples | |
399 | /// | |
400 | /// ``` | |
401 | /// # #![allow(deprecated)] | |
402 | /// use std::mem; | |
403 | /// | |
404 | /// assert_eq!(4, mem::min_align_of::<i32>()); | |
405 | /// ``` | |
406 | #[inline] | |
407 | #[stable(feature = "rust1", since = "1.0.0")] | |
408 | #[rustc_deprecated(reason = "use `align_of` instead", since = "1.2.0")] | |
409 | pub fn min_align_of<T>() -> usize { | |
410 | intrinsics::min_align_of::<T>() | |
411 | } | |
412 | ||
413 | /// Returns the [ABI]-required minimum alignment of the type of the value that `val` points to. | |
414 | /// | |
415 | /// Every reference to a value of the type `T` must be a multiple of this number. | |
416 | /// | |
417 | /// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface | |
418 | /// | |
419 | /// # Examples | |
420 | /// | |
421 | /// ``` | |
422 | /// # #![allow(deprecated)] | |
423 | /// use std::mem; | |
424 | /// | |
425 | /// assert_eq!(4, mem::min_align_of_val(&5i32)); | |
426 | /// ``` | |
427 | #[inline] | |
428 | #[stable(feature = "rust1", since = "1.0.0")] | |
429 | #[rustc_deprecated(reason = "use `align_of_val` instead", since = "1.2.0")] | |
430 | pub fn min_align_of_val<T: ?Sized>(val: &T) -> usize { | |
5869c6ff XL |
431 | // SAFETY: val is a reference, so it's a valid raw pointer |
432 | unsafe { intrinsics::min_align_of_val(val) } | |
dc9dc135 XL |
433 | } |
434 | ||
435 | /// Returns the [ABI]-required minimum alignment of a type. | |
436 | /// | |
437 | /// Every reference to a value of the type `T` must be a multiple of this number. | |
438 | /// | |
439 | /// This is the alignment used for struct fields. It may be smaller than the preferred alignment. | |
440 | /// | |
441 | /// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface | |
442 | /// | |
443 | /// # Examples | |
444 | /// | |
445 | /// ``` | |
446 | /// use std::mem; | |
447 | /// | |
448 | /// assert_eq!(4, mem::align_of::<i32>()); | |
449 | /// ``` | |
e74abb32 | 450 | #[inline(always)] |
dc9dc135 XL |
451 | #[stable(feature = "rust1", since = "1.0.0")] |
452 | #[rustc_promotable] | |
dfeec247 | 453 | #[rustc_const_stable(feature = "const_align_of", since = "1.32.0")] |
dc9dc135 XL |
454 | pub const fn align_of<T>() -> usize { |
455 | intrinsics::min_align_of::<T>() | |
456 | } | |
457 | ||
458 | /// Returns the [ABI]-required minimum alignment of the type of the value that `val` points to. | |
459 | /// | |
460 | /// Every reference to a value of the type `T` must be a multiple of this number. | |
461 | /// | |
462 | /// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface | |
463 | /// | |
464 | /// # Examples | |
465 | /// | |
466 | /// ``` | |
467 | /// use std::mem; | |
468 | /// | |
469 | /// assert_eq!(4, mem::align_of_val(&5i32)); | |
470 | /// ``` | |
471 | #[inline] | |
472 | #[stable(feature = "rust1", since = "1.0.0")] | |
3dfed10e | 473 | #[rustc_const_unstable(feature = "const_align_of_val", issue = "46571")] |
60c5eb7d | 474 | #[allow(deprecated)] |
3dfed10e | 475 | pub const fn align_of_val<T: ?Sized>(val: &T) -> usize { |
5869c6ff XL |
476 | // SAFETY: val is a reference, so it's a valid raw pointer |
477 | unsafe { intrinsics::min_align_of_val(val) } | |
dc9dc135 XL |
478 | } |
479 | ||
ba9703b0 XL |
480 | /// Returns the [ABI]-required minimum alignment of the type of the value that `val` points to. |
481 | /// | |
482 | /// Every reference to a value of the type `T` must be a multiple of this number. | |
483 | /// | |
484 | /// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface | |
485 | /// | |
486 | /// # Safety | |
487 | /// | |
488 | /// This function is only safe to call if the following conditions hold: | |
489 | /// | |
490 | /// - If `T` is `Sized`, this function is always safe to call. | |
491 | /// - If the unsized tail of `T` is: | |
3dfed10e | 492 | /// - a [slice], then the length of the slice tail must be an initialized |
ba9703b0 XL |
493 | /// integer, and the size of the *entire value* |
494 | /// (dynamic tail length + statically sized prefix) must fit in `isize`. | |
495 | /// - a [trait object], then the vtable part of the pointer must point | |
3dfed10e | 496 | /// to a valid vtable acquired by an unsizing coercion, and the size |
ba9703b0 XL |
497 | /// of the *entire value* (dynamic tail length + statically sized prefix) |
498 | /// must fit in `isize`. | |
499 | /// - an (unstable) [extern type], then this function is always safe to | |
500 | /// call, but may panic or otherwise return the wrong value, as the | |
501 | /// extern type's layout is not known. This is the same behavior as | |
f035d41b | 502 | /// [`align_of_val`] on a reference to a type with an extern type tail. |
ba9703b0 XL |
503 | /// - otherwise, it is conservatively not allowed to call this function. |
504 | /// | |
505 | /// [slice]: ../../std/primitive.slice.html | |
506 | /// [trait object]: ../../book/ch17-02-trait-objects.html | |
507 | /// [extern type]: ../../unstable-book/language-features/extern-types.html | |
508 | /// | |
509 | /// # Examples | |
510 | /// | |
511 | /// ``` | |
512 | /// #![feature(layout_for_ptr)] | |
513 | /// use std::mem; | |
514 | /// | |
515 | /// assert_eq!(4, unsafe { mem::align_of_val_raw(&5i32) }); | |
516 | /// ``` | |
517 | #[inline] | |
ba9703b0 | 518 | #[unstable(feature = "layout_for_ptr", issue = "69835")] |
5869c6ff XL |
519 | #[rustc_const_unstable(feature = "const_align_of_val_raw", issue = "46571")] |
520 | pub const unsafe fn align_of_val_raw<T: ?Sized>(val: *const T) -> usize { | |
521 | // SAFETY: the caller must provide a valid raw pointer | |
522 | unsafe { intrinsics::min_align_of_val(val) } | |
ba9703b0 XL |
523 | } |
524 | ||
dc9dc135 XL |
525 | /// Returns `true` if dropping values of type `T` matters. |
526 | /// | |
527 | /// This is purely an optimization hint, and may be implemented conservatively: | |
528 | /// it may return `true` for types that don't actually need to be dropped. | |
529 | /// As such always returning `true` would be a valid implementation of | |
530 | /// this function. However if this function actually returns `false`, then you | |
531 | /// can be certain dropping `T` has no side effect. | |
532 | /// | |
533 | /// Low level implementations of things like collections, which need to manually | |
534 | /// drop their data, should use this function to avoid unnecessarily | |
535 | /// trying to drop all their contents when they are destroyed. This might not | |
536 | /// make a difference in release builds (where a loop that has no side-effects | |
537 | /// is easily detected and eliminated), but is often a big win for debug builds. | |
538 | /// | |
e74abb32 XL |
539 | /// Note that [`drop_in_place`] already performs this check, so if your workload |
540 | /// can be reduced to some small number of [`drop_in_place`] calls, using this is | |
541 | /// unnecessary. In particular note that you can [`drop_in_place`] a slice, and that | |
dc9dc135 XL |
542 | /// will do a single needs_drop check for all the values. |
543 | /// | |
544 | /// Types like Vec therefore just `drop_in_place(&mut self[..])` without using | |
e74abb32 | 545 | /// `needs_drop` explicitly. Types like [`HashMap`], on the other hand, have to drop |
dc9dc135 XL |
546 | /// values one at a time and should use this API. |
547 | /// | |
1b1a35ee | 548 | /// [`drop_in_place`]: crate::ptr::drop_in_place |
e74abb32 | 549 | /// [`HashMap`]: ../../std/collections/struct.HashMap.html |
dc9dc135 XL |
550 | /// |
551 | /// # Examples | |
552 | /// | |
553 | /// Here's an example of how a collection might make use of `needs_drop`: | |
554 | /// | |
555 | /// ``` | |
556 | /// use std::{mem, ptr}; | |
557 | /// | |
558 | /// pub struct MyCollection<T> { | |
559 | /// # data: [T; 1], | |
560 | /// /* ... */ | |
561 | /// } | |
562 | /// # impl<T> MyCollection<T> { | |
563 | /// # fn iter_mut(&mut self) -> &mut [T] { &mut self.data } | |
564 | /// # fn free_buffer(&mut self) {} | |
565 | /// # } | |
566 | /// | |
567 | /// impl<T> Drop for MyCollection<T> { | |
568 | /// fn drop(&mut self) { | |
569 | /// unsafe { | |
570 | /// // drop the data | |
571 | /// if mem::needs_drop::<T>() { | |
572 | /// for x in self.iter_mut() { | |
573 | /// ptr::drop_in_place(x); | |
574 | /// } | |
575 | /// } | |
576 | /// self.free_buffer(); | |
577 | /// } | |
578 | /// } | |
579 | /// } | |
580 | /// ``` | |
581 | #[inline] | |
582 | #[stable(feature = "needs_drop", since = "1.21.0")] | |
dfeec247 | 583 | #[rustc_const_stable(feature = "const_needs_drop", since = "1.36.0")] |
29967ef6 | 584 | #[rustc_diagnostic_item = "needs_drop"] |
dc9dc135 XL |
585 | pub const fn needs_drop<T>() -> bool { |
586 | intrinsics::needs_drop::<T>() | |
587 | } | |
588 | ||
416331ca | 589 | /// Returns the value of type `T` represented by the all-zero byte-pattern. |
dc9dc135 | 590 | /// |
416331ca XL |
591 | /// This means that, for example, the padding byte in `(u8, u16)` is not |
592 | /// necessarily zeroed. | |
dc9dc135 | 593 | /// |
f035d41b XL |
594 | /// There is no guarantee that an all-zero byte-pattern represents a valid value |
595 | /// of some type `T`. For example, the all-zero byte-pattern is not a valid value | |
596 | /// for reference types (`&T`, `&mut T`) and functions pointers. Using `zeroed` | |
597 | /// on such types causes immediate [undefined behavior][ub] because [the Rust | |
598 | /// compiler assumes][inv] that there always is a valid value in a variable it | |
599 | /// considers initialized. | |
dc9dc135 | 600 | /// |
416331ca XL |
601 | /// This has the same effect as [`MaybeUninit::zeroed().assume_init()`][zeroed]. |
602 | /// It is useful for FFI sometimes, but should generally be avoided. | |
603 | /// | |
1b1a35ee | 604 | /// [zeroed]: MaybeUninit::zeroed |
dc9dc135 | 605 | /// [ub]: ../../reference/behavior-considered-undefined.html |
1b1a35ee | 606 | /// [inv]: MaybeUninit#initialization-invariant |
dc9dc135 XL |
607 | /// |
608 | /// # Examples | |
609 | /// | |
610 | /// Correct usage of this function: initializing an integer with zero. | |
611 | /// | |
612 | /// ``` | |
613 | /// use std::mem; | |
614 | /// | |
615 | /// let x: i32 = unsafe { mem::zeroed() }; | |
616 | /// assert_eq!(0, x); | |
617 | /// ``` | |
618 | /// | |
619 | /// *Incorrect* usage of this function: initializing a reference with zero. | |
620 | /// | |
416331ca XL |
621 | /// ```rust,no_run |
622 | /// # #![allow(invalid_value)] | |
dc9dc135 XL |
623 | /// use std::mem; |
624 | /// | |
625 | /// let _x: &i32 = unsafe { mem::zeroed() }; // Undefined behavior! | |
f035d41b | 626 | /// let _y: fn() = unsafe { mem::zeroed() }; // And again! |
dc9dc135 | 627 | /// ``` |
ba9703b0 | 628 | #[inline(always)] |
dc9dc135 | 629 | #[stable(feature = "rust1", since = "1.0.0")] |
e1599b0c | 630 | #[allow(deprecated_in_future)] |
416331ca | 631 | #[allow(deprecated)] |
dfeec247 | 632 | #[rustc_diagnostic_item = "mem_zeroed"] |
dc9dc135 | 633 | pub unsafe fn zeroed<T>() -> T { |
f035d41b XL |
634 | // SAFETY: the caller must guarantee that an all-zero value is valid for `T`. |
635 | unsafe { | |
636 | intrinsics::assert_zero_valid::<T>(); | |
637 | MaybeUninit::zeroed().assume_init() | |
638 | } | |
dc9dc135 XL |
639 | } |
640 | ||
641 | /// Bypasses Rust's normal memory-initialization checks by pretending to | |
642 | /// produce a value of type `T`, while doing nothing at all. | |
643 | /// | |
416331ca | 644 | /// **This function is deprecated.** Use [`MaybeUninit<T>`] instead. |
dc9dc135 XL |
645 | /// |
646 | /// The reason for deprecation is that the function basically cannot be used | |
60c5eb7d XL |
647 | /// correctly: it has the same effect as [`MaybeUninit::uninit().assume_init()`][uninit]. |
648 | /// As the [`assume_init` documentation][assume_init] explains, | |
649 | /// [the Rust compiler assumes][inv] that values are properly initialized. | |
dc9dc135 XL |
650 | /// As a consequence, calling e.g. `mem::uninitialized::<bool>()` causes immediate |
651 | /// undefined behavior for returning a `bool` that is not definitely either `true` | |
652 | /// or `false`. Worse, truly uninitialized memory like what gets returned here | |
653 | /// is special in that the compiler knows that it does not have a fixed value. | |
654 | /// This makes it undefined behavior to have uninitialized data in a variable even | |
655 | /// if that variable has an integer type. | |
656 | /// (Notice that the rules around uninitialized integers are not finalized yet, but | |
657 | /// until they are, it is advisable to avoid them.) | |
658 | /// | |
1b1a35ee XL |
659 | /// [uninit]: MaybeUninit::uninit |
660 | /// [assume_init]: MaybeUninit::assume_init | |
661 | /// [inv]: MaybeUninit#initialization-invariant | |
ba9703b0 | 662 | #[inline(always)] |
416331ca | 663 | #[rustc_deprecated(since = "1.39.0", reason = "use `mem::MaybeUninit` instead")] |
dc9dc135 | 664 | #[stable(feature = "rust1", since = "1.0.0")] |
e1599b0c | 665 | #[allow(deprecated_in_future)] |
416331ca | 666 | #[allow(deprecated)] |
dfeec247 | 667 | #[rustc_diagnostic_item = "mem_uninitialized"] |
dc9dc135 | 668 | pub unsafe fn uninitialized<T>() -> T { |
f035d41b XL |
669 | // SAFETY: the caller must guarantee that an unitialized value is valid for `T`. |
670 | unsafe { | |
671 | intrinsics::assert_uninit_valid::<T>(); | |
672 | MaybeUninit::uninit().assume_init() | |
673 | } | |
dc9dc135 XL |
674 | } |
675 | ||
676 | /// Swaps the values at two mutable locations, without deinitializing either one. | |
677 | /// | |
3dfed10e XL |
678 | /// * If you want to swap with a default or dummy value, see [`take`]. |
679 | /// * If you want to swap with a passed value, returning the old value, see [`replace`]. | |
680 | /// | |
dc9dc135 XL |
681 | /// # Examples |
682 | /// | |
683 | /// ``` | |
684 | /// use std::mem; | |
685 | /// | |
686 | /// let mut x = 5; | |
687 | /// let mut y = 42; | |
688 | /// | |
689 | /// mem::swap(&mut x, &mut y); | |
690 | /// | |
691 | /// assert_eq!(42, x); | |
692 | /// assert_eq!(5, y); | |
693 | /// ``` | |
694 | #[inline] | |
695 | #[stable(feature = "rust1", since = "1.0.0")] | |
696 | pub fn swap<T>(x: &mut T, y: &mut T) { | |
60c5eb7d XL |
697 | // SAFETY: the raw pointers have been created from safe mutable references satisfying all the |
698 | // constraints on `ptr::swap_nonoverlapping_one` | |
dc9dc135 XL |
699 | unsafe { |
700 | ptr::swap_nonoverlapping_one(x, y); | |
701 | } | |
702 | } | |
703 | ||
dfeec247 | 704 | /// Replaces `dest` with the default value of `T`, returning the previous `dest` value. |
dc9dc135 | 705 | /// |
3dfed10e XL |
706 | /// * If you want to replace the values of two variables, see [`swap`]. |
707 | /// * If you want to replace with a passed value instead of the default value, see [`replace`]. | |
708 | /// | |
dc9dc135 XL |
709 | /// # Examples |
710 | /// | |
711 | /// A simple example: | |
712 | /// | |
713 | /// ``` | |
dc9dc135 XL |
714 | /// use std::mem; |
715 | /// | |
716 | /// let mut v: Vec<i32> = vec![1, 2]; | |
717 | /// | |
718 | /// let old_v = mem::take(&mut v); | |
719 | /// assert_eq!(vec![1, 2], old_v); | |
720 | /// assert!(v.is_empty()); | |
721 | /// ``` | |
722 | /// | |
723 | /// `take` allows taking ownership of a struct field by replacing it with an "empty" value. | |
724 | /// Without `take` you can run into issues like these: | |
725 | /// | |
726 | /// ```compile_fail,E0507 | |
727 | /// struct Buffer<T> { buf: Vec<T> } | |
728 | /// | |
729 | /// impl<T> Buffer<T> { | |
730 | /// fn get_and_reset(&mut self) -> Vec<T> { | |
731 | /// // error: cannot move out of dereference of `&mut`-pointer | |
732 | /// let buf = self.buf; | |
733 | /// self.buf = Vec::new(); | |
734 | /// buf | |
735 | /// } | |
736 | /// } | |
737 | /// ``` | |
738 | /// | |
739 | /// Note that `T` does not necessarily implement [`Clone`], so it can't even clone and reset | |
740 | /// `self.buf`. But `take` can be used to disassociate the original value of `self.buf` from | |
741 | /// `self`, allowing it to be returned: | |
742 | /// | |
743 | /// ``` | |
dc9dc135 XL |
744 | /// use std::mem; |
745 | /// | |
746 | /// # struct Buffer<T> { buf: Vec<T> } | |
747 | /// impl<T> Buffer<T> { | |
748 | /// fn get_and_reset(&mut self) -> Vec<T> { | |
749 | /// mem::take(&mut self.buf) | |
750 | /// } | |
751 | /// } | |
416331ca XL |
752 | /// |
753 | /// let mut buffer = Buffer { buf: vec![0, 1] }; | |
754 | /// assert_eq!(buffer.buf.len(), 2); | |
755 | /// | |
756 | /// assert_eq!(buffer.get_and_reset(), vec![0, 1]); | |
757 | /// assert_eq!(buffer.buf.len(), 0); | |
dc9dc135 | 758 | /// ``` |
dc9dc135 | 759 | #[inline] |
e74abb32 | 760 | #[stable(feature = "mem_take", since = "1.40.0")] |
dc9dc135 XL |
761 | pub fn take<T: Default>(dest: &mut T) -> T { |
762 | replace(dest, T::default()) | |
763 | } | |
764 | ||
765 | /// Moves `src` into the referenced `dest`, returning the previous `dest` value. | |
766 | /// | |
767 | /// Neither value is dropped. | |
768 | /// | |
3dfed10e XL |
769 | /// * If you want to replace the values of two variables, see [`swap`]. |
770 | /// * If you want to replace with a default value, see [`take`]. | |
771 | /// | |
dc9dc135 XL |
772 | /// # Examples |
773 | /// | |
774 | /// A simple example: | |
775 | /// | |
776 | /// ``` | |
777 | /// use std::mem; | |
778 | /// | |
779 | /// let mut v: Vec<i32> = vec![1, 2]; | |
780 | /// | |
781 | /// let old_v = mem::replace(&mut v, vec![3, 4, 5]); | |
782 | /// assert_eq!(vec![1, 2], old_v); | |
783 | /// assert_eq!(vec![3, 4, 5], v); | |
784 | /// ``` | |
785 | /// | |
786 | /// `replace` allows consumption of a struct field by replacing it with another value. | |
787 | /// Without `replace` you can run into issues like these: | |
788 | /// | |
789 | /// ```compile_fail,E0507 | |
790 | /// struct Buffer<T> { buf: Vec<T> } | |
791 | /// | |
792 | /// impl<T> Buffer<T> { | |
416331ca | 793 | /// fn replace_index(&mut self, i: usize, v: T) -> T { |
dc9dc135 | 794 | /// // error: cannot move out of dereference of `&mut`-pointer |
416331ca XL |
795 | /// let t = self.buf[i]; |
796 | /// self.buf[i] = v; | |
797 | /// t | |
dc9dc135 XL |
798 | /// } |
799 | /// } | |
800 | /// ``` | |
801 | /// | |
416331ca XL |
802 | /// Note that `T` does not necessarily implement [`Clone`], so we can't even clone `self.buf[i]` to |
803 | /// avoid the move. But `replace` can be used to disassociate the original value at that index from | |
dc9dc135 XL |
804 | /// `self`, allowing it to be returned: |
805 | /// | |
806 | /// ``` | |
807 | /// # #![allow(dead_code)] | |
808 | /// use std::mem; | |
809 | /// | |
810 | /// # struct Buffer<T> { buf: Vec<T> } | |
811 | /// impl<T> Buffer<T> { | |
416331ca XL |
812 | /// fn replace_index(&mut self, i: usize, v: T) -> T { |
813 | /// mem::replace(&mut self.buf[i], v) | |
dc9dc135 XL |
814 | /// } |
815 | /// } | |
416331ca XL |
816 | /// |
817 | /// let mut buffer = Buffer { buf: vec![0, 1] }; | |
818 | /// assert_eq!(buffer.buf[0], 0); | |
819 | /// | |
820 | /// assert_eq!(buffer.replace_index(0, 2), 0); | |
821 | /// assert_eq!(buffer.buf[0], 2); | |
dc9dc135 | 822 | /// ``` |
dc9dc135 XL |
823 | #[inline] |
824 | #[stable(feature = "rust1", since = "1.0.0")] | |
f9f354fc | 825 | #[must_use = "if you don't need the old value, you can just assign the new value directly"] |
dc9dc135 XL |
826 | pub fn replace<T>(dest: &mut T, mut src: T) -> T { |
827 | swap(dest, &mut src); | |
828 | src | |
829 | } | |
830 | ||
831 | /// Disposes of a value. | |
832 | /// | |
f035d41b | 833 | /// This does so by calling the argument's implementation of [`Drop`][drop]. |
dc9dc135 XL |
834 | /// |
835 | /// This effectively does nothing for types which implement `Copy`, e.g. | |
836 | /// integers. Such values are copied and _then_ moved into the function, so the | |
837 | /// value persists after this function call. | |
838 | /// | |
839 | /// This function is not magic; it is literally defined as | |
840 | /// | |
841 | /// ``` | |
842 | /// pub fn drop<T>(_x: T) { } | |
843 | /// ``` | |
844 | /// | |
845 | /// Because `_x` is moved into the function, it is automatically dropped before | |
846 | /// the function returns. | |
847 | /// | |
1b1a35ee | 848 | /// [drop]: Drop |
dc9dc135 XL |
849 | /// |
850 | /// # Examples | |
851 | /// | |
852 | /// Basic usage: | |
853 | /// | |
854 | /// ``` | |
855 | /// let v = vec![1, 2, 3]; | |
856 | /// | |
857 | /// drop(v); // explicitly drop the vector | |
858 | /// ``` | |
859 | /// | |
860 | /// Since [`RefCell`] enforces the borrow rules at runtime, `drop` can | |
861 | /// release a [`RefCell`] borrow: | |
862 | /// | |
863 | /// ``` | |
864 | /// use std::cell::RefCell; | |
865 | /// | |
866 | /// let x = RefCell::new(1); | |
867 | /// | |
868 | /// let mut mutable_borrow = x.borrow_mut(); | |
869 | /// *mutable_borrow = 1; | |
870 | /// | |
871 | /// drop(mutable_borrow); // relinquish the mutable borrow on this slot | |
872 | /// | |
873 | /// let borrow = x.borrow(); | |
874 | /// println!("{}", *borrow); | |
875 | /// ``` | |
876 | /// | |
877 | /// Integers and other types implementing [`Copy`] are unaffected by `drop`. | |
878 | /// | |
879 | /// ``` | |
880 | /// #[derive(Copy, Clone)] | |
881 | /// struct Foo(u8); | |
882 | /// | |
883 | /// let x = 1; | |
884 | /// let y = Foo(2); | |
885 | /// drop(x); // a copy of `x` is moved and dropped | |
886 | /// drop(y); // a copy of `y` is moved and dropped | |
887 | /// | |
888 | /// println!("x: {}, y: {}", x, y.0); // still available | |
889 | /// ``` | |
890 | /// | |
1b1a35ee | 891 | /// [`RefCell`]: crate::cell::RefCell |
5869c6ff | 892 | #[doc(alias = "delete")] |
dc9dc135 XL |
893 | #[inline] |
894 | #[stable(feature = "rust1", since = "1.0.0")] | |
dfeec247 | 895 | pub fn drop<T>(_x: T) {} |
dc9dc135 XL |
896 | |
897 | /// Interprets `src` as having type `&U`, and then reads `src` without moving | |
898 | /// the contained value. | |
899 | /// | |
29967ef6 XL |
900 | /// This function will unsafely assume the pointer `src` is valid for [`size_of::<U>`][size_of] |
901 | /// bytes by transmuting `&T` to `&U` and then reading the `&U` (except that this is done in a way | |
902 | /// that is correct even when `&U` makes stricter alignment requirements than `&T`). It will also | |
903 | /// unsafely create a copy of the contained value instead of moving out of `src`. | |
dc9dc135 XL |
904 | /// |
905 | /// It is not a compile-time error if `T` and `U` have different sizes, but it | |
906 | /// is highly encouraged to only invoke this function where `T` and `U` have the | |
907 | /// same size. This function triggers [undefined behavior][ub] if `U` is larger than | |
908 | /// `T`. | |
909 | /// | |
910 | /// [ub]: ../../reference/behavior-considered-undefined.html | |
dc9dc135 XL |
911 | /// |
912 | /// # Examples | |
913 | /// | |
914 | /// ``` | |
915 | /// use std::mem; | |
916 | /// | |
917 | /// #[repr(packed)] | |
918 | /// struct Foo { | |
919 | /// bar: u8, | |
920 | /// } | |
921 | /// | |
60c5eb7d | 922 | /// let foo_array = [10u8]; |
dc9dc135 XL |
923 | /// |
924 | /// unsafe { | |
60c5eb7d XL |
925 | /// // Copy the data from 'foo_array' and treat it as a 'Foo' |
926 | /// let mut foo_struct: Foo = mem::transmute_copy(&foo_array); | |
dc9dc135 XL |
927 | /// assert_eq!(foo_struct.bar, 10); |
928 | /// | |
929 | /// // Modify the copied data | |
930 | /// foo_struct.bar = 20; | |
931 | /// assert_eq!(foo_struct.bar, 20); | |
932 | /// } | |
933 | /// | |
60c5eb7d XL |
934 | /// // The contents of 'foo_array' should not have changed |
935 | /// assert_eq!(foo_array, [10]); | |
dc9dc135 XL |
936 | /// ``` |
937 | #[inline] | |
938 | #[stable(feature = "rust1", since = "1.0.0")] | |
939 | pub unsafe fn transmute_copy<T, U>(src: &T) -> U { | |
f9f354fc XL |
940 | // If U has a higher alignment requirement, src may not be suitably aligned. |
941 | if align_of::<U>() > align_of::<T>() { | |
f035d41b XL |
942 | // SAFETY: `src` is a reference which is guaranteed to be valid for reads. |
943 | // The caller must guarantee that the actual transmutation is safe. | |
944 | unsafe { ptr::read_unaligned(src as *const T as *const U) } | |
f9f354fc | 945 | } else { |
f035d41b XL |
946 | // SAFETY: `src` is a reference which is guaranteed to be valid for reads. |
947 | // We just checked that `src as *const U` was properly aligned. | |
948 | // The caller must guarantee that the actual transmutation is safe. | |
949 | unsafe { ptr::read(src as *const T as *const U) } | |
f9f354fc | 950 | } |
dc9dc135 XL |
951 | } |
952 | ||
953 | /// Opaque type representing the discriminant of an enum. | |
954 | /// | |
955 | /// See the [`discriminant`] function in this module for more information. | |
dc9dc135 | 956 | #[stable(feature = "discriminant_value", since = "1.21.0")] |
f9f354fc | 957 | pub struct Discriminant<T>(<T as DiscriminantKind>::Discriminant); |
dc9dc135 XL |
958 | |
959 | // N.B. These trait implementations cannot be derived because we don't want any bounds on T. | |
960 | ||
961 | #[stable(feature = "discriminant_value", since = "1.21.0")] | |
962 | impl<T> Copy for Discriminant<T> {} | |
963 | ||
964 | #[stable(feature = "discriminant_value", since = "1.21.0")] | |
965 | impl<T> clone::Clone for Discriminant<T> { | |
966 | fn clone(&self) -> Self { | |
967 | *self | |
968 | } | |
969 | } | |
970 | ||
971 | #[stable(feature = "discriminant_value", since = "1.21.0")] | |
972 | impl<T> cmp::PartialEq for Discriminant<T> { | |
973 | fn eq(&self, rhs: &Self) -> bool { | |
974 | self.0 == rhs.0 | |
975 | } | |
976 | } | |
977 | ||
978 | #[stable(feature = "discriminant_value", since = "1.21.0")] | |
979 | impl<T> cmp::Eq for Discriminant<T> {} | |
980 | ||
981 | #[stable(feature = "discriminant_value", since = "1.21.0")] | |
982 | impl<T> hash::Hash for Discriminant<T> { | |
983 | fn hash<H: hash::Hasher>(&self, state: &mut H) { | |
984 | self.0.hash(state); | |
985 | } | |
986 | } | |
987 | ||
988 | #[stable(feature = "discriminant_value", since = "1.21.0")] | |
989 | impl<T> fmt::Debug for Discriminant<T> { | |
990 | fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { | |
dfeec247 | 991 | fmt.debug_tuple("Discriminant").field(&self.0).finish() |
dc9dc135 XL |
992 | } |
993 | } | |
994 | ||
995 | /// Returns a value uniquely identifying the enum variant in `v`. | |
996 | /// | |
997 | /// If `T` is not an enum, calling this function will not result in undefined behavior, but the | |
998 | /// return value is unspecified. | |
999 | /// | |
1000 | /// # Stability | |
1001 | /// | |
1002 | /// The discriminant of an enum variant may change if the enum definition changes. A discriminant | |
1003 | /// of some variant will not change between compilations with the same compiler. | |
1004 | /// | |
1005 | /// # Examples | |
1006 | /// | |
1007 | /// This can be used to compare enums that carry data, while disregarding | |
1008 | /// the actual data: | |
1009 | /// | |
1010 | /// ``` | |
1011 | /// use std::mem; | |
1012 | /// | |
1013 | /// enum Foo { A(&'static str), B(i32), C(i32) } | |
1014 | /// | |
e74abb32 XL |
1015 | /// assert_eq!(mem::discriminant(&Foo::A("bar")), mem::discriminant(&Foo::A("baz"))); |
1016 | /// assert_eq!(mem::discriminant(&Foo::B(1)), mem::discriminant(&Foo::B(2))); | |
1017 | /// assert_ne!(mem::discriminant(&Foo::B(3)), mem::discriminant(&Foo::C(3))); | |
dc9dc135 XL |
1018 | /// ``` |
1019 | #[stable(feature = "discriminant_value", since = "1.21.0")] | |
ba9703b0 XL |
1020 | #[rustc_const_unstable(feature = "const_discriminant", issue = "69821")] |
1021 | pub const fn discriminant<T>(v: &T) -> Discriminant<T> { | |
f9f354fc | 1022 | Discriminant(intrinsics::discriminant_value(v)) |
dc9dc135 | 1023 | } |
f035d41b XL |
1024 | |
1025 | /// Returns the number of variants in the enum type `T`. | |
1026 | /// | |
1027 | /// If `T` is not an enum, calling this function will not result in undefined behavior, but the | |
1028 | /// return value is unspecified. Equally, if `T` is an enum with more variants than `usize::MAX` | |
1029 | /// the return value is unspecified. Uninhabited variants will be counted. | |
1030 | /// | |
1031 | /// # Examples | |
1032 | /// | |
1033 | /// ``` | |
1034 | /// # #![feature(never_type)] | |
1035 | /// # #![feature(variant_count)] | |
1036 | /// | |
1037 | /// use std::mem; | |
1038 | /// | |
1039 | /// enum Void {} | |
1040 | /// enum Foo { A(&'static str), B(i32), C(i32) } | |
1041 | /// | |
1042 | /// assert_eq!(mem::variant_count::<Void>(), 0); | |
1043 | /// assert_eq!(mem::variant_count::<Foo>(), 3); | |
1044 | /// | |
1045 | /// assert_eq!(mem::variant_count::<Option<!>>(), 2); | |
1046 | /// assert_eq!(mem::variant_count::<Result<!, !>>(), 2); | |
1047 | /// ``` | |
1048 | #[inline(always)] | |
f035d41b XL |
1049 | #[unstable(feature = "variant_count", issue = "73662")] |
1050 | #[rustc_const_unstable(feature = "variant_count", issue = "73662")] | |
1051 | pub const fn variant_count<T>() -> usize { | |
1052 | intrinsics::variant_count::<T>() | |
1053 | } |