Postpone introducing common StringBuilder.capacity() function

Its support complicates JS StringBuilder implementation with no actual
performance improvements. Benefits of having capacity() function
in common code are also not completely clear.

Relates to KT-33069
#KT-40168

libraries/stdlib/api/js-v1/kotlin.text.kt

@@ -1275,8 +1275,8 @@ public final class StringBuilder : kotlin.text.Appendable, kotlin.CharSequence {
     @kotlin.WasExperimental(markerClass = {kotlin.ExperimentalStdlibApi::class})
     public final fun appendRange(value: kotlin.CharSequence, startIndex: kotlin.Int, endIndex: kotlin.Int): kotlin.text.StringBuilder
 
-    @kotlin.SinceKotlin(version = "1.4")
-    @kotlin.WasExperimental(markerClass = {kotlin.ExperimentalStdlibApi::class})
+    @kotlin.SinceKotlin(version = "1.3")
+    @kotlin.Deprecated(level = DeprecationLevel.ERROR, message = "Obtaining StringBuilder capacity is not supported in JS and common code.")
     public final fun capacity(): kotlin.Int
 
     @kotlin.SinceKotlin(version = "1.3")

libraries/stdlib/api/js/kotlin.text.kt

@@ -1275,8 +1275,8 @@ public final class StringBuilder : kotlin.text.Appendable, kotlin.CharSequence {
     @kotlin.WasExperimental(markerClass = {kotlin.ExperimentalStdlibApi::class})
     public final fun appendRange(value: kotlin.CharSequence, startIndex: kotlin.Int, endIndex: kotlin.Int): kotlin.text.StringBuilder
 
-    @kotlin.SinceKotlin(version = "1.4")
-    @kotlin.WasExperimental(markerClass = {kotlin.ExperimentalStdlibApi::class})
+    @kotlin.SinceKotlin(version = "1.3")
+    @kotlin.Deprecated(level = DeprecationLevel.ERROR, message = "Obtaining StringBuilder capacity is not supported in JS and common code.")
     public final fun capacity(): kotlin.Int
 
     @kotlin.SinceKotlin(version = "1.3")

libraries/stdlib/js/src/kotlin/text/StringBuilderJs.kt

@@ -17,7 +17,6 @@ public actual class StringBuilder actual constructor(content: String) : Appendab
      * In Kotlin/JS implementation of StringBuilder the initial capacity has no effect on the further performance of operations.
      */
     actual constructor(capacity: Int) : this() {
-        this.asDynamic()._capacity = capacity
     }
 
     /** Constructs a string builder that contains the same characters as the specified [content] char sequence. */
@@ -135,9 +134,10 @@ public actual class StringBuilder actual constructor(content: String) : Appendab
      *
      * In Kotlin/JS implementation of StringBuilder the value returned from this method may not indicate the actual size of the backing storage.
      */
-    @SinceKotlin("1.4")
-    @WasExperimental(ExperimentalStdlibApi::class)
-    actual fun capacity(): Int = if (this.asDynamic()._capacity !== undefined) maxOf(this.asDynamic()._capacity, length) else length
+    @SinceKotlin("1.3")
+//    @ExperimentalStdlibApi
+    @Deprecated("Obtaining StringBuilder capacity is not supported in JS and common code.", level = DeprecationLevel.ERROR)
+    actual fun capacity(): Int = length
 
     /**
      * Ensures that the capacity of this string builder is at least equal to the specified [minimumCapacity].
@@ -151,9 +151,6 @@ public actual class StringBuilder actual constructor(content: String) : Appendab
     @SinceKotlin("1.4")
     @WasExperimental(ExperimentalStdlibApi::class)
     actual fun ensureCapacity(minimumCapacity: Int) {
-        if (minimumCapacity > capacity()) {
-            this.asDynamic()._capacity = minimumCapacity
-        }
     }
 
     /**
@@ -367,9 +364,6 @@ public actual class StringBuilder actual constructor(content: String) : Appendab
     @SinceKotlin("1.4")
     @WasExperimental(ExperimentalStdlibApi::class)
     actual fun trimToSize() {
-        if (this.asDynamic()._capacity !== undefined) {
-            this.asDynamic()._capacity = length
-        }
     }
 
     override fun toString(): String = string

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

@@ -90,8 +90,9 @@ expect class StringBuilder : Appendable, CharSequence {
      *
      * The capacity is the maximum length this string builder can have before an allocation occurs.
      */
-    @SinceKotlin("1.4")
-    @WasExperimental(ExperimentalStdlibApi::class)
+    @SinceKotlin("1.3")
+//    @ExperimentalStdlibApi
+    @Deprecated("Obtaining StringBuilder capacity is not supported in JS and common code.", level = DeprecationLevel.ERROR)
     fun capacity(): Int
 
     /**

libraries/stdlib/test/text/StringBuilderTest.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2010-2018 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Copyright 2010-2020 JetBrains s.r.o. and Kotlin Programming Language contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
@@ -236,8 +236,9 @@ class StringBuilderTest {
     }
 
     @Test
+    @Suppress("DEPRECATION_ERROR")
     fun capacityTest() {
-        assertEquals(100, StringBuilder(100).capacity())
+//        assertEquals(100, StringBuilder(100).capacity()) // not implemented in JS
 
         StringBuilder("string builder from string capacity test").let { sb ->
             assertTrue(sb.capacity() >= sb.length)
@@ -251,7 +252,7 @@ class StringBuilderTest {
             sb.ensureCapacity(1)
             assertTrue(sb.capacity() >= sb.length)
             sb.ensureCapacity(sb.length * 10)
-            assertTrue(sb.capacity() >= sb.length * 10)
+//            assertTrue(sb.capacity() >= sb.length * 10) // not implemented in JS
         }
     }
 
@@ -423,11 +424,11 @@ class StringBuilderTest {
     fun trimToSize() {
         StringBuilder("my trimToSize test").let { sb ->
             assertEquals(18, sb.length)
-            assertTrue(sb.capacity() >= sb.length)
+//            assertTrue(sb.capacity() >= sb.length)
             sb.append('1')
             sb.trimToSize()
             assertEquals(19, sb.length)
-            assertTrue(sb.capacity() >= sb.length)
+//            assertTrue(sb.capacity() >= sb.length)
         }
     }