Adding upstream version 1.64.0+dfsg1.upstream/1.64.0+dfsg1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 245 insertions, 0 deletions

diff --git a/library/core/src/clone.rs b/library/core/src/clone.rs
new file mode 100644
index 000000000..06dca7e59
--- /dev/null
+++ b/library/core/src/clone.rs
@@ -0,0 +1,245 @@
+//! The `Clone` trait for types that cannot be 'implicitly copied'.
+//!
+//! In Rust, some simple types are "implicitly copyable" and when you
+//! assign them or pass them as arguments, the receiver will get a copy,
+//! leaving the original value in place. These types do not require
+//! allocation to copy and do not have finalizers (i.e., they do not
+//! contain owned boxes or implement [`Drop`]), so the compiler considers
+//! them cheap and safe to copy. For other types copies must be made
+//! explicitly, by convention implementing the [`Clone`] trait and calling
+//! the [`clone`] method.
+//!
+//! [`clone`]: Clone::clone
+//!
+//! Basic usage example:
+//!
+//! ```
+//! let s = String::new(); // String type implements Clone
+//! let copy = s.clone(); // so we can clone it
+//! ```
+//!
+//! To easily implement the Clone trait, you can also use
+//! `#[derive(Clone)]`. Example:
+//!
+//! ```
+//! #[derive(Clone)] // we add the Clone trait to Morpheus struct
+//! struct Morpheus {
+//!    blue_pill: f32,
+//!    red_pill: i64,
+//! }
+//!
+//! fn main() {
+//!    let f = Morpheus { blue_pill: 0.0, red_pill: 0 };
+//!    let copy = f.clone(); // and now we can clone it!
+//! }
+//! ```
+
+#![stable(feature = "rust1", since = "1.0.0")]
+
+use crate::marker::Destruct;
+
+/// A common trait for the ability to explicitly duplicate an object.
+///
+/// Differs from [`Copy`] in that [`Copy`] is implicit and an inexpensive bit-wise copy, while
+/// `Clone` is always explicit and may or may not be expensive. In order to enforce
+/// these characteristics, Rust does not allow you to reimplement [`Copy`], but you
+/// may reimplement `Clone` and run arbitrary code.
+///
+/// Since `Clone` is more general than [`Copy`], you can automatically make anything
+/// [`Copy`] be `Clone` as well.
+///
+/// ## Derivable
+///
+/// This trait can be used with `#[derive]` if all fields are `Clone`. The `derive`d
+/// implementation of [`Clone`] calls [`clone`] on each field.
+///
+/// [`clone`]: Clone::clone
+///
+/// For a generic struct, `#[derive]` implements `Clone` conditionally by adding bound `Clone` on
+/// generic parameters.
+///
+/// ```
+/// // `derive` implements Clone for Reading<T> when T is Clone.
+/// #[derive(Clone)]
+/// struct Reading<T> {
+///     frequency: T,
+/// }
+/// ```
+///
+/// ## How can I implement `Clone`?
+///
+/// Types that are [`Copy`] should have a trivial implementation of `Clone`. More formally:
+/// if `T: Copy`, `x: T`, and `y: &T`, then `let x = y.clone();` is equivalent to `let x = *y;`.
+/// Manual implementations should be careful to uphold this invariant; however, unsafe code
+/// must not rely on it to ensure memory safety.
+///
+/// An example is a generic struct holding a function pointer. In this case, the
+/// implementation of `Clone` cannot be `derive`d, but can be implemented as:
+///
+/// ```
+/// struct Generate<T>(fn() -> T);
+///
+/// impl<T> Copy for Generate<T> {}
+///
+/// impl<T> Clone for Generate<T> {
+///     fn clone(&self) -> Self {
+///         *self
+///     }
+/// }
+/// ```
+///
+/// ## Additional implementors
+///
+/// In addition to the [implementors listed below][impls],
+/// the following types also implement `Clone`:
+///
+/// * Function item types (i.e., the distinct types defined for each function)
+/// * Function pointer types (e.g., `fn() -> i32`)
+/// * Closure types, if they capture no value from the environment
+///   or if all such captured values implement `Clone` themselves.
+///   Note that variables captured by shared reference always implement `Clone`
+///   (even if the referent doesn't),
+///   while variables captured by mutable reference never implement `Clone`.
+///
+/// [impls]: #implementors
+#[stable(feature = "rust1", since = "1.0.0")]
+#[lang = "clone"]
+#[rustc_diagnostic_item = "Clone"]
+#[rustc_trivial_field_reads]
+#[const_trait]
+pub trait Clone: Sized {
+    /// Returns a copy of the value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # #![allow(noop_method_call)]
+    /// let hello = "Hello"; // &str implements Clone
+    ///
+    /// assert_eq!("Hello", hello.clone());
+    /// ```
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[must_use = "cloning is often expensive and is not expected to have side effects"]
+    fn clone(&self) -> Self;
+
+    /// Performs copy-assignment from `source`.
+    ///
+    /// `a.clone_from(&b)` is equivalent to `a = b.clone()` in functionality,
+    /// but can be overridden to reuse the resources of `a` to avoid unnecessary
+    /// allocations.
+    #[inline]
+    #[stable(feature = "rust1", since = "1.0.0")]
+    fn clone_from(&mut self, source: &Self)
+    where
+        Self: ~const Destruct,
+    {
+        *self = source.clone()
+    }
+}
+
+/// Derive macro generating an impl of the trait `Clone`.
+#[rustc_builtin_macro]
+#[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
+#[allow_internal_unstable(core_intrinsics, derive_clone_copy)]
+pub macro Clone($item:item) {
+    /* compiler built-in */
+}
+
+// FIXME(aburka): these structs are used solely by #[derive] to
+// assert that every component of a type implements Clone or Copy.
+//
+// These structs should never appear in user code.
+#[doc(hidden)]
+#[allow(missing_debug_implementations)]
+#[unstable(
+    feature = "derive_clone_copy",
+    reason = "deriving hack, should not be public",
+    issue = "none"
+)]
+pub struct AssertParamIsClone<T: Clone + ?Sized> {
+    _field: crate::marker::PhantomData<T>,
+}
+#[doc(hidden)]
+#[allow(missing_debug_implementations)]
+#[unstable(
+    feature = "derive_clone_copy",
+    reason = "deriving hack, should not be public",
+    issue = "none"
+)]
+pub struct AssertParamIsCopy<T: Copy + ?Sized> {
+    _field: crate::marker::PhantomData<T>,
+}
+
+/// Implementations of `Clone` for primitive types.
+///
+/// Implementations that cannot be described in Rust
+/// are implemented in `traits::SelectionContext::copy_clone_conditions()`
+/// in `rustc_trait_selection`.
+mod impls {
+
+    use super::Clone;
+
+    macro_rules! impl_clone {
+        ($($t:ty)*) => {
+            $(
+                #[stable(feature = "rust1", since = "1.0.0")]
+                #[rustc_const_unstable(feature = "const_clone", issue = "91805")]
+                impl const Clone for $t {
+                    #[inline]
+                    fn clone(&self) -> Self {
+                        *self
+                    }
+                }
+            )*
+        }
+    }
+
+    impl_clone! {
+        usize u8 u16 u32 u64 u128
+        isize i8 i16 i32 i64 i128
+        f32 f64
+        bool char
+    }
+
+    #[unstable(feature = "never_type", issue = "35121")]
+    #[rustc_const_unstable(feature = "const_clone", issue = "91805")]
+    impl const Clone for ! {
+        #[inline]
+        fn clone(&self) -> Self {
+            *self
+        }
+    }
+
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[rustc_const_unstable(feature = "const_clone", issue = "91805")]
+    impl<T: ?Sized> const Clone for *const T {
+        #[inline]
+        fn clone(&self) -> Self {
+            *self
+        }
+    }
+
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[rustc_const_unstable(feature = "const_clone", issue = "91805")]
+    impl<T: ?Sized> const Clone for *mut T {
+        #[inline]
+        fn clone(&self) -> Self {
+            *self
+        }
+    }
+
+    /// Shared references can be cloned, but mutable references *cannot*!
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[rustc_const_unstable(feature = "const_clone", issue = "91805")]
+    impl<T: ?Sized> const Clone for &T {
+        #[inline]
+        #[rustc_diagnostic_item = "noop_method_clone"]
+        fn clone(&self) -> Self {
+            *self
+        }
+    }
+
+    /// Shared references can be cloned, but mutable references *cannot*!
+    #[stable(feature = "rust1", since = "1.0.0")]
+    impl<T: ?Sized> !Clone for &mut T {}
+}