Merge branch 'main' into renovate/sandwich

Author: ashtanko

README.md

@@ -22,21 +22,21 @@
 
 ### Metrics
 ```text
-14993 number of properties
-10384 number of functions
-8855 number of classes
-229 number of packages
-3486 number of kt files
+15001 number of properties
+10391 number of functions
+8857 number of classes
+230 number of packages
+3488 number of kt files
 ```
 
 
 ### Complexity Report
 ```text
-259493 lines of code (loc)
-158946 source lines of code (sloc)
-115976 logical lines of code (lloc)
-72487 comment lines of code (cloc)
-24701 cyclomatic complexity (mcc)
+259554 lines of code (loc)
+158990 source lines of code (sloc)
+116006 logical lines of code (lloc)
+72493 comment lines of code (cloc)
+24708 cyclomatic complexity (mcc)
 20232 cognitive complexity
 0 number of total code smells
 45 comment source ratio

api/Kotlin-Lab.api

@@ -21732,6 +21732,13 @@ public final class dev/shtanko/kotlinlang/types/phantom/Open : dev/shtanko/kotli
 	public static final field INSTANCE Ldev/shtanko/kotlinlang/types/phantom/Open;
 }
 
+public final class dev/shtanko/kotlinlang/types/unsigned/UnsignedKt {
+	public static final field BIG_COUNTER J
+	public static final fun buffers ()V
+	public static final fun unsignedBitwiseAnd-7apg3OU (B)B
+	public static synthetic fun unsignedBitwiseAnd-7apg3OU$default (BILjava/lang/Object;)B
+}
+
 public final class dev/shtanko/kotlinlang/value/Dp : java/lang/Comparable {
 	public static final field Companion Ldev/shtanko/kotlinlang/value/Dp$Companion;
 	public static final field MULTIPLY_FACTOR F

src/main/kotlin/dev/shtanko/kotlinlang/types/unsigned/UNSIGNED_TYPES.md

@@ -0,0 +1,57 @@
+✅ 1. Binary & Bitwise Operations
+Unsigned types are helpful when doing bit manipulation, as they prevent issues with sign extension and simplify logic.
+
+```kotlin
+val mask: UByte = 0b11110000u
+val value: UByte = 0b10101010u
+val result = value and mask // no unexpected sign problems
+```
+
+✅ 2. Working with Raw Data / Buffers
+When you're processing binary files, network packets, or image data, values are often naturally unsigned.
+
+```kotlin
+val bytes: UByteArray = ubyteArrayOf(0xFFu, 0x01u, 0x7Fu)
+```
+
+✅ 3. Interfacing with C / Native Code (JNI / NDK / WASM)
+If you're using Kotlin/Native or Kotlin/Multiplatform and talking to native libraries, they often expect unsigned types.
+
+```kotlin
+external fun nativeRead(buffer: UByteArray): UInt
+```
+
+✅ 4. Avoiding Negative Values by Design
+If a value should never be negative (like an ID, count, size, etc.), unsigned types make your intention clearer and catch errors earlier.
+
+```kotlin
+fun createUser(id: UInt) { /* ... */ }
+```
+
+✅ 5. Cryptography / Checksums / Hashes
+Crypto algorithms and checksums often rely on unsigned integer arithmetic.
+
+```kotlin
+val temperatureRaw: UShort = readSensor()
+```
+
+✅ 6. Embedded / IoT / Microcontroller Code
+For constrained environments or devices (like Arduino, STM32, etc.), values are usually unsigned and memory-efficient.
+
+```kotlin
+val temperatureRaw: UShort = readSensor()
+```
+
+✅ 7. Performance & Precision with Large Positive Numbers
+Sometimes you need the extra upper range — e.g. ULong gives you up to 2^64 - 1, while Long is capped at 2^63 - 1.
+
+```kotlin
+val bigCounter: ULong = 18_446_744_073_709_551_615u
+```
+
+A note of caution 🚧
+Kotlin’s unsigned types are not Java-compatible, meaning:
+
+You can't pass UInt directly to Java code (you’ll need to convert it to Int)
+
+Some standard library functions may not work the same way

src/main/kotlin/dev/shtanko/kotlinlang/types/unsigned/Unsigned.kt

@@ -0,0 +1,18 @@
+@file:OptIn(ExperimentalUnsignedTypes::class)
+
+package dev.shtanko.kotlinlang.types.unsigned
+
+fun unsignedBitwiseAnd(value: UByte = 0b10101010u): UByte {
+    val mask: UByte = 0b11110000u
+    return value and mask // no unexpected sign problems
+}
+
+fun buffers() {
+    val bytes: UByteArray = ubyteArrayOf(0xFFu, 0x01u, 0x7Fu)
+}
+
+/**
+ * Sometimes you need the extra upper range — e.g. ULong gives you up to 2^64 - 1,
+ * while Long is capped at 2^63 - 1.
+ */
+const val BIG_COUNTER: ULong = 18_446_744_073_709_551_615u // ULong.MAX_VALUE

src/test/kotlin/dev/shtanko/kotlinlang/types/unsigned/UnsignedTest.kt

@@ -0,0 +1,41 @@
+package dev.shtanko.kotlinlang.types.unsigned
+
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Nested
+import org.junit.jupiter.api.Test
+
+class UnsignedTest {
+
+    @Nested
+    inner class UnsignedBitwiseAndTest {
+        @Test
+        fun `unsignedBitwiseAnd with default value`() {
+            val result = unsignedBitwiseAnd()
+            assertEquals(0b10100000u.toUByte(), result)
+        }
+
+        @Test
+        fun `unsignedBitwiseAnd with all ones`() {
+            val result = unsignedBitwiseAnd(0b11111111u)
+            assertEquals(0b11110000u.toUByte(), result)
+        }
+
+        @Test
+        fun `unsignedBitwiseAnd with all zeros`() {
+            val result = unsignedBitwiseAnd(0b00000000u)
+            assertEquals(0b00000000u.toUByte(), result)
+        }
+
+        @Test
+        fun `unsignedBitwiseAnd with mixed bits`() {
+            val result = unsignedBitwiseAnd(0b01010101u)
+            assertEquals(0b01010000u.toUByte(), result)
+        }
+
+        @Test
+        fun `unsignedBitwiseAnd with different mixed bits`() {
+            val result = unsignedBitwiseAnd(0b10011001u)
+            assertEquals(0b10010000u.toUByte(), result)
+        }
+    }
+}