fractional-indexing-kt

2.0.4indexed

Generates lexicographically-sortable, variable-length byte keys terminated by 0x80 for application-defined ordering (e.g., drag-and-drop lists), supports before/after/between inserts, rebalance and multiple encodings.

AndroidJSJVMNativeWasm·Pon57/fractional-indexing-kt

Stars

—

Used by

dependents

—

Health

/ 100

JVM Android iOS macOS wasmJS

Fractional Indexing for Kotlin

A Kotlin Multiplatform library that generates lexicographically sortable keys for application-defined ordering (e.g., drag-and-drop lists). Each key is a canonical variable-length byte sequence ending in 0x80. By generating new keys from neighboring items (before / after / between), most inserts can be handled without rewriting the entire list.

Coordinates

Group: dev.pon
Artifact: fractional-indexing

Installation

dependencies {
    implementation("dev.pon:fractional-indexing:<version>")
}

Quick Start

import dev.pon.fractionalindexing.FractionalIndex
import dev.pon.fractionalindexing.FractionalIndexGenerator

val center = FractionalIndex.default()
val left = FractionalIndexGenerator.before(center)
val right = FractionalIndexGenerator.after(center)

val mid = FractionalIndexGenerator
    .between(left, right)
    .getOrThrow()

check(left < mid && mid < right)

Example App

A Kotlin Multiplatform example module is available at example/.
Run the drag-and-drop list demo with ./gradlew :example:jvmRun.

https://github.com/user-attachments/assets/37b3f98f-a8ec-45a9-ac35-c822c50be74f

Extension API

import dev.pon.fractionalindexing.after
import dev.pon.fractionalindexing.before
import dev.pon.fractionalindexing.between

val center = FractionalIndex.default()
val left = center.before()
val right = center.after()
val mid = left.between(right).getOrThrow()

Parse and Encode

val indexFromHex = FractionalIndex.fromHexString("7f80").getOrThrow()
val indexFromSortableBase64 = FractionalIndex.fromSortableBase64String("Us-").getOrThrow()
val indexFromBase64 = FractionalIndex.fromBase64String("f4A=").getOrThrow()

val rawBytes = indexFromHex.toByteArray()
val indexFromBytes = FractionalIndex.fromByteArray(rawBytes).getOrThrow()
val hex = indexFromHex.toHexString()                                  // "7f80"
val sortableBase64 = indexFromSortableBase64.toSortableBase64String() 
 base64 = indexFromBase64.toBase64String()

fromByteArray / / / accept canonical library format only. Ending with is necessary but not sufficient: the first byte is also a format tag. Malformed or non-canonical keys (for example , , ) return failure. The existing APIs (, , and ) remain available but are deprecated.

Notes

Public API Overview

Versioning

This library follows Semantic Versioning.

Changes to the key format or generation algorithm that break compatibility with previously generated keys are treated as breaking changes (major version bump).
Changes that only affect the exact canonical keys produced by future calls are not considered breaking as long as existing keys remain valid and continue to sort correctly.
Algorithmic output changes may still be called out in release notes.

Note: Upgrading to a new major version may require migrating your existing database records to maintain the correct sort order.

API Compatibility Check

CI runs ./gradlew :library:checkKotlinAbi --no-configuration-cache to detect binary-incompatible public API changes.
When intentionally changing public API, regenerate the baseline with ./gradlew :library:updateKotlinAbi --no-configuration-cache and commit the updated ABI dump files under library/api/.

Performance Regression Check

Deterministic key-size checks (FractionalIndexGeneratorBenchmarkRegressionTest) run in regular JVM tests.

License

Apache License 2.0. See LICENSE.

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

Kubit★ 48

mhss1Delivers micro-optimized utilities and data structures enhancing performance and memory efficiency, offering fast, allocation-conscious solutions to common operations with familiar APIs and seamless serialization.Shared: utility, serialization, performance-optimization

libphonenumber-kotlin★ 46

luca992Enhances phone number handling by addressing performance issues and reducing method count in Android applications. Offers a repackaged API and custom instantiation methods for streamlined usage.Shared: utility, performance-optimization

Deci★ 16

KimplifyHigh-precision decimal arithmetic with arbitrary-precision engines, predictable rounding modes, locale-aware parsing/normalization, arithmetic/extension helpers, and built-in serialization for financial calculations.Shared: utility, serialization

Capturable★ 15

jmseb3Utility library facilitates conversion of composable content into ImageBitmap, enabling asynchronous capture and sharing or saving of components. Ideal for modern UI frameworks.Shared: utility, kotlin-multiplatform-sample

ndarray.simd★ 12

Martmists-GHLibrary enhances NDArray operations with SIMD support, optimizing performance for numerical computations. Inspired by Viktor, aims to fully leverage SIMD capabilities for efficient processing.Shared: utility, performance-optimization

ktoml★ 558

orchestr7Serialization/deserialization library for TOML configuration files. Supports various data types, including nested structures, partial deserialization, and file-based operations. Configurable parsing and serialization options.Shared: serialization, kotlin-multiplatform-sample

Fractional Indexing for Kotlin

Quick Start

import dev.pon.fractionalindexing.FractionalIndex import dev.pon.fractionalindexing.FractionalIndexGenerator val center = FractionalIndex.default() val left = FractionalIndexGenerator.before(center) val right = FractionalIndexGenerator.after(center) val mid = FractionalIndexGenerator .between(left, right) .getOrThrow() check(left < mid && mid < right)

import dev.pon.fractionalindexing.after import dev.pon.fractionalindexing.before import dev.pon.fractionalindexing.between val center = FractionalIndex.default() val left = center.before() val right = center.after() val mid = left.between(right).getOrThrow()

Parse and Encode

val indexFromHex = FractionalIndex.fromHexString("7f80").getOrThrow() val indexFromSortableBase64 = FractionalIndex.fromSortableBase64String("Us-").getOrThrow() val indexFromBase64 = FractionalIndex.fromBase64String("f4A=").getOrThrow() val rawBytes = indexFromHex.toByteArray() val indexFromBytes = FractionalIndex.fromByteArray(rawBytes).getOrThrow() val hex = indexFromHex.toHexString() // "7f80" val sortableBase64 = indexFromSortableBase64.toSortableBase64String() base64 = indexFromBase64.toBase64String()

Versioning

Changes to the key format or generation algorithm that break compatibility with previously generated keys are treated as breaking changes (major version bump).

Changes that only affect the exact canonical keys produced by future calls are not considered breaking as long as existing keys remain valid and continue to sort correctly.

Algorithmic output changes may still be called out in release notes.

Note: Upgrading to a new major version may require migrating your existing database records to maintain the correct sort order.

API Compatibility Check

CI runs ./gradlew :library:checkKotlinAbi --no-configuration-cache to detect binary-incompatible public API changes.

When intentionally changing public API, regenerate the baseline with ./gradlew :library:updateKotlinAbi --no-configuration-cache and commit the updated ABI dump files under library/api/.