Change public API: rename onTransformInterval callback, add support for SpannableString (#35)

Author: st235

README.md

@@ -137,7 +137,7 @@ private inline fun getPrivacyPolicyAnnotatedString(
     privacyPolicy: String,
     crossinline onPrivacyPolicyClick: () -> Unit,
 ) = intervalAnnotatedString(privacyPolicy)
-    .asAnnotatedString { id, startsAt, length ->
+    .asAnnotatedString { id, startsAt, endsAt ->
         if (id == PRIVACY_POLICY_LINK_INTERVAL_ID) {
             addLink(
                 clickable =
@@ -154,7 +154,7 @@ private inline fun getPrivacyPolicyAnnotatedString(
                         linkInteractionListener = { onPrivacyPolicyClick() },
                     ),
                 start = startsAt,
-                end = startsAt + length,
+                end = endsAt,
             )
         }
     }

app/src/main/java/com/justeattakeaway/intervalannotatedstring/sampleapp/compose/CareersPromotionCard.kt

@@ -59,9 +59,7 @@ fun CareersPromotionCard(
             )
             Text(
                 text = intervalAnnotatedString(R.string.careers_promotion_card_text)
-                    .asAnnotatedString { id, startsAt, length ->
-                        val endsAt = startsAt + length
-
+                    .asAnnotatedString { id, startsAt, endsAt ->
                         if (id == URL_ANNOTATION_ID) {
                             addLink(
                                 clickable = LinkAnnotation.Clickable(

app/src/main/java/com/justeattakeaway/intervalannotatedstring/sampleapp/compose/Playground.kt

@@ -113,9 +113,7 @@ private fun buildAnnotatedStringPreview(
 
     return try {
         val annotatedString = IntervalAnnotatedString(text)
-            .asAnnotatedString { id, startsAt, length ->
-                val endsAt = startsAt + length
-
+            .asAnnotatedString { id, startsAt, endsAt ->
                 if (!coloursLookup.containsKey(id)) {
                     coloursLookup[id] = Color(
                         Random.nextInt(256),

app/src/main/java/com/justeattakeaway/intervalannotatedstring/sampleapp/compose/SamplesContent.kt

@@ -177,9 +177,7 @@ private fun SampleContentItemRenderingStringViewer(
 ) {
     Text(
         text = intervalAnnotatedString(rawText)
-            .asAnnotatedString { id, startsAt, length ->
-                val endsAt = startsAt + length
-
+            .asAnnotatedString { id, startsAt, endsAt ->
                 val annotation = annotationsLookup[id]
                 when (annotation) {
                     is SpanStyle ->

intervalannotatedstring/api/intervalannotatedstring.api

@@ -61,6 +61,7 @@ public final class com/justeattakeaway/intervalannotatedstring/IntervalAnnotated
 
 public final class com/justeattakeaway/intervalannotatedstring/IntervalAnnotatedStringExtsKt {
 	public static final fun asAnnotatedString-QpJNx2M (Ljava/lang/String;Lkotlin/jvm/functions/Function4;)Landroidx/compose/ui/text/AnnotatedString;
+	public static final fun asSpannableString-QpJNx2M (Ljava/lang/String;Lkotlin/jvm/functions/Function4;)Landroid/text/SpannableString;
 }
 
 public final class com/justeattakeaway/intervalannotatedstring/IntervalAnnotatedStringFactoryKt {

intervalannotatedstring/src/main/java/com/justeattakeaway/intervalannotatedstring/IntervalAnnotatedString.kt

@@ -11,9 +11,10 @@ import com.justeattakeaway.intervalannotatedstring.InlineIntervalSyntaxParser.No
 typealias OnTransformText<T> = (text: String) -> T
 
 /**
- * Applies interval transformation on the target rendering string implementation.
+ * Applies interval transformation on the target rendering string implementation at
+ * inclusive startsAt and exclusive endsAt bounds.
  */
-typealias OnTransformInterval<T> = T.(id: String, startsAt: Int, length: Int) -> Unit
+typealias OnApplyIntervalTransformation<T> = T.(id: String, startsAt: Int, endsAt: Int) -> Unit
 
 /**
  * Primary class for working with interval annotated strings.
@@ -26,14 +27,14 @@ value class IntervalAnnotatedString(
     /**
      * Performs a transformation of raw text (with embedded intervals metadata) to the target rendering string
      * implementation. Can be used to transform the string to an instance of
-     * [androidx.compose.ui.text.AnnotatedString] or [com.jet.pie2.utils.StyledString].
+     * [androidx.compose.ui.text.AnnotatedString] or [android.text.SpannableString].
      *
      * @param T The target type for the transformed string. This is typically a class
      * designed to represent a rendering text, such as
-     * [androidx.compose.ui.text.AnnotatedString] or [com.jet.pie2.utils.StyledString].
+     * [androidx.compose.ui.text.AnnotatedString] or [android.text.SpannableString].
      * The chosen type [T] should generally be constructible from a plain string (via [onTransformText]) and
      * should allow for range-based modifications, styling, or annotations
-     * (via [onTransformInterval]) to be useful with this transformation.
+     * (via [onApplyIntervalTransformation]) to be useful with this transformation.
      *
      * @throws NoIdException if the id subsection is empty
      * @throws EmptyInlineTextException if the raw text within the interval annotated string area is empty
@@ -43,12 +44,16 @@ value class IntervalAnnotatedString(
     @Throws(NoIdException::class, EmptyInlineTextException::class)
     inline fun <T> transform(
         onTransformText: OnTransformText<T>,
-        onTransformInterval: OnTransformInterval<T>,
+        onApplyIntervalTransformation: OnApplyIntervalTransformation<T>,
     ): T {
         val (clearedText, intervals) = InlineIntervalSyntaxParser.parseMetadata(rawString)
         val outResult = onTransformText(clearedText)
         for (interval in intervals) {
-            outResult.onTransformInterval(interval.id, interval.startsAt, interval.length)
+            outResult.onApplyIntervalTransformation(
+                interval.id,
+                interval.startsAt,
+                interval.startsAt + interval.length, // endsAt
+            )
         }
         return outResult
     }

intervalannotatedstring/src/main/java/com/justeattakeaway/intervalannotatedstring/IntervalAnnotatedStringExts.kt

@@ -1,13 +1,31 @@
 package com.justeattakeaway.intervalannotatedstring
 
+import android.text.SpannableString
 import androidx.annotation.AnyThread
 import androidx.annotation.CheckResult
 import androidx.compose.ui.text.AnnotatedString
 import com.justeattakeaway.intervalannotatedstring.InlineIntervalSyntaxParser.EmptyInlineTextException
 import com.justeattakeaway.intervalannotatedstring.InlineIntervalSyntaxParser.NoIdException
 
 /**
- * Converts an interval annotated string instance to AnnotatedString.
+ * Converts an interval annotated string instance to [SpannableString].
+ *
+ * @see IntervalAnnotatedString
+ * @see SpannableString
+ */
+@AnyThread
+@CheckResult
+@Throws(NoIdException::class, EmptyInlineTextException::class)
+inline fun IntervalAnnotatedString.asSpannableString(
+    onAddIntervalStyle: OnApplyIntervalTransformation<SpannableString>
+): SpannableString =
+    transform(
+        onTransformText = { SpannableString(it) },
+        onApplyIntervalTransformation = onAddIntervalStyle,
+    )
+
+/**
+ * Converts an interval annotated string instance to [AnnotatedString].
  *
  * @see IntervalAnnotatedString
  * @see AnnotatedString
@@ -16,9 +34,9 @@ import com.justeattakeaway.intervalannotatedstring.InlineIntervalSyntaxParser.No
 @CheckResult
 @Throws(NoIdException::class, EmptyInlineTextException::class)
 inline fun IntervalAnnotatedString.asAnnotatedString(
-    onAddIntervalStyle: OnTransformInterval<AnnotatedString.Builder>
+    onAddIntervalStyle: OnApplyIntervalTransformation<AnnotatedString.Builder>
 ): AnnotatedString =
     transform(
         onTransformText = { AnnotatedString.Builder(it) },
-        onTransformInterval = onAddIntervalStyle,
+        onApplyIntervalTransformation = onAddIntervalStyle,
     ).toAnnotatedString()

intervalannotatedstring/src/test/java/com/justeattakeaway/intervalannotatedstring/IntervalAnnotatedStringTest.kt

@@ -17,14 +17,14 @@ typealias TestRenderingString = String
 @RunWith(JUnit4::class)
 class IntervalAnnotatedStringTest {
     private val onTransformText = mockk<OnTransformText<TestRenderingString>>()
-    private val onTransformInterval = mockk<OnTransformInterval<TestRenderingString>>()
+    private val onApplyIntervalTransformation = mockk<OnApplyIntervalTransformation<TestRenderingString>>()
 
     @Before
     fun setUp() {
         mockkObject(InlineIntervalSyntaxParser)
 
         every { onTransformText.invoke(any()) } returns TEST_RENDERING_STRING
-        every { onTransformInterval.invoke(any(), any(), any(), any()) } returns Unit
+        every { onApplyIntervalTransformation.invoke(any(), any(), any(), any()) } returns Unit
     }
 
     @SuppressLint("CheckResult")
@@ -39,7 +39,7 @@ class IntervalAnnotatedStringTest {
             )
 
         // When
-        text.transform(onTransformText, onTransformInterval)
+        text.transform(onTransformText, onApplyIntervalTransformation)
 
         // Then
         verify(exactly = 1) { onTransformText.invoke(eq(TEST_INTERVAL_CLEARED_STRING)) }
@@ -57,27 +57,27 @@ class IntervalAnnotatedStringTest {
             )
 
         // When
-        text.transform(onTransformText, onTransformInterval)
+        text.transform(onTransformText, onApplyIntervalTransformation)
 
         // Then
         verify {
-            onTransformInterval.invoke(
+            onApplyIntervalTransformation.invoke(
                 eq(TEST_RENDERING_STRING),
                 eq(TEST_INTERVAL_1.id),
                 eq(TEST_INTERVAL_1.startsAt),
-                eq(TEST_INTERVAL_1.length),
+                eq(TEST_INTERVAL_1.startsAt + TEST_INTERVAL_1.length),
             )
-            onTransformInterval.invoke(
+            onApplyIntervalTransformation.invoke(
                 eq(TEST_RENDERING_STRING),
                 eq(TEST_INTERVAL_2.id),
                 eq(TEST_INTERVAL_2.startsAt),
-                eq(TEST_INTERVAL_2.length),
+                eq(TEST_INTERVAL_2.startsAt + TEST_INTERVAL_2.length),
             )
-            onTransformInterval.invoke(
+            onApplyIntervalTransformation.invoke(
                 eq(TEST_RENDERING_STRING),
                 eq(TEST_INTERVAL_3.id),
                 eq(TEST_INTERVAL_3.startsAt),
-                eq(TEST_INTERVAL_3.length),
+                eq(TEST_INTERVAL_3.startsAt + TEST_INTERVAL_3.length),
             )
         }
     }