Rollup of 16 pull requests

src/doc/rustdoc/src/unstable-features.md

@@ -38,50 +38,62 @@ future.
 Attempting to use these error numbers on stable will result in the code sample being interpreted as
 plain text.
 
-### Linking to items by type
+### Linking to items by name
 
-As designed in [RFC 1946], Rustdoc can parse paths to items when you use them as links. To resolve
-these type names, it uses the items currently in-scope, either by declaration or by `use` statement.
-For modules, the "active scope" depends on whether the documentation is written outside the module
-(as `///` comments on the `mod` statement) or inside the module (at `//!` comments inside the file
-or block). For all other items, it uses the enclosing module's scope.
+Rustdoc is capable of directly linking to other rustdoc pages in Markdown documentation using the path of item as a link.
 
-[RFC 1946]: https://github.com/rust-lang/rfcs/pull/1946
-
-For example, in the following code:
+For example, in the following code all of the links will link to the rustdoc page for `Bar`:
 
 ```rust
-/// Does the thing.
-pub fn do_the_thing(_: SomeType) {
-    println!("Let's do the thing!");
-}
+/// This struct is not [Bar]
+pub struct Foo1;
+
+/// This struct is also not [bar](Bar)
+pub struct Foo2;
+
+/// This struct is also not [bar][b]
+///
+/// [b]: Bar
+pub struct Foo3;
+
+/// This struct is also not [`Bar`]
+pub struct Foo4;
 
-/// Token you use to [`do_the_thing`].
-pub struct SomeType;
+pub struct Bar;
 ```
 
-The link to ``[`do_the_thing`]`` in `SomeType`'s docs will properly link to the page for `fn
-do_the_thing`. Note that here, rustdoc will insert the link target for you, but manually writing the
-target out also works:
+You can refer to anything in scope, and use paths, including `Self`. You may also use `foo()` and `foo!()` to refer to methods/functions and macros respectively.
 
-```rust
-pub mod some_module {
-    /// Token you use to do the thing.
-    pub struct SomeStruct;
-}
+```rust,edition2018
+use std::sync::mpsc::Receiver;
 
-/// Does the thing. Requires one [`SomeStruct`] for the thing to work.
+/// This is an version of [`Receiver`], with support for [`std::future`].
 ///
-/// [`SomeStruct`]: some_module::SomeStruct
-pub fn do_the_thing(_: some_module::SomeStruct) {
-    println!("Let's do the thing!");
+/// You can obtain a [`std::future::Future`] by calling [`Self::recv()`].
+pub struct AsyncReceiver<T> {
+    sender: Receiver<T>
+}
+
+impl<T> AsyncReceiver<T> {
+    pub async fn recv() -> T {
+        unimplemented!()
+    }
 }
 ```
 
-For more details, check out [the RFC][RFC 1946], and see [the tracking issue][43466] for more
-information about what parts of the feature are available.
+Paths in Rust have three namespaces: type, value, and macro. Items from these namespaces are allowed to overlap. In case of ambiguity, rustdoc will warn about the ambiguity and ask you to disambiguate, which can be done by using a prefix like `struct@`, `enum@`, `type@`, `trait@`, `union@`, `const@`, `static@`, `value@`, `function@`, `mod@`, `fn@`, `module@`, `method@` , `macro@`, or `derive@`:
+
+```rust
+/// See also: [`Foo`](struct@Foo)
+struct Bar;
+
+/// This is different from [`Foo`](fn@Foo)
+struct Foo {}
+
+fn Foo() {}
+```
 
-[43466]: https://github.com/rust-lang/rust/issues/43466
+Note: Because of how `macro_rules` macros are scoped in Rust, the intra-doc links of a `macro_rules` macro will be resolved relative to the crate root, as opposed to the module it is defined in.
 
 ## Extensions to the `#[doc]` attribute
 
@@ -321,7 +333,7 @@ library, as an equivalent command-line argument is provided to `rustc` when buil
 ### `--index-page`: provide a top-level landing page for docs
 
 This feature allows you to generate an index-page with a given markdown file. A good example of it
