KT-20357 Add sample code for Char extensions

libraries/stdlib/jvm/src/kotlin/text/CharJVM.kt

@@ -18,18 +18,21 @@ public inline fun Char.isDefined(): Boolean = Character.isDefined(this)
 
 /**
  * Returns `true` if this character is a letter.
+ * @sample samples.text.Chars.isLetter
  */
 @kotlin.internal.InlineOnly
 public inline fun Char.isLetter(): Boolean = Character.isLetter(this)
 
 /**
  * Returns `true` if this character is a letter or digit.
+ * @sample samples.text.Chars.isLetterOrDigit
  */
 @kotlin.internal.InlineOnly
 public inline fun Char.isLetterOrDigit(): Boolean = Character.isLetterOrDigit(this)
 
 /**
  * Returns `true` if this character (Unicode code point) is a digit.
+ * @sample samples.text.Chars.isDigit
  */
 @kotlin.internal.InlineOnly
 public inline fun Char.isDigit(): Boolean = Character.isDigit(this)
@@ -44,18 +47,21 @@ public inline fun Char.isIdentifierIgnorable(): Boolean = Character.isIdentifier
 
 /**
  * Returns `true` if this character is an ISO control character.
+ * @sample samples.text.Chars.isISOControl
  */
 @kotlin.internal.InlineOnly
 public inline fun Char.isISOControl(): Boolean = Character.isISOControl(this)
 
 /**
  * Returns `true` if this  character (Unicode code point) may be part of a Java identifier as other than the first character.
+ * @sample samples.text.Chars.isJavaIdentifierPart
  */
 @kotlin.internal.InlineOnly
 public inline fun Char.isJavaIdentifierPart(): Boolean = Character.isJavaIdentifierPart(this)
 
 /**
  * Returns `true` if this character is permissible as the first character in a Java identifier.
+ * @sample samples.text.Chars.isJavaIdentifierStart
  */
 @kotlin.internal.InlineOnly
 public inline fun Char.isJavaIdentifierStart(): Boolean = Character.isJavaIdentifierStart(this)
@@ -63,35 +69,41 @@ public inline fun Char.isJavaIdentifierStart(): Boolean = Character.isJavaIdenti
 /**
  * Determines whether a character is whitespace according to the Unicode standard.
  * Returns `true` if the character is whitespace.
+ * @sample samples.text.Chars.isWhitespace
  */
 public actual fun Char.isWhitespace(): Boolean = Character.isWhitespace(this) || Character.isSpaceChar(this)
 
 /**
  * Returns `true` if this character is upper case.
+ * @sample samples.text.Chars.isUpperCase
  */
 @kotlin.internal.InlineOnly
 public inline fun Char.isUpperCase(): Boolean = Character.isUpperCase(this)
 
 /**
  * Returns `true` if this character is lower case.
+ * @sample samples.text.Chars.isLowerCase
  */
 @kotlin.internal.InlineOnly
 public inline fun Char.isLowerCase(): Boolean = Character.isLowerCase(this)
 
 /**
  * Converts this character to uppercase.
+ * @sample samples.text.Chars.toUpperCase
  */
 @kotlin.internal.InlineOnly
 public actual inline fun Char.toUpperCase(): Char = Character.toUpperCase(this)
 
 /**
  * Converts this character to lowercase.
+ * @sample samples.text.Chars.toLowerCase
  */
 @kotlin.internal.InlineOnly
 public actual inline fun Char.toLowerCase(): Char = Character.toLowerCase(this)
 
 /**
  * Returns `true` if this character is a titlecase character.
+ * @sample samples.text.Chars.isTitleCase
  */
 @kotlin.internal.InlineOnly
 public inline fun Char.isTitleCase(): Boolean = Character.isTitleCase(this)
@@ -100,6 +112,7 @@ public inline fun Char.isTitleCase(): Boolean = Character.isTitleCase(this)
  * Converts this character to titlecase.
  *
  * @see Character.toTitleCase
+ * @sample samples.text.Chars.toTitleCase
  */
 @kotlin.internal.InlineOnly
 public inline fun Char.toTitleCase(): Char = Character.toTitleCase(this)

libraries/stdlib/samples/test/samples/text/char.kt

