Auto merge of #42523 - clarcharr:refactor_ops, r=brson

Refactor ops.rs

This refactors ops.rs into several different modules internally, as the file has gotten quite big. None of these modules are actually exported, but this should make maintaining it much easier. I've avoided the ambition of exporting the modules because they can more easily be rearranged after this commit goes through, even though it'd be cool to potentially export the modules in the future.

I've separated the creation of each file into a separate commit so that this is easier to read.

Redone version of #42269 with the movement of `RangeArgument` moved.

src/libcore/ops/deref.rs

@@ -0,0 +1,119 @@
+// Copyright 2012 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+/// The `Deref` trait is used to specify the functionality of dereferencing
+/// operations, like `*v`.
+///
+/// `Deref` also enables ['`Deref` coercions'][coercions].
+///
+/// [coercions]: ../../book/deref-coercions.html
+///
+/// # Examples
+///
+/// A struct with a single field which is accessible via dereferencing the
+/// struct.
+///
+/// ```
+/// use std::ops::Deref;
+///
+/// struct DerefExample<T> {
+///     value: T
+/// }
+///
+/// impl<T> Deref for DerefExample<T> {
+///     type Target = T;
+///
+///     fn deref(&self) -> &T {
+///         &self.value
+///     }
+/// }
+///
+/// fn main() {
+///     let x = DerefExample { value: 'a' };
+///     assert_eq!('a', *x);
+/// }
+/// ```
+#[lang = "deref"]
+#[stable(feature = "rust1", since = "1.0.0")]
+pub trait Deref {
+    /// The resulting type after dereferencing
+    #[stable(feature = "rust1", since = "1.0.0")]
+    type Target: ?Sized;
+
+    /// The method called to dereference a value
+    #[stable(feature = "rust1", since = "1.0.0")]
+    fn deref(&self) -> &Self::Target;
+}
+
+#[stable(feature = "rust1", since = "1.0.0")]
+impl<'a, T: ?Sized> Deref for &'a T {
+    type Target = T;
+
+    fn deref(&self) -> &T { *self }
+}
+
+#[stable(feature = "rust1", since = "1.0.0")]
+impl<'a, T: ?Sized> Deref for &'a mut T {
+    type Target = T;
+
+    fn deref(&self) -> &T { *self }
+}
+
+/// The `DerefMut` trait is used to specify the functionality of dereferencing
+/// mutably like `*v = 1;`
+///
+/// `DerefMut` also enables ['`Deref` coercions'][coercions].
+///
+/// [coercions]: ../../book/deref-coercions.html
+///
+/// # Examples
+///
+/// A struct with a single field which is modifiable via dereferencing the
+/// struct.
+///
+/// ```
+/// use std::ops::{Deref, DerefMut};
+///
+/// struct DerefMutExample<T> {
+///     value: T
+/// }
+///
+/// impl<T> Deref for DerefMutExample<T> {
+///     type Target = T;
+///
+///     fn deref(&self) -> &T {
+///         &self.value
+///     }
+/// }
+///
+/// impl<T> DerefMut for DerefMutExample<T> {
+///     fn deref_mut(&mut self) -> &mut T {
+///         &mut self.value
+///     }
+/// }
+///
+/// fn main() {
+///     let mut x = DerefMutExample { value: 'a' };
+///     *x = 'b';
+///     assert_eq!('b', *x);
+/// }
+/// ```
+#[lang = "deref_mut"]
+#[stable(feature = "rust1", since = "1.0.0")]
+pub trait DerefMut: Deref {
+    /// The method called to mutably dereference a value
+    #[stable(feature = "rust1", since = "1.0.0")]
+    fn deref_mut(&mut self) -> &mut Self::Target;
+}
+
+#[stable(feature = "rust1", since = "1.0.0")]
+impl<'a, T: ?Sized> DerefMut for &'a mut T {
+    fn deref_mut(&mut self) -> &mut T { *self }
+}

src/libcore/ops/drop.rs

@@ -0,0 +1,99 @@
+// Copyright 2012 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+/// The `Drop` trait is used to run some code when a value goes out of scope.
+/// This is sometimes called a 'destructor'.
+///
+/// When a value goes out of scope, if it implements this trait, it will have
+/// its `drop` method called. Then any fields the value contains will also
+/// be dropped recursively.
+///
+/// Because of the recursive dropping, you do not need to implement this trait
+/// unless your type needs its own destructor logic.
+///
+/// # Examples
+///
+/// A trivial implementation of `Drop`. The `drop` method is called when `_x`
+/// goes out of scope, and therefore `main` prints `Dropping!`.
+///
+/// ```
+/// struct HasDrop;
+///
+/// impl Drop for HasDrop {
+///     fn drop(&mut self) {
+///         println!("Dropping!");
+///     }
+/// }
+///
+/// fn main() {
+///     let _x = HasDrop;
+/// }
+/// ```
+///
+/// Showing the recursive nature of `Drop`. When `outer` goes out of scope, the
+/// `drop` method will be called first for `Outer`, then for `Inner`. Therefore
+/// `main` prints `Dropping Outer!` and then `Dropping Inner!`.
+///
+/// ```
+/// struct Inner;
+/// struct Outer(Inner);
+///
+/// impl Drop for Inner {
+///     fn drop(&mut self) {
+///         println!("Dropping Inner!");
+///     }
+/// }
+///
+/// impl Drop for Outer {
+///     fn drop(&mut self) {
+///         println!("Dropping Outer!");
+///     }
+/// }
+///
+/// fn main() {
+///     let _x = Outer(Inner);
+/// }
+/// ```
+///
+/// Because variables are dropped in the reverse order they are declared,
+/// `main` will print `Declared second!` and then `Declared first!`.
+///
+/// ```
+/// struct PrintOnDrop(&'static str);
+///
+/// fn main() {
+///     let _first = PrintOnDrop("Declared first!");
+///     let _second = PrintOnDrop("Declared second!");
+/// }
+/// ```
+#[lang = "drop"]
+#[stable(feature = "rust1", since = "1.0.0")]
+pub trait Drop {
+    /// A method called when the value goes out of scope.
+    ///
+    /// When this method has been called, `self` has not yet been deallocated.
+    /// If it were, `self` would be a dangling reference.
+    ///
+    /// After this function is over, the memory of `self` will be deallocated.
+    ///
+    /// This function cannot be called explicitly. This is compiler error
+    /// [E0040]. However, the [`std::mem::drop`] function in the prelude can be
+    /// used to call the argument's `Drop` implementation.
+    ///
+    /// [E0040]: ../../error-index.html#E0040
+    /// [`std::mem::drop`]: ../../std/mem/fn.drop.html
+    ///
+    /// # Panics
+    ///
+    /// Given that a `panic!` will call `drop()` as it unwinds, any `panic!` in
+    /// a `drop()` implementation will likely abort.
+    #[stable(feature = "rust1", since = "1.0.0")]
+    fn drop(&mut self);
+}