Locale-agnostic case conversions by default #KT-43023

libraries/stdlib/src/kotlin/text/Char.kt

@@ -8,6 +8,70 @@
 
 package kotlin.text
 
+/**
+ * Converts this character to lower case using Unicode mapping rules of the invariant locale.
+ */
+public expect fun Char.toLowerCase(): Char
+
+/**
+ * Converts this character to lower case using Unicode mapping rules of the invariant locale.
+ *
+ * This function performs one-to-one character mapping.
+ * To support one-to-many character mapping use the [lowercase] function.
+ * If this character has no mapping equivalent, the character itself is returned.
+ *
+ * @sample samples.text.Chars.lowercase
+ */
+@SinceKotlin("1.4")
+@ExperimentalStdlibApi
+public expect fun Char.lowercaseChar(): Char
+
+/**
+ * Converts this character to lower case using Unicode mapping rules of the invariant locale.
+ *
+ * This function supports one-to-many character mapping, thus the length of the returned string can be greater than one.
+ * For example, `'\u0130'.lowercase()` returns `"\u0069\u0307"`,
+ * where `'\u0130'` is the LATIN CAPITAL LETTER I WITH DOT ABOVE character (`İ`).
+ * If this character has no lower case mapping, the result of `toString()` of this char is returned.
+ *
+ * @sample samples.text.Chars.lowercase
+ */
+@SinceKotlin("1.4")
+@ExperimentalStdlibApi
+public expect fun Char.lowercase(): String
+
+/**
+ * Converts this character to upper case using Unicode mapping rules of the invariant locale.
+ */
+public expect fun Char.toUpperCase(): Char
+
+/**
+ * Converts this character to upper case using Unicode mapping rules of the invariant locale.
+ *
+ * This function performs one-to-one character mapping.
+ * To support one-to-many character mapping use the [uppercase] function.
+ * If this character has no mapping equivalent, the character itself is returned.
+ *
+ * @sample samples.text.Chars.uppercase
+ */
+@SinceKotlin("1.4")
+@ExperimentalStdlibApi
+public expect fun Char.uppercaseChar(): Char
+
+/**
+ * Converts this character to upper case using Unicode mapping rules of the invariant locale.
+ *
+ * This function supports one-to-many character mapping, thus the length of the returned string can be greater than one.
+ * For example, `'\uFB00'.uppercase()` returns `"\u0046\u0046"`,
+ * where `'\uFB00'` is the LATIN SMALL LIGATURE FF character (`ff`).
+ * If this character has no upper case mapping, the result of `toString()` of this char is returned.
+ *
+ * @sample samples.text.Chars.uppercase
+ */
+@SinceKotlin("1.4")
+@ExperimentalStdlibApi
+public expect fun Char.uppercase(): String
+
 /**
  * Concatenates this Char and a String.
  *
@@ -23,17 +87,18 @@ public inline operator fun Char.plus(other: String): String = this.toString() +
  *
  * Two characters are considered the same ignoring case if at least one of the following is `true`:
  *   - The two characters are the same (as compared by the == operator)
- *   - Applying the method [toUpperCase] to each character produces the same result
- *   - Applying the method [toLowerCase] to each character produces the same result
+ *   - Applying the method [uppercaseChar] to each character produces the same result
+ *   - Applying the method [lowercaseChar] to each character produces the same result
  *
  * @sample samples.text.Chars.equals
  */
+@OptIn(ExperimentalStdlibApi::class)
 public fun Char.equals(other: Char, ignoreCase: Boolean = false): Boolean {
     if (this == other) return true
     if (!ignoreCase) return false
 
-    if (this.toUpperCase() == other.toUpperCase()) return true
-    if (this.toLowerCase() == other.toLowerCase()) return true
+    if (this.uppercaseChar() == other.uppercaseChar()) return true
+    if (this.lowercaseChar() == other.lowercaseChar()) return true
     return false
 }
 

libraries/stdlib/src/kotlin/text/Strings.kt

@@ -9,6 +9,60 @@
 package kotlin.text
 
 import kotlin.contracts.contract
+import kotlin.jvm.JvmName
+
+/**
+ * Returns a copy of this string converted to upper case using the rules of the default locale.
+ */
+public expect fun String.toUpperCase(): String
+
+/**
+ * Returns a copy of this string converted to upper case using Unicode mapping rules of the invariant locale.
+ *
+ * This function supports one-to-many and many-to-one character mapping,
+ * thus the length of the returned string can be different from the length of the original string.
+ *
+ * @sample samples.text.Strings.uppercase
+ */
+@SinceKotlin("1.4")
+@ExperimentalStdlibApi
+public expect fun String.uppercase(): String
+
+/**
+ * Returns a copy of this string converted to lower case using the rules of the default locale.
+ */
+public expect fun String.toLowerCase(): String
+
+/**
+ * Returns a copy of this string converted to lower case using Unicode mapping rules of the invariant locale.
+ *
+ * This function supports one-to-many and many-to-one character mapping,
+ * thus the length of the returned string can be different from the length of the original string.
+ *
+ * @sample samples.text.Strings.lowercase
+ */
+@SinceKotlin("1.4")
+@ExperimentalStdlibApi
+public expect fun String.lowercase(): String
+
+/**
+ * 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
+ */
+public expect fun String.capitalize(): String
+
+/**
+ * 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 expect fun String.decapitalize(): String
 
 /**
  * Returns a sub sequence of this char sequence having leading and trailing characters matching the [predicate] removed.
@@ -710,6 +764,42 @@ public inline fun CharSequence.replace(regex: Regex, noinline transform: (MatchR
 @kotlin.internal.InlineOnly
 public inline fun CharSequence.replaceFirst(regex: Regex, replacement: String): String = regex.replaceFirst(this, replacement)
 
+/**
+ * Returns a copy of this string having its first character replaced with the result of the specified [transform],
+ * or the original string if it's empty.
+ *
+ * @param transform function that takes the first character and returns the result of the transform applied to the character.
+ *
+ * @sample samples.text.Strings.replaceFirstChar
+ */
+@SinceKotlin("1.4")
+@ExperimentalStdlibApi
+@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
+@OverloadResolutionByLambdaReturnType
+@JvmName("replaceFirstCharWithChar")
+@kotlin.internal.InlineOnly
+public inline fun String.replaceFirstChar(transform: (Char) -> Char): String {
+    return if (isNotEmpty()) transform(this[0]) + substring(1) else this
+}
+
+/**
+ * Returns a copy of this string having its first character replaced with the result of the specified [transform],
+ * or the original string if it's empty.
+ *
+ * @param transform function that takes the first character and returns the result of the transform applied to the character.
+ *
+ * @sample samples.text.Strings.replaceFirstChar
+ */
+@SinceKotlin("1.4")
+@ExperimentalStdlibApi
+@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
+@OverloadResolutionByLambdaReturnType
+@JvmName("replaceFirstCharWithCharSequence")
+@kotlin.internal.InlineOnly
+public inline fun String.replaceFirstChar(transform: (Char) -> CharSequence): String {
+    return if (isNotEmpty()) transform(this[0]).toString() + substring(1) else this
+}
+
 
 /**
  * Returns `true` if this char sequence matches the given regular expression.