Skip to content

Commit a876b3d

Browse files
authored
docs(marker/copy): provide example for &T being Copy
In the current documentation about the `Copy` marker trait, there is a section with examples of structs that can implement `Copy`. Currently there is no example for showing that shared references (`&T`) are also `Copy`. It is worth to have a dedicated example for `&T` being `Copy`, because shared references are an integral part of the language and it being `Copy` is not as intuitive as other types that share this behaviour like `i32` or `bool`. The example picks up on the previous non-`Copy` struct and shows that structs can be `Copy`, even when they hold a shared reference to a non-`Copy` type.
1 parent 7835c8c commit a876b3d

File tree

1 file changed

+16
-3
lines changed

1 file changed

+16
-3
lines changed

library/core/src/marker.rs

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -315,6 +315,18 @@ pub trait StructuralEq {
315315
/// the trait `Copy` may not be implemented for this type; field `points` does not implement `Copy`
316316
/// ```
317317
///
318+
/// Shared references (`&T`) are also `Copy`, so a struct can be `Copy`, even when it holds
319+
/// shared references of types `T` that are *not* `Copy`. Consider the following struct,
320+
/// which can implement `Copy`, because it only holds a *shared reference* to our non-`Copy`
321+
/// type `PointList` from above:
322+
/// ```
323+
/// # #![allow(dead_code)]
324+
/// # struct PointList;
325+
/// struct PointListWrapper<'a> {
326+
/// point_list_ref: &'a PointList,
327+
/// }
328+
/// ```
329+
///
318330
/// ## When *can't* my type be `Copy`?
319331
///
320332
/// Some types can't be copied safely. For example, copying `&mut T` would create an aliased
@@ -347,8 +359,9 @@ pub trait StructuralEq {
347359
/// * Tuple types, if each component also implements `Copy` (e.g., `()`, `(i32, bool)`)
348360
/// * Closure types, if they capture no value from the environment
349361
/// or if all such captured values implement `Copy` themselves.
350-
/// * Variables captured by shared reference (e.g. `&T`) implement `Copy`, even if the referent (`T`) doesn't,
351-
/// while variables captured by mutable reference (e.g. `&mut T`) never implement `Copy`.
362+
/// Note that variables captured by shared reference always implement `Copy`
363+
/// (even if the referent doesn't),
364+
/// while variables captured by mutable reference never implement `Copy`.
352365
///
353366
/// [`Vec<T>`]: ../../std/vec/struct.Vec.html
354367
/// [`String`]: ../../std/string/struct.String.html
@@ -539,7 +552,7 @@ macro_rules! impls {
539552
/// For a more in-depth explanation of how to use `PhantomData<T>`, please see
540553
/// [the Nomicon](../../nomicon/phantom-data.html).
541554
///
542-
/// # A ghastly note 👻👻👻
555+
/// # A ghastly note
543556
///
544557
/// Though they both have scary names, `PhantomData` and 'phantom types' are
545558
/// related, but not identical. A phantom type parameter is simply a type

0 commit comments

Comments
 (0)