From f3a2f90c88c9d890b67955f0b88def40ce372914 Mon Sep 17 00:00:00 2001
From: Tobias Bucher <tobiasbucher5991@gmail.com>
Date: Wed, 8 Mar 2017 00:06:09 +0100
Subject: [PATCH] Document why `str.to_{lower,upper}case` return `String`

Fixes #39201.
---
 src/libcollections/str.rs | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/libcollections/str.rs b/src/libcollections/str.rs
index 87315fff0a07d..e27c45773441a 100644
--- a/src/libcollections/str.rs
+++ b/src/libcollections/str.rs
@@ -1646,6 +1646,10 @@ impl str {
     /// 'Lowercase' is defined according to the terms of the Unicode Derived Core Property
     /// `Lowercase`.
     ///
+    /// Since some characters can expand into multiple characters when changing
+    /// the case, this function returns a [`String`] instead of modifying the
+    /// parameter in-place.
+    ///
     /// [`String`]: string/struct.String.html
     ///
     /// # Examples
@@ -1718,6 +1722,10 @@ impl str {
     /// 'Uppercase' is defined according to the terms of the Unicode Derived Core Property
     /// `Uppercase`.
     ///
+    /// Since some characters can expand into multiple characters when changing
+    /// the case, this function returns a [`String`] instead of modifying the
+    /// parameter in-place.
+    ///
     /// [`String`]: string/struct.String.html
     ///
     /// # Examples