-is the [rust documentation index](https://doc.rust-lang.org/index.html).
+is the [rust documentation index](https://doc.rust-lang.org/nightly/index.html).
 
 With this, you'll have a page which you can custom as much as you want at the top of your crates.
 

src/liballoc/slice.rs

@@ -156,9 +156,9 @@ mod hack {
     where
         T: Clone,
     {
-        let mut vector = Vec::with_capacity(s.len());
-        vector.extend_from_slice(s);
-        vector
+        let mut vec = Vec::with_capacity(s.len());
+        vec.extend_from_slice(s);
+        vec
     }
 }
 

src/libcore/cmp.rs

@@ -35,7 +35,7 @@ use self::Ordering::*;
 ///
 /// This trait allows for partial equality, for types that do not have a full
 /// equivalence relation. For example, in floating point numbers `NaN != NaN`,
-/// so floating point types implement `PartialEq` but not [`Eq`].
+/// so floating point types implement `PartialEq` but not [`Eq`](Eq).
 ///
 /// Formally, the equality must be (for all `a`, `b` and `c`):
 ///
@@ -191,7 +191,6 @@ use self::Ordering::*;
 /// assert_eq!(x.eq(&y), false);
 /// ```
 ///
-/// [`Eq`]: Eq
 /// [`eq`]: PartialEq::eq
 /// [`ne`]: PartialEq::ne
 #[lang = "eq"]

src/libcore/num/mod.rs

@@ -2160,6 +2160,115 @@ assert_eq!((-a).rem_euclid(-b), 1);
             }
         }
 
