Deprecate StringBuilder { } function, and introduce buildString { } instead.

#KT-7295 Fixed

libraries/stdlib/src/kotlin/dom/Dom.kt

@@ -170,13 +170,13 @@ public fun Element.addClass(vararg cssClasses: String): Boolean {
     val missingClasses = cssClasses.filterNot { hasClass(it) }
     if (missingClasses.isNotEmpty()) {
         val presentClasses = classes.trim()
-        classes = StringBuilder {
+        classes = buildString {
             append(presentClasses)
             if (!presentClasses.isEmpty()) {
                 append(" ")
             }
             missingClasses.joinTo(this, " ")
-        }.toString()
+        }
         return true
     }
 

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

@@ -6,14 +6,16 @@ package kotlin
 /**
  * Builds newly created StringBuilder using provided body.
  */
-public inline fun StringBuilder(body: StringBuilder.() -> Unit): StringBuilder {
-    val sb = StringBuilder()
-    sb.body()
-    return sb
-}
+@Deprecated("Use StringBuilder().apply { body } or use String.build { body } if you need String as a result.", ReplaceWith("StringBuilder().apply(body)"))
+public inline fun StringBuilder(body: StringBuilder.() -> Unit): StringBuilder = StringBuilder().apply(body)
 
 /**
- * Appends all arguments to the given Appendable.
+ * Builds new string by populating newly created [StringBuilder] using provided [builderAction] and then converting it to [String].
+ */
+public inline fun buildString(builderAction: StringBuilder.() -> Unit): String = StringBuilder().apply(builderAction).toString()
+
+/**
+ * Appends all arguments to the given [Appendable].
  */
 public fun <T : Appendable> T.append(vararg value: CharSequence?): T {
     for (item in value)

libraries/stdlib/test/text/StringBuilderTest.kt

@@ -6,10 +6,10 @@ import org.junit.Test as test
 class StringBuilderTest {
 
     @test fun stringBuild() {
-        val s = StringBuilder {
+        val s = buildString {
             append("a")
             append(true)
-        }.toString()
+        }
         assertEquals("atrue", s)
     }
 
@@ -21,8 +21,8 @@ class StringBuilderTest {
 
     @test fun append() {
         // this test is needed for JS implementation
-        assertEquals("em", StringBuilder {
+        assertEquals("em", buildString {
             append("element", 2, 4)
-        }.toString())
+        })
     }
 }