Change:
ARC is beginning to infect more and more types, and they each must have a clone method, but there is no trait to implement.
related
Along with this, we should provide a default implementation of Clonable for all copyable types.
Closing this now that has been implemented. There are no doubt some types left that should have a implementation, but they can be dealt with on a case-by-case basis.

Discussion:
// option. This file may not be copied, modified, or distributed // except according to those terms. <ins> #[doc(keyword = "as")] // /// The type coercion keyword. /// /// `as` is most commonly used to turn primitive types into other primitive types, but it has other /// uses that include turning pointers into addresses, addresses into pointers, and pointers into /// other pointers. /// /// ```rust /// let thing1: u8 = 89.0 as u8; /// assert_eq!('B' as u32, 66); /// assert_eq!(thing1 as char, 'Y'); /// let thing2: f32 = thing1 as f32 + 10.5; /// assert_eq!(true as u8 + thing2 as u8, 100); /// ``` /// /// In general, any coercion that can be performed via writing out type hints can also be done /// using `as`, so instead of writing `let x: u32 = 123`, you can write `let x = 123 as u32` (Note: /// `let x = 123u32` would be best in that situation). The same is not true in the other direction, /// however, explicitly using `as` allows a few more coercions that aren't allowed implicitly, such /// as changing the type of a raw pointer or turning closures into raw pointers. /// /// For more information on what `as` is capable of, see the [Reference] /// /// [Reference]: https://doc.rust-lang.org/reference/expressions/operator-expr.html#type-cast-expressions mod as_keyword { } #[doc(keyword = "const")] // /// The keyword for defining constants. /// /// Sometimes a certain value is used many times throughout a program, and it can become /// inconvenient to copy it over and over. What's more, it's not always possible or desirable to /// make it a variable that gets carried around to each function that needs it. In these cases, the /// `const` keyword provides a convenient alternative to code duplication. /// /// ```rust /// const THING: u32 = 0xABAD1DEA; /// /// let foo = 123 + THING; /// ``` /// /// Constants must be explicitly typed, unlike with `let` you can't ignore its type and let the /// compiler figure it out. Any constant value can be defined in a const, which in practice happens /// to be most things that would be reasonable to have a constant. For example, you can't have a /// File as a `const`. /// /// The only lifetime allowed in a constant is 'static, which is the lifetime that encompasses all /// others in a Rust program. For example, if you wanted to define a constant string, it would look /// like this: /// /// ```rust /// const WORDS: &'static str = "hello rust!"; /// ``` /// /// Thanks to static lifetime elision, you usually don't have to explicitly use 'static: /// /// ```rust /// const WORDS: &str = "hello convenience!"; /// ``` /// /// `const` items looks remarkably similar to [`static`] items, which introduces some confusion as /// to which one should be used at which times. To put it simply, constants are inlined wherever /// they're used, making using them identical to simply replacing the name of the const with its /// value. Static variables on the other hand point to a single location in memory, which all /// accesses share. This means that, unlike with constants, they can't have destructors, but it /// also means that (via unsafe code) they can be mutable, which is useful for the rare situations /// in which you can't avoid using global state. /// /// Constants, as with statics, should always be in SCREAMING_SNAKE_CASE. /// /// The `const` keyword is also used in raw pointers in combination with `mut`, as seen in `*const /// T` and `*mut T`. More about that can be read at the [pointer] primitive part of the Rust docs. /// /// For more detail on `const`, see the [Rust Book] or the [Reference] /// /// [`static`]: keyword.static.html /// [pointer]: primitive.pointer.html /// [Rust Book]: https://doc.rust-lang.org/stable/book/2018-edition/ch03-01-variables-and-mutability.html#differences-between-variables-and-constants /// [Reference]: https://doc.rust-lang.org/reference/items/constant-items.html mod const_keyword { } #[doc(keyword = "crate")] // /// The `crate` keyword. /// /// The primary use of the `crate` keyword is as a part of `extern crate` declarations, which are /// used to specify a dependency on a crate external to the one it's declared in. Crates are the /// fundamental compilation unit of Rust code, and can be seen as libraries or projects. More can /// be read about crates in the [Reference]. /// /// ```rust ignore /// extern crate rand; /// extern crate my_crate as thing; /// extern crate std; // implicitly added to the root of every Rust project /// ``` /// /// The `as` keyword can be used to change what the crate is referred to as in your project. If a /// crate name includes a dash, it is implicitly imported with the dashes replaced by underscores. /// /// `crate` is also used as in conjunction with [`pub`] to signify that the item it's attached to /// is public only to other members of the same crate it's in. /// /// ```rust /// # #[allow(unused_imports)] /// pub(crate) use std::io::Error as IoError; /// pub(crate) enum CoolMarkerType { } /// pub struct PublicThing { ///     pub(crate) semi_secret_thing: bool, /// } /// ``` /// /// [Reference]: https://doc.rust-lang.org/reference/items/extern-crates.html /// [`pub`]: keyword.pub.html mod crate_keyword { } #[doc(keyword = "enum")] // /// For defining enumerations. /// /// Enums in Rust are similar to those of other compiled languages like C, but have important /// differences that make them considerably more powerful. What Rust calls enums are more commonly /// known as Algebraic Data Types if you're coming from a functional programming background, but /// the important part is that data can go with the enum variants. /// /// ```rust /// # struct Coord; /// enum SimpleEnum { ///     FirstVariant, ///     SecondVariant, ///     ThirdVariant, /// } /// /// enum Location { ///     Unknown, ///     Anonymous, ///     Known(Coord), /// } /// /// enum ComplexEnum { ///     Nothing, ///     Something(u32), ///     LotsOfThings { ///         usual_struct_stuff: bool, ///         blah: String, ///     } /// } /// /// enum EmptyEnum { } /// ``` /// /// The first enum shown is the usual kind of enum you'd find in a C-style language. The second /// shows off a hypothetical example of something storing location data, with Coord being any other /// type that's needed, for example a struct. The third example demonstrates the kind of variant a /// variant can store, ranging from nothing, to a tuple, to an anonymous struct. /// /// Instantiating enum variants involves explicitly using the enum's name as its namespace, /// followed by one of its variants. `SimpleEnum::SecondVariant` would be an example from above. /// When data follows along with a variant, such as with rust's built-in [`Option`] type, the data /// is added as the type describes, for example `Option::Some(123)`. The same follows with /// struct-like variants, with things looking like `ComplexEnum::LotsOfThings { usual_struct_stuff: /// true, blah: "hello!".to_string(), }`. Empty Enums are similar to () in that they cannot be /// instantiated at all, and are used mainly to mess with the type system in interesting ways. /// /// For more information, take a look at the [Rust Book] or the [Reference] /// /// [`Option`]: option/enum.Option.html /// [Rust Book]: https://doc.rust-lang.org/book/second-edition/ch06-01-defining-an-enum.html /// [Reference]: https://doc.rust-lang.org/reference/items/enumerations.html mod enum_keyword { } #[doc(keyword = "extern")] // /// For external connections in Rust code. /// /// The `extern` keyword is used in two places in Rust. One is in conjunction with the [`crate`] /// keyword to make your Rust code aware of other Rust crates in your project, i.e. `extern crate /// lazy_static;`. The other use is in foreign function interfaces (FFI). /// /// `extern` is used in two different contexts within FFI. The first is in the form of external /// blcoks, for declaring function interfaces that Rust code can call foreign code by. /// /// ```rust ignore /// #[link(name = "my_c_library")] /// extern "C" { ///     fn my_c_function(x: i32) -> bool; /// } /// ``` /// /// This code would attempt to link with libmy_c_library.so on unix-like systems and /// my_c_library.dll on Windows at runtime, and panic if it can't find something to link to. Rust /// code could then use `my_c_function` as if it were any other unsafe Rust function. Working with /// non-Rust languages and FFI is inherently unsafe, so wrappers are usually built around C APIs. /// /// The mirror use case of FFI is also done via the `extern` keyword: /// /// ```rust /// # #![allow(private_no_mangle_fns)] /// #[no_mangle] /// pub extern fn callable_from_c(x: i32) -> bool { ///     x % 3 == 0 /// } /// ``` /// /// If compiled as a dylib, the resulting .so could then be linked to from a C library, and the /// function could be used as if it was from any other library. /// /// For more information on FFI, check the [Rust book] or the [Reference]. /// /// [Rust book]: https://doc.rust-lang.org/book/second-edition/ch19-01-unsafe-rust.html#using-extern-functions-to-call-external-code /// [Reference]: https://doc.rust-lang.org/reference/items/external-blocks.html mod extern_keyword { } </ins> #[doc(keyword = "fn")] // <del> /// The `fn` keyword. </del> <ins> /// The keyword for defining functions. </ins> /// <del> /// The `fn` keyword is used to declare a function. </del> <ins> /// Functions are the primary way code is executed within Rust. Function blocks, usually just /// called functions, can be defined in a variety of different places and be assigned many /// different attributes and modifiers. </ins> /// <del> /// Example: </del> <ins> /// Standalone functions that just sit within a module not attached to anything else are common, /// but most functions will end up being inside [`impl`] blocks, either on another type itself, or /// as a trait impl for that type. </ins> /// /// ```rust <del> /// fn some_function() { ///     // code goes in here </del> <ins> /// fn standalone_function() { ///     // code /// } /// /// pub fn public_thing(argument: bool) -> String { ///     // code ///     # "".to_string() /// } /// /// struct Thing { ///     foo: i32, /// } /// /// impl Thing { ///     pub fn new() -> Self { ///         Self { ///             foo: 42, ///         } ///     } </ins> /// } /// ``` /// <del> /// For more information about functions, take a look at the [Rust Book][book]. </del> <ins> /// See docs on [`impl`] and [`self`] for relevant details on those. /// /// In addition to presenting fixed types in the form of `fn name(arg: type, ..) -> return_type`, /// functions can also declare a list of type parameters along with trait bounds that they fall /// into. /// /// ```rust /// fn generic_function<T: Clone>(x: T) -> (T, T, T) { ///     (x.clone(), x.clone(), x.clone()) /// } </ins> /// <del> /// [book]: https://doc.rust-lang.org/book/second-edition/ch03-03-how-functions-work.html </del> <ins> /// fn generic_where<T>(x: T) -> T ///     where T: std::ops::Add<Output=T> + Copy /// { ///     x + x + x /// } /// ``` /// /// Declaring trait bounds in the angle brackets is functionally identical to using a [`where`] /// clause, but `where` is preferred due to it being easier to understand at a glance. /// /// Along with being made public via [`pub`], `fn` can also have an [`extern`] added for use in /// FFI. /// /// For more information on the various types of functions and how they're used, consult the [Rust /// book] or the [Reference]. /// /// [`impl`]: keyword.impl.html /// [`self`]: keyword.self.html /// [`where`]: keyword.where.html /// [`pub`]: keyword.pub.html /// [`extern`]: keyword.extern.html /// [Rust book]: https://doc.rust-lang.org/book/second-edition/ch03-03-how-functions-work.html /// [Reference]: https://doc.rust-lang.org/reference/items/functions.html </ins> mod fn_keyword { } <ins> #[doc(keyword = "for")] // /// The `for` keyword. /// /// `for` is primarily used in for-in-loops, but it has a few other pieces of syntactic uses such as /// `impl Trait for Type` (see [`impl`] for more info on that). for-in-loops, or to be more /// precise, iterator loops, are a simple syntactic sugar over an exceedingly common practice /// within Rust, which is to loop over an iterator until that iterator returns None (or [`break`] /// is called). /// /// ```rust /// for i in 0..5 { ///     println!("{}", i * 2); /// } /// /// for i in std::iter::repeat(5) { ///     println!("turns out {} never stops being 5", i); ///     break; // would loop forever otherwise /// } /// /// 'outer: for x in 5..50 { ///     for y in 0..10 { ///         if x == y { ///             break 'outer; ///         } ///     } /// } /// ``` /// /// As shown in the example above, `for` loops (along with all other loops) can be tagged, using /// similar syntax to lifetimes (only visually similar, entirely distinct in practice). Giving the /// same tag to `break` breaks the tagged loop, which is useful for inner loops. It is definitely /// not a goto. /// /// A `for` loop expands as shown: /// /// ```rust /// # fn code() { } /// # let iterator = 0..2; /// for loop_variable in iterator { ///     code() /// } /// ``` /// /// ```rust /// # fn code() { } /// # let iterator = 0..2; /// { ///     let mut _iter = std::iter::IntoIterator::into_iter(iterator); ///     loop { ///         match _iter.next() { ///             Some(loop_variable) => { ///                 code() ///             }, ///             None => break, ///         } ///     } /// } /// ``` /// /// More details on the functionality shown can be seen at the [`IntoIterator`] docs. /// /// For more information on for-loops, see the [Rust book] or the [Reference]. /// /// [`impl`]: keyword.impl.html /// [`break`]: keyword.break.html /// [`IntoIterator`]: iter/trait.IntoIterator.html /// [Rust book]: https://doc.rust-lang.org/book/2018-edition/ch03-05-control-flow.html#looping-through-a-collection-with-for /// [Reference]: https://doc.rust-lang.org/reference/expressions/loop-expr.html#iterator-loops mod for_keyword { } #[doc(keyword = "if")] // /// If statements and expressions. /// /// `if` is a familiar construct to most programmers, and is the main way you'll often do logic in /// your code. However, unlike in most languages, `if` blocks can also act as expressions. /// /// ```rust /// # let rude = true; /// if 1 == 2 { ///     println!("whoops, mathematics broke"); /// } else { ///     println!("everything's fine!"); /// } /// /// let greeting = if rude { ///     "sup nerd." /// } else { ///     "hello, friend!" /// }; /// /// if let Ok(x) = "123".parse::<i32>() { ///     println!("{} double that and you get {}!", greeting, x * 2); /// } /// ``` /// /// Shown above are the three typical forms an `if` block comes in. First is the usual kind of /// thing you'd see in many languages, with an optional `else` block. Second uses `if` as an /// expression, which is only possible if all branches return the same type. An `if` expression can /// be used everywhere you'd expect. The third kind of `if` block is an `if let` block, which /// behaves similarly to using a [`match`] expression: /// /// ```rust /// if let Some(x) = Some(123) { ///     // code ///     # let _ = x; /// } else { ///     // something else /// } /// /// match Some(123) { ///     Some(x) => { ///         // code ///         # let _ = x; ///     }, ///     _ => { ///         // something else ///     }, /// } /// ``` /// /// See [`let`] for more information on pattern bindings. /// /// Each kind of `if` expression can be mixed and matched as needed. /// /// ```rust /// if true == false { ///     println!("oh no"); /// } else if "something" == "other thing" { ///     println!("oh dear"); /// } else if let Some(200) = "blarg".parse::<i32>().ok() { ///     println!("uh oh"); /// } else { ///     println!("phew, nothing's broken"); /// } /// ``` /// /// The `if` keyword is used in one other place in Rust, namely as a part of pattern matching /// itself, allowing patterns such as `Some(x) if x > 200` to be used. /// /// For more information on `if` expressions, see the [Rust book] or the [Reference]. /// /// [`match`]: keyword.match.html /// [`let`]: keyword.let.html /// [Rust book]: https://doc.rust-lang.org/stable/book/2018-edition/ch03-05-control-flow.html#if-expressions /// [Reference]: https://doc.rust-lang.org/reference/expressions/if-expr.html mod if_keyword { } </ins> #[doc(keyword = "let")] // /// The `let` keyword.

