🎨 Improve buffer API

The initial position should also be an out parameter

Author: andersstorhaug

Lite3DotNet.Tests/AlignmentZeroingTests.cs

@@ -13,7 +13,7 @@ public void Can_zero_unaligned_bytes()
         // Fill buffer with non-zero garbage
         buffer.Fill(0xEE);
 
-        var position = Lite3.InitializeObject(buffer);
+        Lite3.InitializeObject(buffer, out var position);
 
         // Object insert adds 99 bytes: LITE3_NODE_SIZE (96) + "a" (size 2 including \0) + key_tag (size 1)
         // 1 padding byte is inserted to reach 100 bytes, for 4 byte alignment.
@@ -25,7 +25,7 @@ public void Can_zero_unaligned_bytes()
         // Reset buffer to garbage for second test
         buffer.Fill(0xEE);
 
-        position = Lite3.InitializeObject(buffer);
+        Lite3.InitializeObject(buffer, out position);
 
         // Object insert adds 112 bytes (LITE3_NODE_SIZE (96) + keyval (16))
         // key_tag(1) + "key1\0"(5) + val_tag(1) + str_len(4) + "val1\0"(5) = 16 bytes.

Lite3DotNet.Tests/BufferApiExamples.cs

@@ -22,7 +22,7 @@ public void Can_build_messages()
         var buffer = new byte[1024];
 
         // Build message
-        var position = Lite3.InitializeObject(buffer);
+        Lite3.InitializeObject(buffer, out var position);
         Lite3.SetString(buffer, ref position, 0, "event"u8, "lap_complete"u8);
         Lite3.SetLong(buffer, ref position, 0, "lap"u8, 55);
         Lite3.SetDouble(buffer, ref position, 0, "time_sec"u8, 88.427);
@@ -63,7 +63,7 @@ public void Can_read_messages()
         var buffer = new byte[1024];
 
         // Build Message
-        var position = Lite3.InitializeObject(buffer);
+        Lite3.InitializeObject(buffer, out var position);
         Lite3.SetString(buffer, ref position, 0, "title"u8, "C Programming Language, 2nd Edition"u8);
         Lite3.SetString(buffer, ref position, 0, "language"u8, "en"u8);
         Lite3.SetDouble(buffer, ref position, 0, "price_usd"u8, 60.30);
@@ -122,7 +122,7 @@ public void Can_work_with_strings()
         var buffer = new byte[1024];
 
         // Build message
-        var position = Lite3.InitializeObject(buffer);
+        Lite3.InitializeObject(buffer, out var position);
         Lite3.SetString(buffer, ref position, 0, "name"u8, "Maria"u8);
         Lite3.SetLong(buffer, ref position, 0, "age"u8, 24);
         Lite3.SetString(buffer, ref position, 0, "email"u8, "marie@example.com"u8);
@@ -155,7 +155,7 @@ public void Can_work_with_nesting()
         var buffer = new byte[1024];
 
         // Build message
-        var position = Lite3.InitializeObject(buffer);
+        Lite3.InitializeObject(buffer, out var position);
         Lite3.SetString(buffer, ref position, 0, "event"u8, "http_request"u8);
         Lite3.SetString(buffer, ref position, 0, "method"u8, "POST"u8);
         Lite3.SetLong(buffer, ref position, 0, "duration_ms"u8, 47);
@@ -183,7 +183,7 @@ public void Can_work_with_arrays()
     {
         var buffer = new byte[1024];
 
-        var position = Lite3.InitializeArray(buffer);
+        Lite3.InitializeArray(buffer, out var position);
         Lite3.ArrayAppendString(buffer, ref position, 0, "zebra"u8);
         Lite3.ArrayAppendString(buffer, ref position, 0, "giraffe"u8);
         Lite3.ArrayAppendString(buffer, ref position, 0, "buffalo"u8);
@@ -233,7 +233,7 @@ public void Can_use_iterators()
         var buffer = new byte[1024];
 
         // Build array
-        var position = Lite3.InitializeArray(buffer);
+        Lite3.InitializeArray(buffer, out var position);
 
         for (var i = 0; i < names.Count; i++)
         {

Lite3DotNet.Tests/CollisionsTests.cs

@@ -14,7 +14,7 @@ public void Can_handle_key_hash_collisions()
         var buffer = new byte[1024 * 64];
         var random = new Random(52073821);
 
-        var position = Lite3.InitializeObject(buffer);
+        Lite3.InitializeObject(buffer, out var position);
 
         const int keyLength = 2;
 

Lite3DotNet.Tests/JohnDoeTests.cs

@@ -10,8 +10,7 @@ public void Can_read_and_write_basic_data()
     {
         Span<byte> buffer = new byte[2048];
 
-        var position = Lite3.InitializeObject(buffer);
-
+        Lite3.InitializeObject(buffer, out var position);
         Lite3.SetLong(buffer, ref position, 0, "user_id"u8, 12345);
         Lite3.SetString(buffer, ref position, 0, "username"u8, "jdoe"u8);
         Lite3.SetString(buffer, ref position, 0, "email_address"u8, "jdoe@example.com"u8);

Lite3DotNet.Tests/TypeQueryTests.cs

@@ -14,7 +14,7 @@ public void Can_get_array_type_with_buffer_API()
         var buffer = new byte[2048];
 
         // Initialize as array
-        var position = Lite3.InitializeArray(buffer);
+        Lite3.InitializeArray(buffer, out var position);
 
         // Append various types
         Lite3.ArrayAppendString(buffer, ref position, 0, "hello"u8);
@@ -128,11 +128,11 @@ public void Can_get_root_type_with_buffer_API()
         var buffer = new byte[2048];
 
         // Test object root
-        Lite3.InitializeObject(buffer);
+        Lite3.InitializeObject(buffer, out _);
         Lite3.GetRootType(buffer).ShouldBe(Lite3Core.ValueKind.Object);
 
         // Test array root
-        Lite3.InitializeArray(buffer);
+        Lite3.InitializeArray(buffer, out _);
         Lite3.GetRootType(buffer).ShouldBe(Lite3Core.ValueKind.Array);
     }
 

Lite3DotNet/Lite3Core.C.cs

@@ -560,7 +560,7 @@ private static void InitializeImpl(Span<byte> buffer, int offset, ValueKind kind
     ///         <em>Ported from C <c>lite3_init_obj</c>.</em>
     ///     </para>
     /// </remarks>
-    [Lite3Api(ReturnArg = nameof(position))]
+    [Lite3Api]
     public static Status InitializeObject(Span<byte> buffer, out int position)
     {
         position = 0;
@@ -591,7 +591,7 @@ public static Status InitializeObject(Span<byte> buffer, out int position)
     ///         <em>Ported from C <c>lite3_init_arr</c>.</em>
     ///     </para>
     /// </remarks>
-    [Lite3Api(ReturnArg = nameof(position))]
+    [Lite3Api]
     public static Status InitializeArray(Span<byte> buffer, out int position)
     {
         position = 0;

README.md

@@ -35,7 +35,7 @@ The following example using the Buffer API outputs `Max Retries: 3`.
 ```csharp
 var buffer = new byte[1024];
 
-var position = Lite3.InitializeObject(buffer);
+Lite3.InitializeObject(buffer, out var position);
 Lite3.SetString(buffer, ref position, 0, "app_name"u8, "demo_app"u8);
 Lite3.SetLong(buffer, ref position, 0, "max_retries"u8, 3);
 Lite3.SetBool(buffer, ref position, 0, "debug_mode"u8, false);