mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix up docs for String::from_utf8_lossy()

Browse Source 
When I last did a pass through the string documentation, I focused on
consistency across similar functions. Unfortunately, I missed some
details. This example was _too_ consistent: it wasn't actually accurate!

This commit fixes the docs do both be more accurate and to explain why
the return type is a Cow<'a, str>.

First reported here:
https://www.reddit.com/r/rust/comments/44q9ms/stringfrom_utf8_lossy_doesnt_return_a_string/
This commit is contained in:
Steve Klabnik 2016-02-08 17:10:55 -05:00
parent efdde2479b
commit 5089b43b45
1 changed files with 12 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
src/libcollections/string.rs
View File

@ -479,16 +479,15 @@ impl String {
}
}
/// 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: <20>
///
/// [`&str`]: ../primitive.str.html
/// [`u8`]: ../primitive.u8.html
/// [byteslice]: ../primitive.slice.html
///
@ -499,10 +498,13 @@ impl String {
///
/// [`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>`]: ../borrow/enum.Cow.html
///
/// # Examples
///
@ -512,8 +514,7 @@ impl String {
/// // 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);
/// ```