//! [`ToString`]s, and several error types that may result from working with
//! [`String`]s.
//!
-//! [`ToString`]: trait.ToString.html
-//!
//! # Examples
//!
//! There are multiple ways to create a new [`String`] from a string literal:
//! You can create a new [`String`] from an existing one by concatenating with
//! `+`:
//!
-//! [`String`]: struct.String.html
-//!
//! ```
//! let s = "Hello".to_string();
//!
/// contents of the string. It has a close relationship with its borrowed
/// counterpart, the primitive [`str`].
///
-/// [`str`]: ../../std/primitive.str.html
-///
/// # Examples
///
-/// You can create a `String` from a literal string with [`String::from`]:
+/// You can create a `String` from [a literal string][str] with [`String::from`]:
+///
+/// [`String::from`]: From::from
///
/// ```
/// let hello = String::from("Hello, world!");
/// hello.push_str("orld!");
/// ```
///
-/// [`String::from`]: #method.from
-/// [`char`]: ../../std/primitive.char.html
-/// [`push`]: #method.push
-/// [`push_str`]: #method.push_str
+/// [`push`]: String::push
+/// [`push_str`]: String::push_str
///
/// If you have a vector of UTF-8 bytes, you can create a `String` from it with
/// the [`from_utf8`] method:
/// assert_eq!("💖", sparkle_heart);
/// ```
///
-/// [`from_utf8`]: #method.from_utf8
+/// [`from_utf8`]: String::from_utf8
///
/// # UTF-8
///
/// The [`bytes`] and [`chars`] methods return iterators over the first
/// two, respectively.
///
-/// [`bytes`]: #method.bytes
-/// [`chars`]: #method.chars
+/// [`bytes`]: str::bytes
+/// [`chars`]: str::chars
///
/// # Deref
///
/// assert_eq!(String::from("Once upon a time..."), s);
/// ```
///
-/// [`as_ptr`]: #method.as_ptr
-/// [`len`]: #method.len
-/// [`capacity`]: #method.capacity
+/// [`as_ptr`]: str::as_ptr
+/// [`len`]: String::len
+/// [`capacity`]: String::capacity
///
/// If a `String` has enough capacity, adding elements to it will not
/// re-allocate. For example, consider this program:
/// }
/// ```
///
-/// [`with_capacity`]: #method.with_capacity
+/// [`with_capacity`]: String::with_capacity
///
/// We end up with a different output:
///
///
/// 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
+/// [`&str`]: str
+/// [`Deref`]: core::ops::Deref
+/// [`as_str()`]: String::as_str
#[derive(PartialOrd, Eq, Ord)]
#[cfg_attr(not(test), rustc_diagnostic_item = "string_type")]
#[stable(feature = "rust1", since = "1.0.0")]
/// [`into_bytes`] method will give back the byte vector that was used in the
/// conversion attempt.
///
-/// [`from_utf8`]: struct.String.html#method.from_utf8
-/// [`String`]: struct.String.html
-/// [`into_bytes`]: struct.FromUtf8Error.html#method.into_bytes
+/// [`from_utf8`]: String::from_utf8
+/// [`into_bytes`]: FromUtf8Error::into_bytes
///
/// The [`Utf8Error`] type provided by [`std::str`] represents an error that may
/// occur when converting a slice of [`u8`]s to a [`&str`]. In this sense, it's
/// an analogue to `FromUtf8Error`, and you can get one from a `FromUtf8Error`
/// through the [`utf8_error`] method.
///
-/// [`Utf8Error`]: ../../std/str/struct.Utf8Error.html
-/// [`std::str`]: ../../std/str/index.html
-/// [`u8`]: ../../std/primitive.u8.html
-/// [`&str`]: ../../std/primitive.str.html
-/// [`utf8_error`]: #method.utf8_error
+/// [`Utf8Error`]: core::str::Utf8Error
+/// [`std::str`]: core::str
+/// [`&str`]: str
+/// [`utf8_error`]: Self::utf8_error
///
/// # Examples
///
///
/// This type is the error type for the [`from_utf16`] method on [`String`].
///
-/// [`from_utf16`]: struct.String.html#method.from_utf16
-/// [`String`]: struct.String.html
-///
+/// [`from_utf16`]: String::from_utf16
/// # Examples
///
/// Basic usage:
/// consider the [`with_capacity`] method to prevent excessive
/// re-allocation.
///
- /// [`with_capacity`]: #method.with_capacity
+ /// [`with_capacity`]: String::with_capacity
///
/// # Examples
///
/// appending a bunch of data to the `String`, reducing the number of
/// reallocations it needs to do.
///
- /// [`capacity`]: #method.capacity
+ /// [`capacity`]: String::capacity
///
/// If the given capacity is `0`, no allocation will occur, and this method
/// is identical to the [`new`] method.
///
- /// [`new`]: #method.new
+ /// [`new`]: String::new
///
/// # 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
- /// [`String`]: struct.String.html
- /// [`u8`]: ../../std/primitive.u8.html
- /// [`Vec<u8>`]: ../../std/vec/struct.Vec.html
- /// [`&str`]: ../../std/primitive.str.html
- /// [`str::from_utf8`]: ../../std/str/fn.from_utf8.html
- /// [`into_bytes`]: struct.String.html#method.into_bytes
- /// [`FromUtf8Error`]: struct.FromUtf8Error.html
- /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
+ /// [`from_utf8_unchecked`]: String::from_utf8_unchecked
+ /// [`Vec<u8>`]: crate::vec::Vec
+ /// [`&str`]: str
+ /// [`into_bytes`]: String::into_bytes
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn from_utf8(vec: Vec<u8>) -> Result<String, FromUtf8Error> {
/// `from_utf8_lossy()` will replace any invalid UTF-8 sequences with
/// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD], which looks like this: �
///
- /// [`u8`]: ../../std/primitive.u8.html
/// [byteslice]: ../../std/primitive.slice.html
- /// [U+FFFD]: ../char/constant.REPLACEMENT_CHARACTER.html
+ /// [U+FFFD]: core::char::REPLACEMENT_CHARACTER
///
/// If you are sure that the byte slice is valid UTF-8, and you don't want
/// to incur the overhead of the conversion, there is an unsafe version
/// of this function, [`from_utf8_unchecked`], which has the same behavior
/// but skips the checks.
///
- /// [`from_utf8_unchecked`]: struct.String.html#method.from_utf8_unchecked
+ /// [`from_utf8_unchecked`]: String::from_utf8_unchecked
///
/// This function returns a [`Cow<'a, str>`]. If our byte slice is invalid
/// UTF-8, then we need to insert the replacement characters, which will
/// it's already valid UTF-8, we don't need a new allocation. This return
/// type allows us to handle both cases.
///
- /// [`Cow<'a, str>`]: ../../std/borrow/enum.Cow.html
+ /// [`Cow<'a, str>`]: crate::borrow::Cow
///
/// # Examples
///
/// Decode a UTF-16 encoded vector `v` into a `String`, returning [`Err`]
/// if `v` contains any invalid data.
///
- /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
- ///
/// # Examples
///
/// Basic usage:
/// `from_utf16_lossy` returns a `String` since the UTF-16 to UTF-8
/// conversion requires a memory allocation.
///
- /// [`from_utf8_lossy`]: #method.from_utf8_lossy
- /// [`Cow<'a, str>`]: ../borrow/enum.Cow.html
- /// [U+FFFD]: ../char/constant.REPLACEMENT_CHARACTER.html
+ /// [`from_utf8_lossy`]: String::from_utf8_lossy
+ /// [`Cow<'a, str>`]: crate::borrow::Cow
+ /// [U+FFFD]: core::char::REPLACEMENT_CHARACTER
///
/// # Examples
///
/// into a `String` with the [`from_raw_parts`] function, allowing
/// the destructor to perform the cleanup.
///
- /// [`from_raw_parts`]: #method.from_raw_parts
+ /// [`from_raw_parts`]: String::from_raw_parts
///
/// # Examples
///
///
/// See the safe version, [`from_utf8`], for more details.
///
- /// [`from_utf8`]: struct.String.html#method.from_utf8
+ /// [`from_utf8`]: String::from_utf8
///
/// # Safety
///
///
/// Panics if the new capacity overflows [`usize`].
///
- /// [`reserve_exact`]: struct.String.html#method.reserve_exact
- /// [`usize`]: ../../std/primitive.usize.html
+ /// [`reserve_exact`]: String::reserve_exact
///
/// # Examples
///
/// Consider using the [`reserve`] method unless you absolutely know
/// better than the allocator.
///
- /// [`reserve`]: #method.reserve
+ /// [`reserve`]: String::reserve
///
/// # Panics
///
/// Appends the given [`char`] to the end of this `String`.
///
- /// [`char`]: ../../std/primitive.char.html
- ///
/// # Examples
///
/// Basic usage:
///
/// The inverse of this method is [`from_utf8`].
///
- /// [`from_utf8`]: #method.from_utf8
+ /// [`from_utf8`]: String::from_utf8
///
/// # Examples
///
///
/// Panics if `new_len` does not lie on a [`char`] boundary.
///
- /// [`char`]: ../../std/primitive.char.html
- ///
/// # Examples
///
/// Basic usage:
///
/// Returns [`None`] if this `String` is empty.
///
- /// [`None`]: ../../std/option/enum.Option.html#variant.None
- ///
/// # Examples
///
/// Basic usage:
/// Panics if `idx` is larger than or equal to the `String`'s length,
/// or if it does not lie on a [`char`] boundary.
///
- /// [`char`]: ../../std/primitive.char.html
- ///
/// # Examples
///
/// Basic usage:
/// Panics if `idx` is larger than the `String`'s length, or if it does not
/// lie on a [`char`] boundary.
///
- /// [`char`]: ../../std/primitive.char.html
- ///
/// # Examples
///
/// Basic usage:
/// Panics if `idx` is larger than the `String`'s length, or if it does not
/// lie on a [`char`] boundary.
///
- /// [`char`]: ../../std/primitive.char.html
- ///
/// # Examples
///
/// Basic usage:
/// Panics if the starting point or end point do not lie on a [`char`]
/// boundary, or if they're out of bounds.
///
- /// [`char`]: ../../std/primitive.char.html
- ///
/// # Examples
///
/// Basic usage:
/// Panics if the starting point or end point do not lie on a [`char`]
/// boundary, or if they're out of bounds.
///
- /// [`char`]: ../../std/primitive.char.html
- /// [`Vec::splice`]: ../../std/vec/struct.Vec.html#method.splice
- ///
/// # Examples
///
/// Basic usage:
///
/// This will drop any excess capacity.
///
- /// [`Box`]: ../../std/boxed/struct.Box.html
- /// [`str`]: ../../std/primitive.str.html
- ///
/// # Examples
///
/// Basic usage:
/// an analogue to `FromUtf8Error`. See its documentation for more details
/// on using it.
///
- /// [`Utf8Error`]: ../../std/str/struct.Utf8Error.html
- /// [`std::str`]: ../../std/str/index.html
- /// [`u8`]: ../../std/primitive.u8.html
- /// [`&str`]: ../../std/primitive.str.html
+ /// [`std::str`]: core::str
+ /// [`&str`]: str
///
/// # Examples
///
}
}
+#[stable(feature = "box_str2", since = "1.45.0")]
+impl FromIterator<Box<str>> for String {
+ fn from_iter<I: IntoIterator<Item = Box<str>>>(iter: I) -> String {
+ let mut buf = String::new();
+ buf.extend(iter);
+ buf
+ }
+}
+
#[stable(feature = "herd_cows", since = "1.19.0")]
impl<'a> FromIterator<Cow<'a, str>> for String {
fn from_iter<I: IntoIterator<Item = Cow<'a, str>>>(iter: I) -> String {
}
}
+#[stable(feature = "box_str2", since = "1.45.0")]
+impl Extend<Box<str>> for String {
+ fn extend<I: IntoIterator<Item = Box<str>>>(&mut self, iter: I) {
+ iter.into_iter().for_each(move |s| self.push_str(&s));
+ }
+}
+
#[stable(feature = "extend_string", since = "1.4.0")]
impl Extend<String> for String {
fn extend<I: IntoIterator<Item = String>>(&mut self, iter: I) {
///
/// This alias exists for backwards compatibility, and may be eventually deprecated.
///
-/// [`Infallible`]: ../../core/convert/enum.Infallible.html
+/// [`Infallible`]: core::convert::Infallible
#[stable(feature = "str_parse_error", since = "1.5.0")]
pub type ParseError = core::convert::Infallible;
/// [`Display`] should be implemented instead, and you get the `ToString`
/// implementation for free.
///
-/// [`Display`]: ../../std/fmt/trait.Display.html
+/// [`Display`]: fmt::Display
#[stable(feature = "rust1", since = "1.0.0")]
pub trait ToString {
/// Converts the given value to a `String`.
/// This struct is created by the [`drain`] method on [`String`]. See its
/// documentation for more.
///
-/// [`drain`]: struct.String.html#method.drain
-/// [`String`]: struct.String.html
+/// [`drain`]: String::drain
#[stable(feature = "drain", since = "1.6.0")]
pub struct Drain<'a> {
/// Will be used as &'a mut String in the destructor
projects / rust.git / blobdiff