//! 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.
//!
//! ```
/// 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.
///
/// 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
///
/// ```
///
/// 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 {
/// 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<u8>`]: ../../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
/// 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<u8>`]: ../../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<u8>) -> Result<String, FromUtf8Error> {
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:
decode_utf16(v.iter().cloned()).collect::<Result<_, _>>().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
/// 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
///
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
///
/// 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
///
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.
/// 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
/// boundary, or if they're out of bounds.
///
/// [`char`]: ../../std/primitive.char.html
+ /// [`Splice`]: ../../std/string/struct.Splice.html
///
/// # Examples
///
}
}
- /// Converts this `String` into a `Box<str>`.
+ /// 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:
projects / rust.git / commitdiff