Introduce StringBuilder.appendLine in stdlib-common #KT-37839

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

@@ -158,6 +158,47 @@ public actual inline fun StringBuilder.insertRange(index: Int, value: CharSequen
     this.insert(index, value, startIndex, endIndex)
 
 
+/** Appends [value] to this [StringBuilder], followed by a line feed character (`\n`). */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun StringBuilder.appendLine(value: StringBuffer?): StringBuilder = append(value).appendLine()
+
+/** Appends [value] to this [StringBuilder], followed by a line feed character (`\n`). */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun StringBuilder.appendLine(value: StringBuilder?): StringBuilder = append(value).appendLine()
+
+/** Appends [value] to this [StringBuilder], followed by a line feed character (`\n`). */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun StringBuilder.appendLine(value: Int): StringBuilder = append(value).appendLine()
+
+/** Appends [value] to this [StringBuilder], followed by a line feed character (`\n`). */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun StringBuilder.appendLine(value: Short): StringBuilder = append(value.toInt()).appendLine()
+
+/** Appends [value] to this [StringBuilder], followed by a line feed character (`\n`). */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun StringBuilder.appendLine(value: Byte): StringBuilder = append(value.toInt()).appendLine()
+
+/** Appends [value] to this [StringBuilder], followed by a line feed character (`\n`). */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun StringBuilder.appendLine(value: Long): StringBuilder = append(value).appendLine()
+
+/** Appends [value] to this [StringBuilder], followed by a line feed character (`\n`). */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun StringBuilder.appendLine(value: Float): StringBuilder = append(value).appendLine()
+
+/** Appends [value] to this [StringBuilder], followed by a line feed character (`\n`). */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun StringBuilder.appendLine(value: Double): StringBuilder = append(value).appendLine()
+
+
 private object SystemProperties {
     /** Line separator for current system. */
     @JvmField
@@ -165,71 +206,177 @@ private object SystemProperties {
 }
 
 /** Appends a line separator to this Appendable. */
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine()"),
+    level = DeprecationLevel.WARNING
+)
 public fun Appendable.appendln(): Appendable = append(SystemProperties.LINE_SEPARATOR)
 
 /** Appends value to the given Appendable and line separator after it. */
+@Suppress("DEPRECATION")
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine(value)"),
+    level = DeprecationLevel.WARNING
+)
 @kotlin.internal.InlineOnly
 public inline fun Appendable.appendln(value: CharSequence?): Appendable = append(value).appendln()
 
 /** Appends value to the given Appendable and line separator after it. */
+@Suppress("DEPRECATION")
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine(value)"),
+    level = DeprecationLevel.WARNING
+)
 @kotlin.internal.InlineOnly
 public inline fun Appendable.appendln(value: Char): Appendable = append(value).appendln()
 
 /** Appends a line separator to this StringBuilder. */
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine()"),
+    level = DeprecationLevel.WARNING
+)
 public fun StringBuilder.appendln(): StringBuilder = append(SystemProperties.LINE_SEPARATOR)
 
 /** Appends [value] to this [StringBuilder], followed by a line separator. */
+@Suppress("DEPRECATION")
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine(value)"),
+    level = DeprecationLevel.WARNING
+)
 @kotlin.internal.InlineOnly
 public inline fun StringBuilder.appendln(value: StringBuffer?): StringBuilder = append(value).appendln()
 
 /** Appends [value] to this [StringBuilder], followed by a line separator. */
+@Suppress("DEPRECATION")
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine(value)"),
+    level = DeprecationLevel.WARNING
+)
 @kotlin.internal.InlineOnly
 public inline fun StringBuilder.appendln(value: CharSequence?): StringBuilder = append(value).appendln()
 
 /** Appends [value] to this [StringBuilder], followed by a line separator. */
+@Suppress("DEPRECATION")
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine(value)"),
+    level = DeprecationLevel.WARNING
+)
 @kotlin.internal.InlineOnly
 public inline fun StringBuilder.appendln(value: String?): StringBuilder = append(value).appendln()
 
 /** Appends [value] to this [StringBuilder], followed by a line separator. */
+@Suppress("DEPRECATION")
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine(value)"),
+    level = DeprecationLevel.WARNING
+)
 @kotlin.internal.InlineOnly
 public inline fun StringBuilder.appendln(value: Any?): StringBuilder = append(value).appendln()
 
 /** Appends [value] to this [StringBuilder], followed by a line separator. */
+@Suppress("DEPRECATION")
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine(value)"),
+    level = DeprecationLevel.WARNING
+)
 @kotlin.internal.InlineOnly
 public inline fun StringBuilder.appendln(value: StringBuilder?): StringBuilder = append(value).appendln()
 
 /** Appends [value] to this [StringBuilder], followed by a line separator. */
+@Suppress("DEPRECATION")
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine(value)"),
+    level = DeprecationLevel.WARNING
+)
 @kotlin.internal.InlineOnly
 public inline fun StringBuilder.appendln(value: CharArray): StringBuilder = append(value).appendln()
 
 /** Appends [value] to this [StringBuilder], followed by a line separator. */
+@Suppress("DEPRECATION")
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine(value)"),
+    level = DeprecationLevel.WARNING
+)
 @kotlin.internal.InlineOnly
 public inline fun StringBuilder.appendln(value: Char): StringBuilder = append(value).appendln()
 
 /** Appends [value] to this [StringBuilder], followed by a line separator. */
+@Suppress("DEPRECATION")
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine(value)"),
+    level = DeprecationLevel.WARNING
+)
 @kotlin.internal.InlineOnly
 public inline fun StringBuilder.appendln(value: Boolean): StringBuilder = append(value).appendln()
 
 /** Appends [value] to this [StringBuilder], followed by a line separator. */
