From c64df75cd59217fad33e797da97966bd3c43e41f Mon Sep 17 00:00:00 2001
From: rnentjes <info@nentjes.com>
Date: Fri, 13 Dec 2024 21:53:37 +0100
Subject: [PATCH] Add initial README for `typed-byte-arrays` library

Provide an overview of the library's purpose, usage, and functionality. This includes a Kotlin example of defining and using `TypedByteArray` and explanation of data types and properties. The README aims to help developers understand and adopt the library effectively.
---
 readme.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 readme.md

diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..35fb1cd
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,49 @@
+# typed-byte-arrays
+
+This is a small library to make working with byte arrays easier. 
+I developed this as an alternative to kotlin serialization which was cumbersome to use and much too slow for my use case.
+
+A TypeByteArray is a wrapper around a ByteArray that defines what bytes map to which property. This way there is only data conversion
+to convert the bytes to the property and back when the property is accessed. The data can be sent as the bytearray that it actually is.
+
+## Usage
+
+This is what a definition could look like:
+
+```kotlin
+class Person : TypedByteArray(
+  Type("id", DataType.LONG),
+  Type("name", DataType.STRING, 100),
+  Type("age", DataType.INT),
+  Type("rate", DataType.DOUBLE),
+  Type("description", DataType.CLOB, 100000)
+) {
+  var id by LongProperty("id")
+  var name by StringProperty("name")
+  var age by IntProperty("age")
+  var rate by DoubleProperty("rate")
+  var description by ClobProperty("description")
+  
+  constructor(name: String, age: Int) : this() {
+    this.name = name
+    this.age = age
+    this.rate = 1.0
+    this.description = "Nothing here yet."
+  }
+  
+  constructor(data: ByteArray): this() {
+    check(data.size == definition.size) {
+      "Invalid data size: ${data.size} != ${definition.size}"
+    }
+
+    this.data = MutableByteArrayHandler(data)
+  }
+}
+```
+
+The different between STRING and CLOB is the maximum size (32kb vs 2gb). For any type where the length isn't fixed we need to provide max size. 
+When for example a string is updated with a shorter string the remaining bytes are zeroed to make compression as efficient as possible.
+
+Strings are stored as UTF-8 bytes, there is also a CachedStringProperty which will keep a copy of the string so it isn't converted to a 
+native string every time it's accessed.
+