use core::hash;
use core::iter::FromIterator;
use core::mem;
-use core::ops::{self, Add};
+use core::ops::{self, Add, Index, IndexMut};
use core::ptr;
use core::slice;
use core::str::pattern::Pattern;
use rustc_unicode::char::{decode_utf16, REPLACEMENT_CHARACTER};
use rustc_unicode::str as unicode_str;
-#[allow(deprecated)]
-use borrow::{Cow, IntoCow};
+use borrow::Cow;
use range::RangeArgument;
use str::{self, FromStr, Utf8Error, Chars};
use vec::Vec;
/// contents of the string. It has a close relationship with its borrowed
/// counterpart, the primitive [`str`].
///
-/// [`str`]: ../primitive.str.html
+/// [`str`]: ../../std/primitive.str.html
///
/// # Examples
///
/// hello.push_str("orld!");
/// ```
///
-/// [`char`]: ../primitive.char.html
+/// [`char`]: ../../std/primitive.char.html
/// [`push()`]: #method.push
/// [`push_str()`]: #method.push_str
///
/// println!("The first letter of s is {}", s[0]); // ERROR!!!
/// ```
///
-/// [`OsString`]: ../ffi/struct.OsString.html
+/// [`OsString`]: ../../std/ffi/struct.OsString.html
///
/// Indexing is intended to be a constant-time operation, but UTF-8 encoding
/// does not allow us to do this. Furtheremore, it's not clear what sort of
/// takes_str(&s);
/// ```
///
-/// [`&str`]: ../primitive.str.html
-/// [`Deref`]: ../ops/trait.Deref.html
+/// [`&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
/// mem::forget(story);
///
/// // We can re-build a String out of ptr, len, and capacity. This is all
-/// // unsafe becuase we are responsible for making sure the components are
+/// // unsafe because we are responsible for making sure the components are
/// // valid:
/// let s = unsafe { String::from_raw_parts(ptr as *mut _, len, capacity) } ;
///
/// an analogue to `FromUtf8Error`, and you can get one from a `FromUtf8Error`
/// through the [`utf8_error()`] method.
///
-/// [`Utf8Error`]: ../str/struct.Utf8Error.html
-/// [`std::str`]: ../str/index.html
-/// [`u8`]: ../primitive.u8.html
-/// [`&str`]: ../primitive.str.html
+/// [`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
///
/// # Examples
/// 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`]: ../primitive.str.html
- /// [`u8`]: ../primitive.u8.html
- /// [`Vec<u8>`]: ../vec/struct.Vec.html
+ /// [`&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
/// If you need a `&str` instead of a `String`, consider
/// [`str::from_utf8()`].
///
- /// [`str::from_utf8()`]: ../str/fn.from_utf8.html
+ /// [`str::from_utf8()`]: ../../std/str/fn.from_utf8.html
///
/// # Errors
///
}
}
- /// Converts a slice of bytes to a `String`, including invalid characters.
+ /// Converts a slice of bytes to a string, including invalid characters.
///
- /// A string slice ([`&str`]) is made of bytes ([`u8`]), and a slice of
- /// bytes ([`&[u8]`][byteslice]) is made of bytes, so this function converts between
- /// the two. Not all byte slices are valid string slices, however: [`&str`]
- /// requires that it is valid UTF-8. During this conversion,
+ /// Strings are made of bytes ([`u8`]), and a slice of bytes
+ /// ([`&[u8]`][byteslice]) is made of bytes, so this function converts
+ /// between the two. Not all byte slices are valid strings, however: strings
+ /// are required to be valid UTF-8. During this conversion,
/// `from_utf8_lossy()` will replace any invalid UTF-8 sequences with
/// `U+FFFD REPLACEMENT CHARACTER`, which looks like this: �
///
- /// [`&str`]: ../primitive.str.html
- /// [`u8`]: ../primitive.u8.html
- /// [byteslice]: ../primitive.slice.html
+ /// [`u8`]: ../../std/primitive.u8.html
+ /// [byteslice]: ../../std/primitive.slice.html
///
/// 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
///
/// [`from_utf8_unchecked()`]: struct.String.html#method.from_utf8_unchecked
///
- /// If you need a [`&str`] instead of a `String`, consider
- /// [`str::from_utf8()`].
+ /// 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
+ /// change the size of the string, and hence, require a `String`. But if
+ /// it's already valid UTF-8, we don't need a new allocation. This return
+ /// type allows us to handle both cases.
///
- /// [`str::from_utf8()`]: ../str/fn.from_utf8.html
+ /// [`Cow<'a, str>`]: ../../std/borrow/enum.Cow.html
///
/// # Examples
///
/// // some bytes, in a vector
/// let sparkle_heart = vec![240, 159, 146, 150];
///
- /// // We know these bytes are valid, so we'll use `unwrap()`.
- /// let sparkle_heart = String::from_utf8(sparkle_heart).unwrap();
+ /// let sparkle_heart = String::from_utf8_lossy(&sparkle_heart);
///
/// assert_eq!("💖", sparkle_heart);
/// ```
/// Panics if `new_len` > current length, or if `new_len` does not lie on a
/// [`char`] boundary.
///
- /// [`char`]: ../primitive.char.html
+ /// [`char`]: ../../std/primitive.char.html
///
/// # Examples
///
/// Panics if `idx` is larger than or equal to the `String`'s length,
/// or if it does not lie on a [`char`] boundary.
///
- /// [`char`]: ../primitive.char.html
+ /// [`char`]: ../../std/primitive.char.html
///
/// # Examples
///
/// Panics if `idx` is larger than the `String`'s length, or if it does not
/// lie on a [`char`] boundary.
///
- /// [`char`]: ../primitive.char.html
+ /// [`char`]: ../../std/primitive.char.html
///
/// # Examples
///
/// Panics if the starting point or end point do not lie on a [`char`]
/// boundary, or if they're out of bounds.
///
- /// [`char`]: ../primitive.char.html
+ /// [`char`]: ../../std/primitive.char.html
///
/// # Examples
///
/// an analogue to `FromUtf8Error`. See its documentation for more details
/// on using it.
///
- /// [`Utf8Error`]: ../str/struct.Utf8Error.html
- /// [`std::str`]: ../str/index.html
- /// [`u8`]: ../primitive.u8.html
- /// [`&str`]: ../primitive.str.html
+ /// [`Utf8Error`]: ../../std/str/struct.Utf8Error.html
+ /// [`std::str`]: ../../std/str/index.html
+ /// [`u8`]: ../../std/primitive.u8.html
+ /// [`&str`]: ../../std/primitive.str.html
///
/// # Examples
///
unsafe { str::from_utf8_unchecked(&self.vec) }
}
}
+#[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")]
+impl ops::Index<ops::RangeInclusive<usize>> for String {
+ type Output = str;
+
+ #[inline]
+ fn index(&self, index: ops::RangeInclusive<usize>) -> &str {
+ Index::index(&**self, index)
+ }
+}
+#[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")]
+impl ops::Index<ops::RangeToInclusive<usize>> for String {
+ type Output = str;
+
+ #[inline]
+ fn index(&self, index: ops::RangeToInclusive<usize>) -> &str {
+ Index::index(&**self, index)
+ }
+}
#[stable(feature = "derefmut_for_string", since = "1.2.0")]
impl ops::IndexMut<ops::Range<usize>> for String {
unsafe { mem::transmute(&mut *self.vec) }
}
}
+#[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")]
+impl ops::IndexMut<ops::RangeInclusive<usize>> for String {
+ #[inline]
+ fn index_mut(&mut self, index: ops::RangeInclusive<usize>) -> &mut str {
+ IndexMut::index_mut(&mut **self, index)
+ }
+}
+#[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")]
+impl ops::IndexMut<ops::RangeToInclusive<usize>> for String {
+ #[inline]
+ fn index_mut(&mut self, index: ops::RangeToInclusive<usize>) -> &mut str {
+ IndexMut::index_mut(&mut **self, index)
+ }
+}
#[stable(feature = "rust1", since = "1.0.0")]
impl ops::Deref for String {
/// [`String`] without error, this type will never actually be returned. As
/// such, it is only here to satisfy said signature, and is useless otherwise.
///
-/// [`FromStr`]: ../str/trait.FromStr.html
+/// [`FromStr`]: ../../std/str/trait.FromStr.html
/// [`String`]: struct.String.html
-/// [`from_str()`]: ../str/trait.FromStr.html#tymethod.from_str
+/// [`from_str()`]: ../../std/str/trait.FromStr.html#tymethod.from_str
#[stable(feature = "str_parse_error", since = "1.5.0")]
#[derive(Copy)]
pub enum ParseError {}
/// [`Display`] should be implemented instead, and you get the `ToString`
/// implementation for free.
///
-/// [`Display`]: ../fmt/trait.Display.html
+/// [`Display`]: ../../std/fmt/trait.Display.html
#[stable(feature = "rust1", since = "1.0.0")]
pub trait ToString {
/// Converts the given value to a `String`.
}
}
-#[unstable(feature = "into_cow", reason = "may be replaced by `convert::Into`",
- issue= "27735")]
-#[allow(deprecated)]
-impl IntoCow<'static, str> for String {
- #[inline]
- fn into_cow(self) -> Cow<'static, str> {
- Cow::Owned(self)
- }
-}
-
-#[unstable(feature = "into_cow", reason = "may be replaced by `convert::Into`",
- issue = "27735")]
-#[allow(deprecated)]
-impl<'a> IntoCow<'a, str> for &'a str {
- #[inline]
- fn into_cow(self) -> Cow<'a, str> {
- Cow::Borrowed(self)
- }
-}
-
#[stable(feature = "rust1", since = "1.0.0")]
impl fmt::Write for String {
#[inline]
}
/// A draining iterator for `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
#[stable(feature = "drain", since = "1.6.0")]
pub struct Drain<'a> {
/// Will be used as &'a mut String in the destructor