revert the changes to BigText.substring(), and refactor the lazy view into a new API BigText.subView()

Author: sunny-chung

CHANGELOG.md

@@ -12,6 +12,7 @@ UI
 
 DS
 - Emoji sequences support
+- `BigText.subView()` -- returning memory-efficient sub-view in `CharSequence` type
 
 ### Breaking Change!
 UI
@@ -24,10 +25,6 @@ DS
 UI
 - OOM crash when there is a large text in clipboard (without pasting)
 
-### Optimized
-DS
-- `BigText.substring()` memory usage
-
 
 ## UI [2.4.0] - 2026-03-01
 

datastructure/src/jvmMain/kotlin/com/sunnychung/lib/multiplatform/bigtext/core/BigText.kt

@@ -53,6 +53,19 @@ interface BigText {
 
     fun subSequence(startIndex: Int, endIndex: Int): CharSequence
 
+    /**
+     * Returns a view of the text range.
+     *
+     * Use this when you only need to read or scan a range, especially a large range. For example, it is suitable for
+     * regex searches, counting characters, or passing text to code that only needs the [CharSequence] interface.
+     *
+     * Do not use this when your code requires the result to be the custom type produced by
+     * [charSequenceBuilderFactory] and [charSequenceFactory]. Use [substring] or [subSequence] for that.
+     */
+    fun subView(startIndex: Int, endIndex: Int): CharSequence = subSequence(startIndex, endIndex)
+
+    fun subView(range: IntRange): CharSequence = subView(range.start, range.endInclusive + 1)
+
     fun chunkAt(start: Int): String
 
     fun findLineString(lineIndex: Int): CharSequence

datastructure/src/jvmMain/kotlin/com/sunnychung/lib/multiplatform/bigtext/core/BigTextImpl.kt

@@ -55,7 +55,7 @@ private const val EPS = 1e-4f
 private val accumulatedWidthCacheInterval = 64
 private val accumulatedWidthCacheHalfInterval = accumulatedWidthCacheInterval / 2
 private const val MAX_GRAPHEME_SEQUENCE_LENGTH = 128
-private const val LAZY_SUBSTRING_MIN_LENGTH = 8 * 1024 * 1024
+private const val SUBVIEW_MIN_LENGTH = 8 * 1024 * 1024
 
 open class BigTextImpl(
     override val chunkSize: Int = 2 * 1024 * 1024, // 2 MB
@@ -964,34 +964,8 @@ open class BigTextImpl(
             return ""
         }
 
-        if (decorator == null && endExclusive - start >= LAZY_SUBSTRING_MIN_LENGTH) {
-            val segments = mutableListOf<BigTextSegment>()
-            var node = tree.findNodeByRenderCharIndex(start) ?: throw IllegalStateException("Cannot find string node for position $start")
-            var nodeStartPos = findRenderPositionStart(node)
-            var numRemainCharsToCopy = endExclusive - start
-            var copyFromBufferIndex = start - nodeStartPos + node.value.renderBufferStart
-            while (numRemainCharsToCopy > 0) {
-                val numCharsToCopy = minOf(endExclusive, nodeStartPos + node.value.currentRenderLength) - maxOf(start, nodeStartPos)
-                val copyUntilBufferIndex = copyFromBufferIndex + numCharsToCopy
-                if (numCharsToCopy > 0) {
-                    segments += BigTextSegment(
-                        buffer = node.value.buffer,
-                        start = copyFromBufferIndex,
-                        endExclusive = copyUntilBufferIndex,
-                    )
-                    numRemainCharsToCopy -= numCharsToCopy
-                }
-                if (numRemainCharsToCopy > 0) {
-                    nodeStartPos += node.value.currentRenderLength
-                    node = tree.nextNode(node) ?: throw IllegalStateException("Cannot find the next string node. Requested = $start ..< $endExclusive. Remain = $numRemainCharsToCopy")
-                    copyFromBufferIndex = node.value.renderBufferStart
-                }
-            }
-            return BigTextSegmentCharSequence(segments)
-        }
-
 //        val result = charSequenceBuilderFactory(endExclusive - start)
-        val result = getCharSequenceBuilder()
+        val result = getCharSequenceBuilder(endExclusive - start)
         var node = tree.findNodeByRenderCharIndex(start) ?: throw IllegalStateException("Cannot find string node for position $start")
         var nodeStartPos = findRenderPositionStart(node)
         var numRemainCharsToCopy = endExclusive - start
@@ -1016,13 +990,46 @@ open class BigTextImpl(
         return charSequenceFactory(result)
     }
 
+    private fun lazySubSequence(start: Int, endExclusive: Int): CharSequence {
+        val segments = mutableListOf<BigTextSegment>()
+        var node = tree.findNodeByRenderCharIndex(start) ?: throw IllegalStateException("Cannot find string node for position $start")
+        var nodeStartPos = findRenderPositionStart(node)
+        var numRemainCharsToCopy = endExclusive - start
+        var copyFromBufferIndex = start - nodeStartPos + node.value.renderBufferStart
+        while (numRemainCharsToCopy > 0) {
+            val numCharsToCopy = minOf(endExclusive, nodeStartPos + node.value.currentRenderLength) - maxOf(start, nodeStartPos)
+            val copyUntilBufferIndex = copyFromBufferIndex + numCharsToCopy
+            if (numCharsToCopy > 0) {
+                segments += BigTextSegment(
+                    buffer = node.value.buffer,
+                    start = copyFromBufferIndex,
+                    endExclusive = copyUntilBufferIndex,
+                )
+                numRemainCharsToCopy -= numCharsToCopy
+            }
+            if (numRemainCharsToCopy > 0) {
+                nodeStartPos += node.value.currentRenderLength
+                node = tree.nextNode(node) ?: throw IllegalStateException("Cannot find the next string node. Requested = $start ..< $endExclusive. Remain = $numRemainCharsToCopy")
+                copyFromBufferIndex = node.value.renderBufferStart
+            }
+        }
+        return BigTextSegmentCharSequence(segments)
+    }
+
     private fun getCharSequenceBuilder(): GeneralStringBuilder {
         // possible memory leak
         return charSequenceBuilder
             .getOrSet { charSequenceBuilderFactory(chunkSize) }
             .apply { clear() }
     }
 
+    private fun getCharSequenceBuilder(capacity: Int): GeneralStringBuilder =
+        if (capacity > chunkSize) {
+            charSequenceBuilderFactory(capacity)
+        } else {
+            getCharSequenceBuilder()
+        }
+
     // TODO: refactor not to duplicate implementation of substring
     override fun subSequence(start: Int, endExclusive: Int): CharSequence {
         require(start <= endExclusive) { "start should be <= endExclusive" }
@@ -1037,7 +1044,7 @@ open class BigTextImpl(
 //        log.v { "subSequence start" }
 
 //        val result = charSequenceBuilderFactory(endExclusive - start)
-        val result = getCharSequenceBuilder()
+        val result = getCharSequenceBuilder(endExclusive - start)
         var node = tree.findNodeByRenderCharIndex(start) ?: throw IllegalStateException("Cannot find string node for position $start")
         var nodeStartPos = findRenderPositionStart(node)
         var numRemainCharsToCopy = endExclusive - start
@@ -1080,6 +1087,22 @@ open class BigTextImpl(
         }
     }
 
+    override fun subView(startIndex: Int, endIndex: Int): CharSequence {
+        require(startIndex <= endIndex) { "start should be <= endExclusive" }
+        require(0 <= startIndex) { "Invalid start" }
+        require(endIndex <= length) { "endExclusive $endIndex is out of bound. length = $length" }
+
+        if (startIndex == endIndex) {
+            return ""
+        }
+
+        if (decorator == null && endIndex - startIndex >= SUBVIEW_MIN_LENGTH) {
+            return lazySubSequence(startIndex, endIndex)
+        }
+
+        return subSequence(startIndex, endIndex)
+    }
+
     protected open fun decorate(nodeValue: BigTextNodeValue, text: CharSequence, renderPositions: IntRange) =
         decorator!!.onApplyDecorationOnOriginal(text, renderPositions)
 

datastructure/src/jvmMain/kotlin/com/sunnychung/lib/multiplatform/bigtext/core/ConcurrentBigText.kt

@@ -63,6 +63,9 @@ open class ConcurrentBigText(open val delegate: LockableBigText) : BigText {
     override fun substring(start: Int, endExclusive: Int): CharSequence = withReadLock { delegate.substring(start, endExclusive) }
 
     override fun subSequence(startIndex: Int, endIndex: Int): CharSequence = withReadLock { delegate.subSequence(startIndex, endIndex) }
+
+    override fun subView(startIndex: Int, endIndex: Int): CharSequence = withReadLock { delegate.subView(startIndex, endIndex) }
+
     override fun chunkAt(start: Int): String = withReadLock { delegate.chunkAt(start) }
 
     override fun findLineString(lineIndex: Int): CharSequence = withReadLock { delegate.findLineString(lineIndex) }

datastructure/src/jvmTest/kotlin/com/sunnychung/lib/multiplatform/bigtext/test/BigTextImplTest.kt

@@ -3,12 +3,15 @@ package com.sunnychung.lib.multiplatform.bigtext.test
 import com.sunnychung.lib.multiplatform.bigtext.core.BigTextImpl
 import com.sunnychung.lib.multiplatform.bigtext.core.isD
 import com.sunnychung.lib.multiplatform.bigtext.extension.length
+import com.sunnychung.lib.multiplatform.bigtext.util.GeneralStringBuilder
 import org.junit.jupiter.params.ParameterizedTest
 import org.junit.jupiter.params.provider.MethodSource
 import org.junit.jupiter.params.provider.ValueSource
 import kotlin.random.Random
 import kotlin.test.Test
 import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertTrue
 
 /**
  * Some cases in this test may look very specific, but they had consistently failed before.
@@ -496,6 +499,44 @@ class BigTextImplTest {
         }
     }
 
+    @Test
+    fun subViewPreservesCustomCharSequenceTypeForSmallRange() {
+        val t = BigTextImpl(
+            chunkSize = 64,
+            charSequenceBuilderFactory = { CustomStringBuilder(it) },
+            charSequenceFactory = { CustomCharSequence(it.toString()) },
+        )
+        t.append("abcdef")
+
+        val view = t.subView(1, 4)
+
+        assertTrue(view is CustomCharSequence)
+        assertEquals("bcd", view.toString())
+    }
+
+    @Test
+    fun subViewCanReturnNonCustomCharSequenceTypeForLargeRange() {
+        val text = repeatedAlphabet(SUBVIEW_TEST_LENGTH)
+        val t = BigTextImpl(
+            chunkSize = 1024 * 1024,
+            charSequenceBuilderFactory = { CustomStringBuilder(it) },
+            charSequenceFactory = { CustomCharSequence(it.toString()) },
+        )
+        t.append(text)
+
+        val start = 17
+        val endExclusive = text.length - 19
+        val view = t.subView(start, endExclusive)
+
+        assertFalse(view is CustomCharSequence)
+        assertEquals(endExclusive - start, view.length)
+        assertEquals(text[start], view[0])
+        assertEquals(text[start + 1], view[1])
+        assertEquals(text[start + 1024 * 1024], view[1024 * 1024])
+        assertEquals(text[endExclusive - 1], view[view.lastIndex])
+        assertEquals(text.substring(start + 99, start + 123), view.subSequence(99, 123).toString())
+    }
+
     /**
      * Benchmark:
      *
@@ -548,3 +589,48 @@ private fun random(from: Int, toExclusive: Int): Int {
     }
     return Random.nextInt(from, toExclusive)
 }
+
+private const val SUBVIEW_TEST_LENGTH = 8 * 1024 * 1024 + 64
+
+private fun repeatedAlphabet(length: Int): String = buildString(length) {
+    repeat(length) {
+        append(('a'.code + it % 26).toChar())
+    }
+}
+
+private class CustomStringBuilder(capacity: Int) : GeneralStringBuilder {
+    private val delegate = StringBuilder(capacity)
+
+    override fun append(value: Char): Appendable {
+        delegate.append(value)
+        return this
+    }
+
+    override fun append(value: CharSequence?): Appendable {
+        delegate.append(value)
+        return this
+    }
+
+    override fun append(value: CharSequence?, startIndex: Int, endIndex: Int): Appendable {
+        delegate.append(value, startIndex, endIndex)
+        return this
+    }
+
+    override fun clear() {
+        delegate.clear()
+    }
+
+    override fun toString(): String = delegate.toString()
+}
+
+private class CustomCharSequence(private val delegate: String) : CharSequence {
+    override val length: Int
+        get() = delegate.length
+
+    override fun get(index: Int): Char = delegate[index]
+
+    override fun subSequence(startIndex: Int, endIndex: Int): CharSequence =
+        CustomCharSequence(delegate.substring(startIndex, endIndex))
+
+    override fun toString(): String = delegate
+}

demo-ui-composable/src/jvmMain/kotlin/com/sunnychung/lib/multiplatform/bigtext/demo/VariableIncrementalTransformation.kt

@@ -28,7 +28,7 @@ class VariableIncrementalTransformation : IncrementalTextTransformation<Unit> {
     override fun initialize(text: BigText, transformer: BigTextTransformer) {
         transformer.disableComputations()
 
-        val targets = variableRegex.findAll(text.buildString())
+        val targets = variableRegex.findAll(text.subView(0, text.length))
         targets.forEach {
             val name = it.groups[1]!!.value
             transformer.replace(it.range, createSpan(name), BigTextTransformOffsetMapping.WholeBlock)
@@ -56,7 +56,7 @@ class VariableIncrementalTransformation : IncrementalTextTransformation<Unit> {
 
     private fun findNearbyPatterns(change: BigTextChangeEvent): Sequence<RangeWithResult<MatchResult>> {
         val startOffset = maxOf(0, change.changeStartIndex - processLengthLimit)
-        val substring = change.bigText.substring(
+        val substring = change.bigText.subView(
             startOffset
             until
             minOf(change.bigText.length, change.changeEndExclusiveIndex + processLengthLimit)