@@ -0,0 +1,127 @@
+package samples.text
+
+import samples.*
+import kotlin.test.*
+import java.util.*
+
+class Chars {
+
+    @Sample
+    fun isLetter() {
+        val chars = listOf('a', 'β', '+', '1')
+        val (letters, notLetters) = chars.partition { it.isLetter() }
+        assertPrints(letters, "[a, β]")
+        assertPrints(notLetters, "[+, 1]")
+    }
+
+    @Sample
+    fun isLetterOrDigit() {
+        val chars = listOf('a', '1', '+')
+        val (letterOrDigitList, notLetterOrDigitList) = chars.partition { it.isLetterOrDigit() }
+        assertPrints(letterOrDigitList, "[a, 1]")
+        assertPrints(notLetterOrDigitList, "[+]")
+    }
+
+    @Sample
+    fun isDigit() {
+        val chars = listOf('a', '+', '1')
+        val (digits, notDigits) = chars.partition { it.isDigit() }
+        assertPrints(digits, "[1]")
+        assertPrints(notDigits, "[a, +]")
+    }
+
+    @Sample
+    fun isISOControl() {
+        val chars = listOf('\u0000', '\u000E', '\u0009', '1', 'a')
+        val (isoControls, notIsoControls) = chars.partition { it.isISOControl() }
+        // some ISO-control char codes
+        assertPrints(isoControls.map(Char::toInt), "[0, 14, 9]")
+        // non-ISO-control chars
+        assertPrints(notIsoControls, "[1, a]")
+    }
+
+    @Sample
+    fun isJavaIdentifierPart() {
+        val chars = listOf('a', '_', '1', 'β', '$', '+', ';')
+        val (javaIdentifierParts, notJavaIdentifierParts) = chars.partition { it.isJavaIdentifierPart() }
+        assertPrints(javaIdentifierParts, "[a, _, 1, β, $]")
+        assertPrints(notJavaIdentifierParts, "[+, ;]")
+    }
+
+    @Sample
+    fun isJavaIdentifierStart() {
+        val chars = listOf('a', '_', 'β', '$', '1', '+', ';')
+        val (javaIdentifierStarts, notJavaIdentifierStarts) = chars.partition { it.isJavaIdentifierStart() }
+        assertPrints(javaIdentifierStarts, "[a, _, β, $]")
+        assertPrints(notJavaIdentifierStarts, "[1, +, ;]")
+    }
+
+    @Sample
+    fun isWhitespace() {
+        val chars = listOf(' ', '\t', '\n', '1', 'a', '\u00A0')
+        val (whitespaces, notWhitespaces) = chars.partition { it.isWhitespace() }
+        // whitespace char codes
+        assertPrints(whitespaces.map(Char::toInt), "[32, 9, 10, 160]")
+        // non-whitespace chars
+        assertPrints(notWhitespaces, "[1, a]")
+    }
+
+    @Sample
+    fun isUpperCase() {
+        val chars = listOf('A', 'Ψ', 'a', '1', '+')
+        val (upperCases, notUpperCases) = chars.partition { it.isUpperCase() }
+        assertPrints(upperCases, "[A, Ψ]")
+        assertPrints(notUpperCases, "[a, 1, +]")
+    }
+
+    @Sample
+    fun isLowerCase() {
+        val chars = listOf('a', 'λ', 'A', '1', '+')
+        val (lowerCases, notLowerCases) = chars.partition { it.isLowerCase() }
+        assertPrints(lowerCases, "[a, λ]")
+        assertPrints(notLowerCases, "[A, 1, +]")
+    }
+
+    @Sample
+    fun toUpperCase() {
+        val chars = listOf('a', 'ω', '1', 'A', '+')
+        val upperCases = chars.map { it.toUpperCase() }
+        assertPrints(upperCases, "[A, Ω, 1, A, +]")
+    }
+
+    @Sample
+    fun toLowerCase() {
+        val chars = listOf('A', 'Ω', '1', 'a', '+')
+        val lowerCases = chars.map { it.toLowerCase() }
+        assertPrints(lowerCases, "[a, ω, 1, a, +]")
+    }
+
+    @Sample
+    fun isTitleCase() {
+        val chars = listOf('Dž', 'Lj', 'Nj', 'Dz', '1', 'A', 'a', '+')
+        val (titleCases, notTitleCases) = chars.partition { it.isTitleCase() }
+        assertPrints(titleCases, "[Dž, Lj, Nj, Dz]")
+        assertPrints(notTitleCases, "[1, A, a, +]")
+    }
+
+    @Sample
+    fun toTitleCase() {
+        val chars = listOf('a', 'Dž', '1', '+')
+        val titleCases = chars.map { it.toTitleCase() }
+        assertPrints(titleCases, "[A, Dž, 1, +]")
+    }
+
+    @Sample
+    fun plus() {
+        val value = 'a' + "bcd"
+        assertPrints(value, "abcd")
+    }
+
+    @Sample
+    fun equals() {
+        assertTrue('a'.equals('a', false))
+        assertFalse('a'.equals('A', false))
+        assertTrue('a'.equals('A', true))
+    }
+
+}

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

@@ -10,6 +10,8 @@ package kotlin.text
 
 /**
  * Concatenates this Char and a String.
+ *
+ * @sample samples.text.Chars.plus
  */
 @kotlin.internal.InlineOnly
 public inline operator fun Char.plus(other: String): String = this.toString() + other
@@ -23,6 +25,8 @@ public inline operator fun Char.plus(other: String): String = this.toString() +
  *   - 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
+ *
+ * @sample samples.text.Chars.equals
  */
 public fun Char.equals(other: Char, ignoreCase: Boolean = false): Boolean {
     if (this == other) return true