From 6cb0175719b0fa96d4066a210ed5f3438b589b70 Mon Sep 17 00:00:00 2001
From: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>
Date: Thu, 25 Jun 2020 02:50:51 +0300
Subject: [PATCH] Sync docs and behavior of decapitalize and capitalize

(cherry picked from commit 5e2d58a967b254abd2569c2d5988f7f444765979)
---
 .../src/main/kotlin/kotlin/text/Strings.kt    | 27 ++++++++++---------
 1 file changed, 15 insertions(+), 12 deletions(-)

diff --git a/runtime/src/main/kotlin/kotlin/text/Strings.kt b/runtime/src/main/kotlin/kotlin/text/Strings.kt
index 40aa81c763c..744d5e35326 100644
--- a/runtime/src/main/kotlin/kotlin/text/Strings.kt
+++ b/runtime/src/main/kotlin/kotlin/text/Strings.kt
@@ -81,16 +81,6 @@ public actual fun String.replaceFirst(oldValue: String, newValue: String, ignore
     return if (index < 0) this else this.replaceRange(index, index + oldValue.length, newValue)
 }
 
-/**
- * Returns a copy of this string having its first letter lowercased, or the original string,
- * if it's empty or already starts with a lower case letter.
- *
- * @sample samples.text.Strings.decapitalize
- */
-public actual fun String.decapitalize(): String {
-    return if (isNotEmpty() && this[0].isUpperCase()) substring(0, 1).toLowerCase() + substring(1) else this
-}
-
 /**
  * Returns `true` if this string is empty or consists solely of whitespace characters.
  *
@@ -184,8 +174,11 @@ public actual fun String.toCharArray(): CharArray = toCharArray(this, 0, length)
 private external fun toCharArray(string: String, start: Int, size: Int): CharArray
 
 /**
- * Returns a copy of this string having its first letter uppercased, or the original string,
- * if it's empty or already starts with an upper case letter.
+ * Returns a copy of this string having its first letter titlecased using the rules of the default locale,
+ * or the original string if it's empty or already starts with a title case letter.
+ *
+ * The title case of a character is usually the same as its upper case with several exceptions.
+ * The particular list of characters with the special title case form depends on the underlying platform.
  *
  * @sample samples.text.Strings.capitalize
  */
@@ -193,6 +186,16 @@ public actual fun String.capitalize(): String {
     return if (isNotEmpty() && this[0].isLowerCase()) substring(0, 1).toUpperCase() + substring(1) else this
 }
 
+/**
+ * Returns a copy of this string having its first letter lowercased using the rules of the default locale,
+ * or the original string if it's empty or already starts with a lower case letter.
+ *
+ * @sample samples.text.Strings.decapitalize
+ */
+public actual fun String.decapitalize(): String {
+    return if (isNotEmpty() && !this[0].isLowerCase()) substring(0, 1).toLowerCase() + substring(1) else this
+}
+
 /**
  * Returns a string containing this char sequence repeated [n] times.
  * @throws [IllegalArgumentException] when n < 0.