Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document From impls in string.rs #85715

Merged
merged 1 commit into from
Jun 9, 2021
Merged

Document From impls in string.rs #85715

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 43 additions & 7 deletions library/alloc/src/string.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2438,6 +2438,9 @@ impl AsRef<[u8]> for String {
#[cfg(not(no_global_oom_handling))]
#[stable(feature = "rust1", since = "1.0.0")]
impl From<&str> for String {
/// Converts a `&str` into a [`String`].
///
/// The result is allocated on the heap.
#[inline]
fn from(s: &str) -> String {
s.to_owned()
Expand All @@ -2447,7 +2450,7 @@ impl From<&str> for String {
#[cfg(not(no_global_oom_handling))]
#[stable(feature = "from_mut_str_for_string", since = "1.44.0")]
impl From<&mut str> for String {
/// Converts a `&mut str` into a `String`.
/// Converts a `&mut str` into a [`String`].
///
/// The result is allocated on the heap.
#[inline]
Expand All @@ -2459,6 +2462,9 @@ impl From<&mut str> for String {
#[cfg(not(no_global_oom_handling))]
#[stable(feature = "from_ref_string", since = "1.35.0")]
impl From<&String> for String {
/// Converts a `&String` into a [`String`].
///
/// This clones `s` and returns the clone.
#[inline]
fn from(s: &String) -> String {
s.clone()
Expand All @@ -2469,7 +2475,7 @@ impl From<&String> for String {
#[cfg(not(test))]
#[stable(feature = "string_from_box", since = "1.18.0")]
impl From<Box<str>> for String {
/// Converts the given boxed `str` slice to a `String`.
/// Converts the given boxed `str` slice to a [`String`].
/// It is notable that the `str` slice is owned.
///
/// # Examples
Expand All @@ -2491,7 +2497,7 @@ impl From<Box<str>> for String {
#[cfg(not(no_global_oom_handling))]
#[stable(feature = "box_from_str", since = "1.20.0")]
impl From<String> for Box<str> {
/// Converts the given `String` to a boxed `str` slice that is owned.
/// Converts the given [`String`] to a boxed `str` slice that is owned.
///
/// # Examples
///
Expand All @@ -2512,6 +2518,22 @@ impl From<String> for Box<str> {
#[cfg(not(no_global_oom_handling))]
#[stable(feature = "string_from_cow_str", since = "1.14.0")]
impl<'a> From<Cow<'a, str>> for String {
/// Converts a clone-on-write string to an owned
/// instance of [`String`].
///
/// This extracts the owned string,
/// clones the string if it is not already owned.
///
/// # Example
fee1-dead marked this conversation as resolved.
Show resolved Hide resolved
///
/// ```
/// # use std::borrow::Cow;
/// // If the string is not owned...
/// let cow: Cow<str> = Cow::Borrowed("eggplant");
/// // It will allocate on the heap and copy the string.
/// let owned: String = String::from(cow);
/// assert_eq!(&owned[..], "eggplant");
/// ```
fn from(s: Cow<'a, str>) -> String {
s.into_owned()
}
Expand All @@ -2520,7 +2542,7 @@ impl<'a> From<Cow<'a, str>> for String {
#[cfg(not(no_global_oom_handling))]
#[stable(feature = "rust1", since = "1.0.0")]
impl<'a> From<&'a str> for Cow<'a, str> {
/// Converts a string slice into a Borrowed variant.
/// Converts a string slice into a [`Borrowed`] variant.
/// No heap allocation is performed, and the string
/// is not copied.
///
Expand All @@ -2530,6 +2552,8 @@ impl<'a> From<&'a str> for Cow<'a, str> {
/// # use std::borrow::Cow;
/// assert_eq!(Cow::from("eggplant"), Cow::Borrowed("eggplant"));
/// ```
///
/// [`Borrowed`]: crate::borrow::Cow::Borrowed
#[inline]
fn from(s: &'a str) -> Cow<'a, str> {
Cow::Borrowed(s)
Expand All @@ -2539,7 +2563,7 @@ impl<'a> From<&'a str> for Cow<'a, str> {
#[cfg(not(no_global_oom_handling))]
#[stable(feature = "rust1", since = "1.0.0")]
impl<'a> From<String> for Cow<'a, str> {
/// Converts a String into an Owned variant.
/// Converts a [`String`] into an [`Owned`] variant.
/// No heap allocation is performed, and the string
/// is not copied.
///
Expand All @@ -2551,6 +2575,8 @@ impl<'a> From<String> for Cow<'a, str> {
/// let s2 = "eggplant".to_string();
/// assert_eq!(Cow::from(s), Cow::<'static, str>::Owned(s2));
/// ```
///
/// [`Owned`]: crate::borrow::Cow::Owned
#[inline]
fn from(s: String) -> Cow<'a, str> {
Cow::Owned(s)
Expand All @@ -2560,7 +2586,7 @@ impl<'a> From<String> for Cow<'a, str> {
#[cfg(not(no_global_oom_handling))]
#[stable(feature = "cow_from_string_ref", since = "1.28.0")]
impl<'a> From<&'a String> for Cow<'a, str> {
/// Converts a String reference into a Borrowed variant.
/// Converts a [`String`] reference into a [`Borrowed`] variant.
/// No heap allocation is performed, and the string
/// is not copied.
///
Expand All @@ -2571,6 +2597,8 @@ impl<'a> From<&'a String> for Cow<'a, str> {
/// let s = "eggplant".to_string();
/// assert_eq!(Cow::from(&s), Cow::Borrowed("eggplant"));
/// ```
///
/// [`Borrowed`]: crate::borrow::Cow::Borrowed
#[inline]
fn from(s: &'a String) -> Cow<'a, str> {
Cow::Borrowed(s.as_str())
Expand Down Expand Up @@ -2603,7 +2631,7 @@ impl<'a> FromIterator<String> for Cow<'a, str> {

#[stable(feature = "from_string_for_vec_u8", since = "1.14.0")]
impl From<String> for Vec<u8> {
/// Converts the given `String` to a vector `Vec` that holds values of type `u8`.
/// Converts the given [`String`] to a vector [`Vec`] that holds values of type [`u8`].
///
/// # Examples
///
Expand Down Expand Up @@ -2749,6 +2777,14 @@ impl FusedIterator for Drain<'_> {}
#[cfg(not(no_global_oom_handling))]
#[stable(feature = "from_char_for_string", since = "1.46.0")]
impl From<char> for String {
/// Allocates an owned [`String`] from a single character.
///
/// # Example
fee1-dead marked this conversation as resolved.
Show resolved Hide resolved
/// ```rust
/// let c: char = 'a';
/// let s: String = String::from(c);
/// assert_eq!("a", &s[..]);
/// ```
#[inline]
fn from(c: char) -> Self {
c.to_string()
Expand Down