+@Suppress("DEPRECATION")
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine(value)"),
+    level = DeprecationLevel.WARNING
+)
 @kotlin.internal.InlineOnly
 public inline fun StringBuilder.appendln(value: Int): StringBuilder = append(value).appendln()
 
 /** Appends [value] to this [StringBuilder], followed by a line separator. */
+@Suppress("DEPRECATION")
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine(value)"),
+    level = DeprecationLevel.WARNING
+)
 @kotlin.internal.InlineOnly
 public inline fun StringBuilder.appendln(value: Short): StringBuilder = append(value.toInt()).appendln()
 
 /** Appends [value] to this [StringBuilder], followed by a line separator. */
+@Suppress("DEPRECATION")
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine(value)"),
+    level = DeprecationLevel.WARNING
+)
 @kotlin.internal.InlineOnly
 public inline fun StringBuilder.appendln(value: Byte): StringBuilder = append(value.toInt()).appendln()
 
 /** Appends [value] to this [StringBuilder], followed by a line separator. */
+@Suppress("DEPRECATION")
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine(value)"),
+    level = DeprecationLevel.WARNING
+)
 @kotlin.internal.InlineOnly
 public inline fun StringBuilder.appendln(value: Long): StringBuilder = append(value).appendln()
 
 /** Appends [value] to this [StringBuilder], followed by a line separator. */
+@Suppress("DEPRECATION")
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine(value)"),
+    level = DeprecationLevel.WARNING
+)
 @kotlin.internal.InlineOnly
 public inline fun StringBuilder.appendln(value: Float): StringBuilder = append(value).appendln()
 
 /** Appends [value] to this [StringBuilder], followed by a line separator. */
+@Suppress("DEPRECATION")
+@Deprecated(
+    "Use appendLine instead. Note that the new method always appends the line feed character '\\n' regardless of the system line separator.",
+    ReplaceWith("appendLine(value)"),
+    level = DeprecationLevel.WARNING
+)
 @kotlin.internal.InlineOnly
 public inline fun StringBuilder.appendln(value: Double): StringBuilder = append(value).appendln()

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

@@ -65,6 +65,21 @@ public fun <T : Appendable> T.append(vararg value: CharSequence?): T {
     return this
 }
 
+/** Appends a line feed character (`\n`) to this Appendable. */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun Appendable.appendLine(): Appendable = append('\n')
+
+/** Appends value to the given Appendable and a line feed character (`\n`) after it. */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun Appendable.appendLine(value: CharSequence?): Appendable = append(value).appendLine()
+
+/** Appends value to the given Appendable and a line feed character (`\n`) after it. */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun Appendable.appendLine(value: Char): Appendable = append(value).appendLine()
+
 
 internal fun <T> Appendable.appendElement(element: T, transform: ((T) -> CharSequence)?) {
     when {

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

@@ -428,3 +428,39 @@ public fun StringBuilder.append(vararg value: Any?): StringBuilder {
         append(item)
     return this
 }
+
+/** Appends a line feed character (`\n`) to this StringBuilder. */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun StringBuilder.appendLine(): StringBuilder = append('\n')
+
+/** Appends [value] to this [StringBuilder], followed by a line feed character (`\n`). */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun StringBuilder.appendLine(value: CharSequence?): StringBuilder = append(value).appendLine()
+
+/** Appends [value] to this [StringBuilder], followed by a line feed character (`\n`). */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun StringBuilder.appendLine(value: String?): StringBuilder = append(value).appendLine()
+
+/** Appends [value] to this [StringBuilder], followed by a line feed character (`\n`). */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun StringBuilder.appendLine(value: Any?): StringBuilder = append(value).appendLine()
+
+/** Appends [value] to this [StringBuilder], followed by a line feed character (`\n`). */
+@OptIn(ExperimentalStdlibApi::class)
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun StringBuilder.appendLine(value: CharArray): StringBuilder = append(value).appendLine()
+
+/** Appends [value] to this [StringBuilder], followed by a line feed character (`\n`). */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun StringBuilder.appendLine(value: Char): StringBuilder = append(value).appendLine()
+
+/** Appends [value] to this [StringBuilder], followed by a line feed character (`\n`). */
+@SinceKotlin("1.4")
+@kotlin.internal.InlineOnly
+public inline fun StringBuilder.appendLine(value: Boolean): StringBuilder = append(value).appendLine()

libraries/stdlib/test/text/StringBuilderTest.kt

@@ -484,4 +484,36 @@ class StringBuilderTest {
             assertFails { sb.toCharArray(chars, 0, 0, sb.length + 1) }
         }
     }
+
+    @Test
+    fun appendLine() {
+        val stringBuilder = StringBuilder()
+        stringBuilder.appendLine('c')
+        stringBuilder.appendLine("string")
+        stringBuilder.appendLine(true)
+        stringBuilder.appendLine(charArrayOf('a', 'r', 'r', 'a', 'y'))
+        stringBuilder.appendLine()
+        stringBuilder.appendLine("char sequence" as CharSequence)
+        stringBuilder.appendLine(null as Any?)
+        stringBuilder.appendLine("nonnull" as Any?)
+        stringBuilder.appendLine(null as String?)
+        stringBuilder.appendLine(null as CharSequence?)
+
+        val expected =
+            """
+            c
+            string
+            true
+            array
+            
+            char sequence
+            null
+            nonnull
+            null
+            null
+            
+            """.trimIndent()
+
+        assertEquals(expected, stringBuilder.toString())
+    }
 }