Pure systems-programming toolkit enabling bit-exact C semantics with single-heap memory, C-compatible types, deterministic floating-point, and dual-mode bitshift engine for reliable C-to-language porting.
Pure Kotlin multiplatform systems programming library for exact C code porting — providing deterministic, bit-exact low-level primitives across Kotlin/JS and Kotlin/Native targets to enable reliable C-to-Kotlin code migration.
Source-code rule: no
import java.*/import javax.*insrc/. SeeCLAUDE.md.
KLang is not a cinterop wrapper or FFI layer. It's a pure Kotlin implementation that precisely replicates C's bitwise operations, memory model, and numeric behavior. This enables accurate porting of C code to idiomatic Kotlin multiplatform while maintaining exact bit-level compatibility.
Multiple large-scale C-to-Kotlin porting projects failed or took months to debug due to subtle behavioral differences between Kotlin and C:
KLang solves these issues by implementing C semantics in pure, portable Kotlin.
KLang bridges the gap between Kotlin's high-level abstractions and C's low-level control, enabling:
All C-style memory lives in a single GlobalHeap backed by a pure Kotlin ByteArray. Pointers are Int byte offsets, providing:
KMalloc) with coalescing, splitting, and size-class binsmalloc/calloc/realloc/free, strlen/strcmp/memcpy/memmove, etc.Unlike C's platform-dependent long double, KLang provides explicit control:
CDouble: IEEE-754 binary64 (exact on all targets)CLongDouble: Selectable flavors — DOUBLE64, EXTENDED80, or IEEE128CFloat128: Double-double arithmetic (~106-bit mantissa precision)Benchmark Results (100M summations of 1e-8, expected: 1.0):
Simple double: 1.000000082740371 (error: 8.27e-08)
Kahan compensated: 1.000000000000000 (error: 1.11e-16, 1.8x slower)
KLang double-double: 1.000000000000000 (error: 4.44e-31, 2.1x slower)
Double-double provides ~15 orders of magnitude better precision than compensated summation while maintaining consistent behavior across all platforms.
A unified shift interface supporting both performance and C-exact determinism:
shl/shr/ushr operations (use only after validation)Why this matters: Kotlin's shl, shr, and bitwise operators have platform-specific behavior that breaks C algorithm ports. A single misplaced and 0xFF can cause cryptographic or compression algorithms to produce different results on different platforms.
All C types have Klang equivalents with exact semantic matching:
All types use heap-based storage for zero-copy operations and exact C memory layout.
All platforms provide identical semantics — no endianness leaks, no platform-specific floating-point quirks.
Memory Management
GlobalArrayHeap: Single expandable heap with typed load/store operationsKMalloc: Production-ready allocator with coalescing and fragmentation controlCPointer<T>: Type-safe pointer abstraction over Int offsetsNumerical Computing
BitShiftEngine: Configurable shift strategies (native vs arithmetic)ArrayBitShifts: Efficient multi-limb operations for arbitrary-precision mathHeapUInt128: 128-bit unsigned integer with full arithmetic supportCFloat128: Double-double precision (~31 decimal digits)C Library Compatibility
strlen, , , , , Detailed documentation available in docs/klang/:
# Build all targets
./gradlew build
# Build web/JS target
./gradlew jsWeb
# Build native executable (macOS ARM64)
./gradlew buildMac
# Run native executable
./gradlew run
# Build Docker image (Linux ARM64)
./gradlew buildDockerImage
# Run all tests
./gradlew test
# Run JS tests only
./gradlew jsTest
# Run native tests (macOS ARM64)
./gradlew macosArm64Test
src/
├── commonMain/kotlin/io/github/kotlinmania/klang/
│ ├── mem/ # Memory management (GlobalHeap, KMalloc, CLib)
│ ├── bitwise/ # BitShiftEngine, array operations
│ ├── fp/ # Floating-point types (CDouble, CLongDouble, CFloat128)
│ ├── int/hpc/ # HeapUInt128 and arbitrary-precision integers
│ └── stringshift/ # String manipulation utilities
├── jsMain/ # JavaScript-specific implementations
└── nativeMain/ # Native platform implementations
tools/ # C reference implementations for validation
docs/klang/ # Comprehensive documentation
import io.github.kotlinmania.klang.mem.*
// Initialize heap
GlobalHeap.init(4096)
// Allocate memory
val ptr = Runtime.kmalloc(256)
ptr.store(0x12345678)
val value = ptr.load()
// C-style string operations
val str = "Hello, KLang!".toCString()
val len = CLib.strlen(str)
Runtime.kfree(ptr)
import io.github.kotlinmania.klang.fp.CFloat128
// Double-double precision
val a = CFloat128(1.0 / 3.0) // ~106-bit mantissa
val b = CFloat128(2.0 / 3.0)
val sum = a + b
// Result is accurate to ~31 decimal digits
import io.github.kotlinmania.klang.bitwise.*
// Configure shift mode
BitShiftConfig.defaultMode = BitShiftMode.NATIVE
// Shift large limb arrays
val limbs = intArrayOf(0x1234, 0xABCD, 0x00FF, 0xC0DE)
val shifted = ArrayBitShifts.shl16LEInPlace(limbs, bits = 37)
KLang is designed for production use with performance characteristics competitive with native C implementations:
See docs/klang/11-poc-benchmark.md for detailed performance analysis.
Contributions welcome! Areas of interest:
Licensed under the Apache License, Version 2.0. See LICENSE for details.
C_UInt8, C_UInt16, C_UInt32, C_UInt64 (and signed variants)C_UInt128, C_Int128 (matching GCC/Clang's __uint128 and __int128)CFloat, CDouble, CLongDouble, CFloat128 with configurable precision profilesstrcmpstrcpystrncpystrchrstrstrmemcpy, memmove, memset, memchr, memcmpSurfaced from shared tags and platforms — no rankings paid for.