diff --git a/src/liballoc/string.rs b/src/liballoc/string.rs index 76ee0158a6233..96bd6273c9484 100644 --- a/src/liballoc/string.rs +++ b/src/liballoc/string.rs @@ -38,7 +38,7 @@ //! let message = s + " world!"; //! ``` //! -//! If you have a vector of valid UTF-8 bytes, you can make a `String` out of +//! If you have a vector of valid UTF-8 bytes, you can make a [`String`] out of //! it. You can do the reverse too. //! //! ``` @@ -155,17 +155,14 @@ use boxed::Box; /// takes_str(&s); /// ``` /// -/// [`&str`]: ../../std/primitive.str.html -/// [`Deref`]: ../../std/ops/trait.Deref.html -/// /// This will create a [`&str`] from the `String` and pass it in. This /// conversion is very inexpensive, and so generally, functions will accept /// [`&str`]s as arguments unless they need a `String` for some specific /// reason. /// /// In certain cases Rust doesn't have enough information to make this -/// conversion, known as `Deref` coercion. In the following example a string -/// slice `&'a str` implements the trait `TraitExample`, and the function +/// conversion, known as [`Deref`] coercion. In the following example a string +/// slice [`&'a str`][`&str`] implements the trait `TraitExample`, and the function /// `example_func` takes anything that implements the trait. In this case Rust /// would need to make two implicit conversions, which Rust doesn't have the /// means to do. For that reason, the following example will not compile. @@ -185,13 +182,13 @@ use boxed::Box; /// /// There are two options that would work instead. The first would be to /// change the line `example_func(&example_string);` to -/// `example_func(example_string.as_str());`, using the method `as_str()` +/// `example_func(example_string.as_str());`, using the method [`as_str()`] /// to explicitly extract the string slice containing the string. The second /// way changes `example_func(&example_string);` to /// `example_func(&*example_string);`. In this case we are dereferencing a -/// `String` to a `str`, then referencing the `str` back to `&str`. The -/// second way is more idiomatic, however both work to do the conversion -/// explicitly rather than relying on the implicit conversion. +/// `String` to a [`str`][`&str`], then referencing the [`str`][`&str`] back to +/// [`&str`]. The second way is more idiomatic, however both work to do the +/// conversion explicitly rather than relying on the implicit conversion. /// /// # Representation /// @@ -287,6 +284,10 @@ use boxed::Box; /// ``` /// /// Here, there's no need to allocate more memory inside the loop. +/// +/// [`&str`]: ../../std/primitive.str.html +/// [`Deref`]: ../../std/ops/trait.Deref.html +/// [`as_str()`]: struct.String.html#method.as_str #[derive(PartialOrd, Eq, Ord)] #[stable(feature = "rust1", since = "1.0.0")] pub struct String { @@ -443,32 +444,22 @@ impl String { /// requires that it is valid UTF-8. `from_utf8()` checks to ensure that /// the bytes are valid UTF-8, and then does the conversion. /// - /// [`&str`]: ../../std/primitive.str.html - /// [`u8`]: ../../std/primitive.u8.html - /// [`Vec`]: ../../std/vec/struct.Vec.html - /// /// If you are sure that the byte slice is valid UTF-8, and you don't want /// to incur the overhead of the validity check, there is an unsafe version /// of this function, [`from_utf8_unchecked`], which has the same behavior /// but skips the check. /// - /// [`from_utf8_unchecked`]: struct.String.html#method.from_utf8_unchecked - /// /// This method will take care to not copy the vector, for efficiency's /// sake. /// - /// If you need a `&str` instead of a `String`, consider + /// If you need a [`&str`] instead of a `String`, consider /// [`str::from_utf8`]. /// - /// [`str::from_utf8`]: ../../std/str/fn.from_utf8.html - /// /// The inverse of this method is [`as_bytes`]. /// - /// [`as_bytes`]: #method.as_bytes - /// /// # Errors /// - /// Returns `Err` if the slice is not UTF-8 with a description as to why the + /// Returns [`Err`] if the slice is not UTF-8 with a description as to why the /// provided bytes are not UTF-8. The vector you moved in is also included. /// /// # Examples @@ -497,7 +488,14 @@ impl String { /// See the docs for [`FromUtf8Error`] for more details on what you can do /// with this error. /// + /// [`from_utf8_unchecked`]: struct.String.html#method.from_utf8_unchecked + /// [`&str`]: ../../std/primitive.str.html + /// [`u8`]: ../../std/primitive.u8.html + /// [`Vec`]: ../../std/vec/struct.Vec.html + /// [`str::from_utf8`]: ../../std/str/fn.from_utf8.html + /// [`as_bytes`]: struct.String.html#method.as_bytes /// [`FromUtf8Error`]: struct.FromUtf8Error.html + /// [`Err`]: ../../stdresult/enum.Result.html#variant.Err #[inline] #[stable(feature = "rust1", since = "1.0.0")] pub fn from_utf8(vec: Vec) -> Result { @@ -594,9 +592,11 @@ impl String { Cow::Owned(res) } - /// Decode a UTF-16 encoded vector `v` into a `String`, returning `Err` + /// Decode a UTF-16 encoded vector `v` into a `String`, returning [`Err`] /// if `v` contains any invalid data. /// + /// [`Err`]: ../../std/result/enum.Result.htlm#variant.Err + /// /// # Examples /// /// Basic usage: @@ -618,7 +618,7 @@ impl String { decode_utf16(v.iter().cloned()).collect::>().map_err(|_| FromUtf16Error(())) } - /// Decode a UTF-16 encoded vector `v` into a string, replacing + /// Decode a UTF-16 encoded slice `v` into a `String`, replacing /// invalid data with the replacement character (U+FFFD). /// /// # Examples @@ -800,11 +800,12 @@ impl String { /// If you do not want this "at least" behavior, see the [`reserve_exact`] /// method. /// - /// [`reserve_exact`]: #method.reserve_exact - /// /// # Panics /// - /// Panics if the new capacity overflows `usize`. + /// Panics if the new capacity overflows [`usize`]. + /// + /// [`reserve_exact`]: struct.String.html#method.reserve_exact + /// [`usize`]: ../../std/primitive.usize.html /// /// # Examples /// @@ -909,7 +910,9 @@ impl String { self.vec.shrink_to_fit() } - /// Appends the given `char` to the end of this `String`. + /// Appends the given [`char`] to the end of this `String`. + /// + /// [`char`]: ../../std/primitive.char.html /// /// # Examples /// @@ -990,7 +993,9 @@ impl String { /// Removes the last character from the string buffer and returns it. /// - /// Returns `None` if this `String` is empty. + /// Returns [`None`] if this `String` is empty. + /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None /// /// # Examples /// @@ -1019,7 +1024,7 @@ impl String { Some(ch) } - /// Removes a `char` from this `String` at a byte position and returns it. + /// Removes a [`char`] from this `String` at a byte position and returns it. /// /// This is an `O(n)` operation, as it requires copying every element in the /// buffer. @@ -1389,7 +1394,7 @@ impl String { /// replaces with the given string, and yields the removed chars. /// The given string doesn’t need to be the same length as the range. /// - /// Note: The element range is removed when the `Splice` is dropped, + /// Note: The element range is removed when the [`Splice`] is dropped, /// even if the iterator is not consumed until the end. /// /// # Panics @@ -1398,6 +1403,7 @@ impl String { /// boundary, or if they're out of bounds. /// /// [`char`]: ../../std/primitive.char.html + /// [`Splice`]: ../../std/string/struct.Splice.html /// /// # Examples /// @@ -1450,10 +1456,13 @@ impl String { } } - /// Converts this `String` into a `Box`. + /// Converts this `String` into a [`Box`]`<`[`str`]`>`. /// /// This will drop any excess capacity. /// + /// [`Box`]: ../../std/boxed/struct.Box.html + /// [`str`]: ../../std/primitive.str.html + /// /// # Examples /// /// Basic usage: