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