+        doc_comment! {
+            concat!("Returns the logarithm of the number with respect to an arbitrary base.
+
+Returns `None` if the number is negative or zero, or if the base is not at least 2.
+
+This method may not be optimized owing to implementation details;
+`self.checked_log2()` can produce results more efficiently for base 2, and
+`self.checked_log10()` can produce results more efficiently for base 10.
+
+# Examples
+
+```
+#![feature(int_log)]
+
+let five = 5", stringify!($SelfT), ";
+
+// log5(5) == 1
+let result = five.checked_log(5);
+
+assert_eq!(result, Some(1));
+```"),
+            #[unstable(feature = "int_log", issue = "70887")]
+            #[must_use = "this returns the result of the operation, \
+                          without modifying the original"]
+            #[inline]
+            pub fn checked_log(self, base: Self) -> Option<Self> {
+                // SAFETY: We check the input to this is always positive
+                let logb2 = |x: Self| unsafe { intrinsics::ctlz_nonzero(1 as Self) - intrinsics::ctlz_nonzero(x) };
+
+                if self <= 0 || base <= 1 {
+                    None
+                } else {
+                    let mut n = 0;
+                    let mut r = self;
+
+                    // Optimization for 128 bit wide integers.
+                    if mem::size_of::<Self>() * 8 == 128 {
+                        let b = logb2(self) / (logb2(base) + 1);
+                        n += b;
+                        r /= base.pow(b as u32);
+                    }
+
+                    while r >= base {
+                        r /= base;
+                        n += 1;
+                    }
+                    Some(n)
+                }
+            }
+        }
+
+        doc_comment! {
+            concat!("Returns the base 2 logarithm of the number.
+
+Returns `None` if the number is negative or zero.
+
+# Examples
+
+```
+#![feature(int_log)]
+
+let two = 2", stringify!($SelfT), ";
+
+// checked_log2(2) == 1
+let result = two.checked_log2();
+
+assert_eq!(result, Some(1));
+```"),
+            #[unstable(feature = "int_log", issue = "70887")]
+            #[must_use = "this returns the result of the operation, \
+                          without modifying the original"]
+            #[inline]
+            pub fn checked_log2(self) -> Option<Self> {
+                if self <= 0 {
+                    None
+                } else {
+                    // SAFETY: We just checked that this number is positive
+                    let log = unsafe { intrinsics::ctlz_nonzero(1 as Self) - intrinsics::ctlz_nonzero(self) };
+                    Some(log)
+                }
+            }
+        }
+
+        doc_comment! {
+            concat!("Returns the base 10 logarithm of the number.
+
+Returns `None` if the number is negative or zero.
+
+# Examples
+
+```
+#![feature(int_log)]
+
+let ten = 10", stringify!($SelfT), ";
+
+// checked_log10(10) == 1
+let result = ten.checked_log10();
+
+assert_eq!(result, Some(1));
+```"),
+            #[unstable(feature = "int_log", issue = "70887")]
+            #[must_use = "this returns the result of the operation, \
+                          without modifying the original"]
+            #[inline]
+            pub fn checked_log10(self) -> Option<Self> {
+                self.checked_log(10)
+            }
+        }
+
         doc_comment! {
             concat!("Computes the absolute value of `self`.
 
@@ -4169,6 +4278,115 @@ assert_eq!(7", stringify!($SelfT), ".rem_euclid(4), 3); // or any other integer
             }
         }
 
+        doc_comment! {
+            concat!("Returns the logarithm of the number with respect to an arbitrary base.
+
+Returns `None` if the number is zero, or if the base is not at least 2.
+
+This method may not be optimized owing to implementation details;
+`self.checked_log2()` can produce results more efficiently for base 2, and
+`self.checked_log10()` can produce results more efficiently for base 10.
+
+# Examples
+
+```
+#![feature(int_log)]
+
+let five = 5", stringify!($SelfT), ";
+
+// log5(5) == 1
+let result = five.checked_log(5);
+
+assert_eq!(result, Some(1));
+```"),
+            #[unstable(feature = "int_log", issue = "70887")]
+            #[must_use = "this returns the result of the operation, \
+                          without modifying the original"]
+            #[inline]
+            pub fn checked_log(self, base: Self) -> Option<Self> {
+                // SAFETY: We check the input to this is always positive.
+                let logb2 = |x: Self| unsafe { intrinsics::ctlz_nonzero(1 as Self) - intrinsics::ctlz_nonzero(x) };
+
+                if self <= 0 || base <= 1 {
+                    None
+                } else {
+                    let mut n = 0;
+                    let mut r = self;
+
+                    // Optimization for 128 bit wide integers.
+                    if mem::size_of::<Self>() * 8 == 128 {
+                        let b = logb2(self) / (logb2(base) + 1);
+                        n += b;
+                        r /= base.pow(b as u32);
+                    }
+
+                    while r >= base {
+                        r /= base;
+                        n += 1;
+                    }
+                    Some(n)
+                }
+            }
+        }
+
+        doc_comment! {
+            concat!("Returns the base 2 logarithm of the number.
+
+Returns `None` if the number is zero.
+
+# Examples
+
+```
+#![feature(int_log)]
+
+let two = 2", stringify!($SelfT), ";
+
+// checked_log2(2) == 1
+let result = two.checked_log2();
+
+assert_eq!(result, Some(1));
+```"),
+            #[unstable(feature = "int_log", issue = "70887")]
+            #[must_use = "this returns the result of the operation, \
+                          without modifying the original"]
+            #[inline]
+            pub fn checked_log2(self) -> Option<Self> {
+                if self <= 0 {
+                    None
+                } else {
+                    // SAFETY: We just checked that this number is positive
+                    let log = unsafe { intrinsics::ctlz_nonzero(1 as Self) - intrinsics::ctlz_nonzero(self) };
+                    Some(log)
+                }
+            }
+        }
+
+        doc_comment! {
+            concat!("Returns the base 10 logarithm of the number.
+
+Returns `None` if the number is zero.
+
+# Examples
+
+```
+#![feature(int_log)]
+
+let ten = 10", stringify!($SelfT), ";
+
+// checked_log10(10) == 1
+let result = ten.checked_log10();
+
+assert_eq!(result, Some(1));
+```"),
+            #[unstable(feature = "int_log", issue = "70887")]
+            #[must_use = "this returns the result of the operation, \
+                          without modifying the original"]
+            #[inline]
+            pub fn checked_log10(self) -> Option<Self> {
+                self.checked_log(10)
+            }
+        }
+
         doc_comment! {
             concat!("Returns `true` if and only if `self == 2^k` for some `k`.
 

src/libcore/tests/lib.rs

@@ -13,6 +13,7 @@
 #![feature(fmt_internals)]
 #![feature(hashmap_internals)]
 #![feature(try_find)]
+#![feature(int_log)]
 #![feature(is_sorted)]
 #![feature(pattern)]
 #![feature(range_is_empty)]