buildString with initial capacity for the StringBuilder instance

this method helps save computation time when the developer knows or have a good
educated guess about the size of the generated string and have to use control
structures while filling the string builder

Signed-off-by: Laszlo Hornyak <laszlo.hornyak@gmail.com>

Signed-off-by: Laszlo Hornyak <laszlo.hornyak@gmail.com>

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

@@ -9,6 +9,12 @@ package kotlin.text
 @kotlin.internal.InlineOnly
 public inline fun buildString(builderAction: StringBuilder.() -> Unit): String = StringBuilder().apply(builderAction).toString()
 
+/**
+ * Builds new string by populating newly created [StringBuilder] initialized with the given capacity using provided [builderAction] and then converting it to [String].
+ */
+@kotlin.internal.InlineOnly
+inline fun buildString(capacity : Int, builderAction: StringBuilder.() -> Unit): String = StringBuilder(capacity).apply(builderAction).toString()
+
 /**
  * Appends all arguments to the given [Appendable].
  */

libraries/stdlib/test/text/StringBuilderJVMTest.kt

@@ -5,6 +5,13 @@ import kotlin.test.*
 import org.junit.Test as test
 
 class StringBuilderJVMTest() {
+
+    @test fun stringBuildWithInitialCapacity() {
+        val s = buildString(123) {
+            assertEquals(123, capacity())
+        }
+    }
+
     @test fun getAndSetChar() {
         val sb = StringBuilder("abc")
         sb[1] = 'z'