#[doc(keyword = "struct")] // <del> /// The `struct` keyword. </del> <ins> /// The keyword used to define structs. </ins> /// <del> /// The `struct` keyword is used to define a struct type. </del> <ins> /// Structs in Rust come in three flavours: Regular structs, tuple structs, /// and empty structs. </ins> /// <del> /// Example: </del> <ins> /// ```rust /// struct Regular { ///     field1: f32, ///     field2: String, ///     pub field3: bool /// } /// /// struct Tuple(u32, String); </ins> /// <ins> /// struct Empty; </ins> /// ``` <del> /// struct Foo { ///     field1: u32, ///     field2: String, </del> <ins> /// /// Regular structs are the most commonly used. Each field defined within them has a name and a /// type, and once defined can be accessed using `example_struct.field` syntax. The fields of a /// struct share its mutability, so `foo.bar = 2;` would only be valid if `foo` was mutable. Adding /// `pub` to a field makes it visible to code in other modules, as well as allowing it to be /// directly accessed and modified. /// /// Tuple structs are similar to regular structs, but its fields have no names. They are used like /// tuples, with deconstruction possible via `let TupleStruct(x, y) = foo;` syntax.  For accessing /// individual variables, the same syntax is used as with regular tuples, namely `foo.0`, `foo.1`, /// etc, starting at zero. /// /// Empty structs, or unit-like structs, are most commonly used as markers, for example /// [`PhantomData`]. Empty structs have a size of zero bytes, but unlike empty enums they can be /// instantiated, making them similar to the unit type `()`. Unit-like structs are useful when you /// need to implement a trait on something, but don't need to store any data inside it. /// /// # Instantiation /// /// Structs can be instantiated in a manner of different ways, each of which can be mixed and /// matched as needed. The most common way to make a new struct is via a constructor method such as /// `new()`, but when that isn't available (or you're writing the constructor itself), struct /// literal syntax is used: /// /// ```rust /// # struct Foo { field1: f32, field2: String, etc: bool } /// let example = Foo { ///     field1: 42.0, ///     field2: "blah".to_string(), ///     etc: true, /// }; /// ``` /// /// It's only possible to directly instantiate a struct using struct literal syntax when all of its /// fields are visible to you. /// /// There are a handful of shortcuts provided to make writing constructors more convenient, most /// common of which is the Field Init shorthand. When there is a variable and a field of the same /// name, the assignment can be simplified from `field: field` into simply `field`. The following /// example of a hypothetical constructor demonstrates this: /// /// ```rust /// struct User { ///     name: String, ///     admin: bool, </ins> /// } <ins> /// /// impl User { ///     pub fn new(name: String) -> Self { ///         Self { ///             name, ///             admin: false, ///         } ///     } /// } /// ``` /// /// Another shortcut for struct instantiation is available, used when you need to make a new /// struct that has the same values as most of a previous struct of the same type, called struct /// update syntax: /// /// ```rust /// # struct Foo { field1: String, field2: () } /// # let thing = Foo { field1: "".to_string(), field2: () }; /// let updated_thing = Foo { ///     field1: "a new value".to_string(), ///     ..thing /// }; </ins> /// ``` /// <del> /// There are different kinds of structs. For more information, take a look at the /// [Rust Book][book]. </del> <ins> /// Tuple structs are instantiated in the same way as tuples themselves, except with the struct's /// name as a prefix: `Foo(123, false, 0.1)`. /// /// Empty structs are instantiated with just their name, and don't need anything else. `let thing = /// EmptyStruct;` /// /// # Style conventions /// /// Structs are always written in CamelCase, with few exceptions. While the trailing comma on a /// struct's list of fields can be omitted, it's usually kept for convenience in adding and /// removing fields down the line. /// /// For more information on structs, take a look at the [Rust Book][book] or the /// [Reference][reference]. </ins> /// <ins> /// [`PhantomData`]: marker/struct.PhantomData.html </ins> /// [book]: https://doc.rust-lang.org/book/second-edition/ch05-01-defining-structs.html <ins> /// [reference]: https://doc.rust-lang.org/reference/items/structs.html </ins> mod struct_keyword { }