library: mark more functions that return String as #[must_use]

If the return value (String) of the function is not used, the function call is technically in vain
(unless there are side effects) and the entire function call could be ommitted.

Warn about unused return values of -> String functions.

Example code:

   let mut x = Sting::from("hello");
   x.push_str(" world!");
   x.to_uppercase();
   println!("{}", x);

will print "hello world!" instead of "HELLO WORLD!") because the result of .to_uppercase() is not caught
in a variable.

std::str::to_lowercase()
std::str::to_uppercase()
std::str::escape_debug()
std::str::escape_default()
std::str::escape_unicode()
std::str::into_string()
std::str::repeat()
std::str::to_ascii_uppercase()
std::str::to_ascii_lowercase()

std::String::with_capacity()
std::String::from_str()
std::String::from_utf16_lossy()
std::String::from_raw_parts()
std::String::from_utf8_unchecked()
std::String::split_off()

src/liballoc/str.rs

@@ -305,6 +305,7 @@ impl str {
     ///
     /// assert_eq!(new_year, new_year.to_lowercase());
     /// ```
+    #[must_use]
     #[stable(feature = "unicode_case_mapping", since = "1.2.0")]
     pub fn to_lowercase(&self) -> String {
         let mut s = String::with_capacity(self.len());
@@ -368,6 +369,7 @@ impl str {
     ///
     /// assert_eq!(new_year, new_year.to_uppercase());
     /// ```
+    #[must_use]
     #[stable(feature = "unicode_case_mapping", since = "1.2.0")]
     pub fn to_uppercase(&self) -> String {
         let mut s = String::with_capacity(self.len());
@@ -378,6 +380,7 @@ impl str {
     /// Escapes each char in `s` with [`char::escape_debug`].
     ///
     /// [`char::escape_debug`]: primitive.char.html#method.escape_debug
+    #[must_use]
     #[unstable(feature = "str_escape",
                reason = "return type may change to be an iterator",
                issue = "27791")]
@@ -388,6 +391,7 @@ impl str {
     /// Escapes each char in `s` with [`char::escape_default`].
     ///
     /// [`char::escape_default`]: primitive.char.html#method.escape_default
+    #[must_use]
     #[unstable(feature = "str_escape",
                reason = "return type may change to be an iterator",
                issue = "27791")]
@@ -398,6 +402,7 @@ impl str {
     /// Escapes each char in `s` with [`char::escape_unicode`].
     ///
     /// [`char::escape_unicode`]: primitive.char.html#method.escape_unicode
+    #[must_use]
     #[unstable(feature = "str_escape",
                reason = "return type may change to be an iterator",
                issue = "27791")]
@@ -420,6 +425,7 @@ impl str {
     ///
     /// assert_eq!(boxed_str.into_string(), string);
     /// ```
+    #[must_use]
     #[stable(feature = "box_str", since = "1.4.0")]
     #[inline]
     pub fn into_string(self: Box<str>) -> String {
@@ -438,6 +444,7 @@ impl str {
     /// ```
     /// assert_eq!("abc".repeat(4), String::from("abcabcabcabc"));
     /// ```
+    #[must_use]
     #[stable(feature = "repeat_str", since = "1.16.0")]
     pub fn repeat(&self, n: usize) -> String {
         unsafe { String::from_utf8_unchecked(self.as_bytes().repeat(n)) }
@@ -464,6 +471,7 @@ impl str {
     ///
     /// [`make_ascii_uppercase`]: #method.make_ascii_uppercase
     /// [`to_uppercase`]: #method.to_uppercase
+    #[must_use]
     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
     #[inline]
     pub fn to_ascii_uppercase(&self) -> String {
@@ -494,6 +502,7 @@ impl str {
     ///
     /// [`make_ascii_lowercase`]: #method.make_ascii_lowercase
     /// [`to_lowercase`]: #method.to_lowercase
+    #[must_use]
     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
     #[inline]
     pub fn to_ascii_lowercase(&self) -> String {

src/liballoc/string.rs

@@ -422,6 +422,7 @@ impl String {
     /// // ...but this may make the vector reallocate
     /// s.push('a');
     /// ```
+    #[must_use]
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn with_capacity(capacity: usize) -> String {
@@ -432,6 +433,7 @@ impl String {
     // required for this method definition, is not available. Since we don't
     // require this method for testing purposes, I'll just stub it
     // NB see the slice::hack module in slice.rs for more information
+    #[must_use]
     #[inline]
     #[cfg(test)]
     pub fn from_str(_: &str) -> String {
@@ -643,6 +645,7 @@ impl String {
     /// assert_eq!(String::from("𝄞mus\u{FFFD}ic\u{FFFD}"),
     ///            String::from_utf16_lossy(v));
     /// ```
+    #[must_use]
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn from_utf16_lossy(v: &[u16]) -> String {
@@ -690,6 +693,7 @@ impl String {
     ///     assert_eq!(String::from("hello"), s);
     /// }
     /// ```
+    #[must_use]
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub unsafe fn from_raw_parts(buf: *mut u8, length: usize, capacity: usize) -> String {
@@ -724,6 +728,7 @@ impl String {
     ///
     /// assert_eq!("💖", sparkle_heart);
     /// ```
+    #[must_use]
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub unsafe fn from_utf8_unchecked(bytes: Vec<u8>) -> String {
@@ -1420,6 +1425,7 @@ impl String {
     /// assert_eq!(world, "World!");
     /// # }
     /// ```
+    #[must_use]
     #[inline]
     #[stable(feature = "string_split_off", since = "1.16.0")]
     pub fn split_off(&mut self, at: usize) -> String {

src/liballoc/tests/string.rs

@@ -244,14 +244,14 @@ fn test_split_off_empty() {
 fn test_split_off_past_end() {
     let orig = "Hello, world!";
     let mut split = String::from(orig);
-    split.split_off(orig.len() + 1);
+    let _ = split.split_off(orig.len() + 1);
 }
 
 #[test]
 #[should_panic]
 fn test_split_off_mid_char() {
     let mut orig = String::from("山");
-    orig.split_off(1);
+    let _ = orig.split_off(1);
 }
 
 #[test]