tinybits 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4826141cb2aae8ecab56241a3b5cec14a7c40911cabd7aae971bcbde3a8248c
-  data.tar.gz: a87cd61d1aa59343b3c81e8dfd38554cbf590e78b18b3866d98e16f3f4a86cb5
+  metadata.gz: 51ab487694dc35eabde1bebda52a2726074ab6c80ef84ce2c845141c9732283c
+  data.tar.gz: 5c3b2c2eb52a15fb5e32d54c37d705fd41c9ec4759464519c599f83f517b9e2b
 SHA512:
-  metadata.gz: d67489ba3c2e4bdeb4ba7a458d4c70a61e766f10dc77282190e82e8f2dcef46b8f8c5d4de4ee551711229d42366b84d45ad08666abf49e24550adb5d99a94787
-  data.tar.gz: 592ed8e9367d428a3bc76994c8bcb91ef77793fd0c3f12beed21e0f08b6d1b5410b04408ad0e391eddc55b1beefd836e1b96e8ff0d64b160d3e035df96cf7425
+  metadata.gz: 65fd3c3a22a67d8a1a6a218644d4ed82171386202de0b09ce86c285501852cf40c71690820defbf811be66db29da6346d9e933878027377e1ac0c680c08cdf60
+  data.tar.gz: 6d389ea71dac6c417956d98dfe545f3baa015f2947ce968d9f8ec2f0dbe62ffdd5f841fb789658b00a69fe7975b8ed7788b1747a2867440fee10f0c19b05c243

data/ext/tinybits/test_date.rb

@@ -0,0 +1,37 @@
+require './tinybits_ext'
+
+packer = TinyBits::Packer.new
+unpacker = TinyBits::Unpacker.new
+
+t = [Time.now, nil, true, false]
+
+
+
+
+puts packer.dump(t).bytesize
+
+puts t
+puts t2 = unpacker.unpack(packer.pack(t))
+puts t == t2
+
+
+objects = [{"abc": 123}, {"abc": [1, 2, "abc"]}, ["xyz", "abc", "xyz", 7.6] ]
+
+puts "----------------"
+
+packer.reset
+
+objects.each do |obj|
+  puts packer << obj
+end
+
+buffer = packer.to_s
+
+puts buffer.bytesize
+
+unpacker.buffer = buffer
+
+while(value = unpacker.pop)
+  pp value
+  puts "+++++++++++++++++++++++++"
+end

data/ext/tinybits/tinybits.h

@@ -1,6 +1,6 @@
 /**
  * TinyBits Amalgamated Header
- * Generated on: Sat Apr 19 07:05:26 PM CEST 2025
+ * Generated on: Sat May  3 09:20:46 PM CEST 2025
  */
 
 #ifndef TINY_BITS_H
@@ -8,43 +8,49 @@
 
 /* Begin common.h */
 
-
 #include <stdint.h>
 #include <stdlib.h>
 #include <string.h>
 #include <stddef.h> // for size_t
 #include <math.h>
-
+#include <stdio.h>
 
 #define TB_HASH_SIZE 128
 #define TB_HASH_CACHE_SIZE 256
 #define MAX_BYTES 9
 #define TB_DDP_STR_LEN_MAX 128
 
-#define TB_INT_TAG 0x80
-#define TB_STR_TAG 0x40
-#define TB_STR_LEN 0x1F
-#define TB_REF_TAG 0x60
-#define TB_REF_LEN 0x1F
-#define TB_DBL_TAG 0x20
-#define TB_PFP_TAG 0x20
-#define TB_NFP_TAG 0x30
-#define TB_NAN_TAG 0x2D
-#define TB_INF_TAG 0x3D
-#define TB_NNF_TAG 0x2E
-#define TB_F16_TAG 0x3E
-#define TB_F32_TAG 0x2F
-#define TB_F64_TAG 0x3F
-#define TB_MAP_TAG 0x10
-#define TB_MAP_LEN 0x0F
-#define TB_ARR_TAG 0x08
-#define TB_ARR_LEN 0x07
-#define TB_SEP_TAG 0x05
-#define TB_EXT_TAG 0x04
-#define TB_BLB_TAG 0x03
-#define TB_NIL_TAG 0x02
-#define TB_TRU_TAG 0x01
-#define TB_FLS_TAG 0x00
+// main tags
+#define TB_INT_TAG 0x80     // +/- integer
+#define TB_REF_TAG 0x60     // deduped string
+#define TB_STR_TAG 0x40     // string
+#define TB_DBL_TAG 0x20     // double value
+#define TB_PFP_TAG 0x20     // + compressed double
+#define TB_NFP_TAG 0x30     // - compressed double
+#define TB_NAN_TAG 0x2D     // NaN
+#define TB_INF_TAG 0x3D     // Infinity
+#define TB_NNF_TAG 0x2E     // -Infinity
+#define TB_F16_TAG 0x3E     // f16 
+#define TB_F32_TAG 0x2F     // float (32bit)
+#define TB_F64_TAG 0x3F     // double (64bit)
+#define TB_MAP_TAG 0x10     // map { key: value}
+#define TB_ARR_TAG 0x08     // array [element1, element2]
+#define TB_DTM_TAG 0x07     // datetime
+#define TB_NXT_TAG 0x06     // native extensions (multibyte tags)
+#define TB_SEP_TAG 0x05     // separator (for group deduplication)
+#define TB_EXT_TAG 0x04     // extension (user extentions)
+#define TB_BLB_TAG 0x03     // blob
+#define TB_NIL_TAG 0x02     // NULL
+#define TB_TRU_TAG 0x01     // TRUE
+#define TB_FLS_TAG 0x00     // FALSE
+
+// Length values (for string, map & array)
+#define TB_STR_LEN 0x1F     // max embedded string length
+#define TB_REF_LEN 0x1F     // max embedded reference id
+#define TB_MAP_LEN 0x0F     // max embedded map length
+#define TB_ARR_LEN 0x07     // max embedded array length
+
+// native extensions TR_NXT_TAG
 
 // Feature flags (from encoder)
 #define TB_FEATURE_STRING_DEDUPE    0x01
@@ -358,6 +364,13 @@ static inline unsigned char *tiny_bits_packer_ensure_capacity(tiny_bits_packer *
     return encoder->buffer + encoder->current_pos;
 }
 
+/**
+ * @brief allocates and initializes a new packer
+ * 
+ * @return pointer to new packer instance
+ * 
+ * @note the returned packer object must be freed using tiny_bits_packer_destroy()
+ */
 tiny_bits_packer *tiny_bits_packer_create(size_t initial_capacity, uint8_t features) {
     tiny_bits_packer *encoder = (tiny_bits_packer *)malloc(sizeof(tiny_bits_packer));
     if (!encoder) return NULL;
@@ -393,6 +406,13 @@ tiny_bits_packer *tiny_bits_packer_create(size_t initial_capacity, uint8_t featu
     return encoder;
 }
 
+/**
+ * @brief Resets internal data structure of the packer object
+ * 
+ * @param encoder The packer instance
+ *
+ * @note This function allows for more efficient packing by reusing the same packer object
+ */
 inline void tiny_bits_packer_reset(tiny_bits_packer *encoder) {
     if (!encoder) return;
     encoder->current_pos = 0;  
@@ -404,6 +424,12 @@ inline void tiny_bits_packer_reset(tiny_bits_packer *encoder) {
     
 }
 
+/**
+ * @brief Deallocate the packer object and its internal data structures
+ * 
+ * @param encoder The unpacker instance
+ *
+ */
 void tiny_bits_packer_destroy(tiny_bits_packer *encoder) {
     if (!encoder) return;
     
@@ -414,6 +440,15 @@ void tiny_bits_packer_destroy(tiny_bits_packer *encoder) {
     free(encoder);
 }
 
+/**
+ * @brief Packs an array header into the buffer
+ * 
+ * @param encoder Pointer to the packer instance
+ * @param arr_len Number of elements in the array
+ * @return Number of bytes written, or 0 on error
+ * 
+ * @note This function only writes the array header, not the elements themselves
+ */
 static inline int pack_arr(tiny_bits_packer *encoder, int arr_len){
     int written = 0;
     int needed_size;
@@ -439,6 +474,15 @@ static inline int pack_arr(tiny_bits_packer *encoder, int arr_len){
     return written;
 }
 
+/**
+ * @brief Packs a map header into the buffer
+ * 
+ * @param encoder Pointer to the packer instance
+ * @param map_len Number of key-value pairs in the map
+ * @return Number of bytes written, or 0 on error
+ * 
+ * @note This function only writes the map header, not the key-value pairs themselves
+ */
 static inline int pack_map(tiny_bits_packer *encoder, int map_len){
     int written = 0;
     int needed_size;
@@ -464,6 +508,15 @@ static inline int pack_map(tiny_bits_packer *encoder, int map_len){
     return written;
 }
 
+/**
+ * @brief Packs an integer value into the buffer
+ * 
+ * @param encoder Pointer to the packer instance
+ * @param value The integer value to pack
+ * @return Number of bytes written, or 0 on error
+ * 
+ * @note Uses a compact representation for small values and SQLite4 like integer encoding for larger values
+ */
 static inline int pack_int(tiny_bits_packer *encoder, int64_t value){
     int written = 0;
     int needed_size = 10;
@@ -494,66 +547,95 @@ static inline int pack_int(tiny_bits_packer *encoder, int64_t value){
     return written;
 }
 
-static inline int pack_null(tiny_bits_packer *encoder){
-    int needed_size = 1;
-    uint8_t *buffer = tiny_bits_packer_ensure_capacity(encoder, needed_size);
+static inline int _pack_tag_only(tiny_bits_packer *encoder, uint8_t tag){
+    uint8_t *buffer = tiny_bits_packer_ensure_capacity(encoder, 1);
     if (!buffer) return 0; // Handle error
-
-    buffer[0] = (uint8_t)TB_NIL_TAG;
+    buffer[0] = tag;
     encoder->current_pos += 1;
     return 1;
+
 }
 
-static inline int pack_true(tiny_bits_packer *encoder){
-    int needed_size = 1;
-    uint8_t *buffer = tiny_bits_packer_ensure_capacity(encoder, needed_size);
-    if (!buffer) return 0; // Handle error
+/**
+ * @brief Packs a separator tag into the buffer
+ * 
+ * @param encoder Pointer to the packer instance
+ * @return Number of bytes written, or 0 on error
+ */
+static inline int pack_separator(tiny_bits_packer *encoder){
+    return _pack_tag_only(encoder, (uint8_t)TB_SEP_TAG);
+}
 
-    buffer[0] = (uint8_t)TB_TRU_TAG;
-    encoder->current_pos += 1;
-    return 1;
+/**
+ * @brief Packs a NULL value into the buffer
+ * 
+ * @param encoder Pointer to the packer instance
+ * @return Number of bytes written, or 0 on error
+ */
+static inline int pack_null(tiny_bits_packer *encoder){
+    return _pack_tag_only(encoder, (uint8_t)TB_NIL_TAG);
 }
 
-static inline int pack_false(tiny_bits_packer *encoder){
-    int needed_size = 1;
-    uint8_t *buffer = tiny_bits_packer_ensure_capacity(encoder, needed_size);
-    if (!buffer) return 0; // Handle error
+/**
+ * @brief Packs a TRUE boolean value into the buffer
+ * 
+ * @param encoder Pointer to the packer instance
+ * @return Number of bytes written, or 0 on error
+ */
+static inline int pack_true(tiny_bits_packer *encoder){
+    return _pack_tag_only(encoder, (uint8_t)TB_TRU_TAG);
+}
 
-    buffer[0] = (uint8_t)TB_FLS_TAG;
-    encoder->current_pos += 1;
-    return 1;
+/**
+ * @brief Packs a FALSE boolean value into the buffer
+ * 
+ * @param encoder Pointer to the packer instance
+ * @return Number of bytes written, or 0 on error
+ */
+static inline int pack_false(tiny_bits_packer *encoder){
+    return _pack_tag_only(encoder, (uint8_t)TB_FLS_TAG);
 }
 
+/**
+ * @brief Packs a NaN (Not a Number) value into the buffer
+ * 
+ * @param encoder Pointer to the packer instance
+ * @return Number of bytes written, or 0 on error
+ */
 static inline int pack_nan(tiny_bits_packer *encoder){
-    int needed_size = 1;
-    uint8_t *buffer = tiny_bits_packer_ensure_capacity(encoder, needed_size);
-    if (!buffer) return 0; // Handle error
-
-    buffer[0] = (uint8_t)TB_NAN_TAG;
-    encoder->current_pos += 1;
-    return 1;
+    return _pack_tag_only(encoder, (uint8_t)TB_NAN_TAG);
 }
 
+/**
+ * @brief Packs a positive infinity value into the buffer
+ * 
+ * @param encoder Pointer to the packer instance
+ * @return Number of bytes written, or 0 on error
+ */
 static inline int pack_infinity(tiny_bits_packer *encoder){
-    int needed_size = 1;
-    uint8_t *buffer = tiny_bits_packer_ensure_capacity(encoder, needed_size);
-    if (!buffer) return 0; // Handle error
-
-    buffer[0] = (uint8_t)TB_INF_TAG;
-    encoder->current_pos += 1;
-    return 1;
+    return _pack_tag_only(encoder, (uint8_t)TB_INF_TAG);
 }
 
+/**
+ * @brief Packs a negative infinity value into the buffer
+ * 
+ * @param encoder Pointer to the packer instance
+ * @return Number of bytes written, or 0 on error
+ */
 static inline int pack_negative_infinity(tiny_bits_packer *encoder){
-    int needed_size = 1;
-    uint8_t *buffer = tiny_bits_packer_ensure_capacity(encoder, needed_size);
-    if (!buffer) return 0; // Handle error
-
-    buffer[0] = (uint8_t)TB_NNF_TAG;
-    encoder->current_pos += 1;
-    return 1;
+    return _pack_tag_only(encoder, (uint8_t)TB_NNF_TAG);
 }
 
+/**
+ * @brief Packs a string into the buffer
+ * 
+ * @param encoder Pointer to the packer instance
+ * @param str Pointer to the string data
+ * @param str_len Length of the string in bytes
+ * @return Number of bytes written, or 0 on error
+ * 
+ * @note If string deduplication is enabled, this may store a reference to a previously stored string
+ */
 static inline int pack_str(tiny_bits_packer *encoder, char* str, uint32_t str_len) {
     uint32_t id = 0;
     int found = 0;
@@ -632,10 +714,29 @@ static inline int pack_str(tiny_bits_packer *encoder, char* str, uint32_t str_le
     return written;
 }
 
+/**
+ * @brief Packs a double-precision floating point value into the buffer
+ * 
+ * @param encoder Pointer to the packer instance
+ * @param val The double value to pack
+ * @return Number of bytes written, or 0 on error
+ * 
+ * @note If TB_FEATURE_COMPRESS_FLOATS is enabled, this will use a more compact representation for some values
+ */
 static inline int pack_double(tiny_bits_packer *encoder, double val) {
     int written = 0;
     uint8_t *buffer = tiny_bits_packer_ensure_capacity(encoder, 10);
     if (!buffer) return 0;
+    if(isnan(val)){
+      return pack_nan(encoder);
+    } 
+    if(isinf(val)){
+      if(val > 0){
+        return pack_infinity(encoder);
+      } else {
+        return pack_negative_infinity(encoder);
+      }
+    }
     // scaled varint encoding
     if (encoder->features & TB_FEATURE_COMPRESS_FLOATS) {
         double abs_val = fabs(val); ///val >= 0 ? val : -val;
@@ -667,6 +768,37 @@ static inline int pack_double(tiny_bits_packer *encoder, double val) {
     return written;
 }
 
+/**
+ * @brief Packs a unixtime double-precision floating point value, along with a time zone offset into the buffer
+ * 
+ * @param encoder Pointer to the packer instance
+ * @param val The unixtime double value to pack
+ * @param offset The timezone offset (as a +/- seconds)
+ * @return Number of bytes written, or 0 on error
+ * 
+ */
+static inline int pack_datetime(tiny_bits_packer *encoder, double val, int16_t offset) {
+    int written = 0;
+    uint8_t *buffer = tiny_bits_packer_ensure_capacity(encoder, 11);
+    if (!buffer) return 0;
+    buffer[0] = TB_DTM_TAG;
+    buffer[1] = (int8_t) ((offset % 86400) / (60*15)); // convert seconds to multiples of 15 minutes
+    written += 2;
+    encode_uint64(dtoi_bits(val), buffer + written);
+    written += 8;
+    encoder->current_pos += written;
+    //written += pack_double(encoder, val);
+    return written;
+}
+
+/**
+ * @brief Packs a binary blob (byte array) into the buffer
+ * 
+ * @param encoder Pointer to the packer instance
+ * @param blob Pointer to the binary data
+ * @param blob_size Size of the binary data in bytes
+ * @return Number of bytes written, or 0 on error
+ */
 static inline int pack_blob(tiny_bits_packer *encoder, const char* blob, int blob_size){
     int written = 0;
     int needed_size;
@@ -697,19 +829,22 @@ enum tiny_bits_type {
     TINY_BITS_MAP,      // length: number of key-value pairs
     TINY_BITS_INT,      // int_val: integer value
     TINY_BITS_DOUBLE,   // double_val: double value
-    TINY_BITS_STR,      // length: byte length of string
-    TINY_BITS_BLOB,     // length: byte length of blob
+    TINY_BITS_STR,      // str_blob_val.length: byte length of string, str_blob_val.data: pointer to string
+    TINY_BITS_BLOB,     // str_blob_val.length: byte length of blob, str_blob_val.data: pointer to blob
     TINY_BITS_TRUE,     // No value
     TINY_BITS_FALSE,    // No value
     TINY_BITS_NULL,     // No value
-    TINY_BITS_NAN,     // No value
-    TINY_BITS_INF,     // No value
-    TINY_BITS_N_INF,     // No value
-    TINY_BITS_EXT,     // No value
+    TINY_BITS_NAN,      // No value
+    TINY_BITS_INF,      // No value
+    TINY_BITS_N_INF,    // No value
+    TINY_BITS_EXT,      // No value
+    TINY_BITS_SEP,      // No balue
     TINY_BITS_FINISHED, // End of buffer
-    TINY_BITS_ERROR     // Parsing error
+    TINY_BITS_ERROR,     // Parsing error
+    TINY_BITS_DATETIME   // double_val: double value
 };
 
+// value union
 typedef union tiny_bits_value {
     int64_t int_val;    // TINY_BITS_INT
     double double_val;  // TINY_BITS_DOUBLE
@@ -719,8 +854,13 @@ typedef union tiny_bits_value {
         size_t length;
         int32_t id;
     } str_blob_val;
+    struct {            // TINY_BITS_STR, TINY_BITS_BLOB
+        double unixtime;
+        size_t offset;
+    } datetime_val;   
 } tiny_bits_value;
 
+// The unpacker data structure
 typedef struct tiny_bits_unpacker {
     const unsigned char *buffer;  // Input buffer (read-only)
     size_t size;                  // Total size of buffer
@@ -734,6 +874,13 @@ typedef struct tiny_bits_unpacker {
     HashTable dictionary;
 } tiny_bits_unpacker;
 
+/**
+ * @brief allocates and initializes a new unpacker
+ * 
+ * @return pointer to new unpacker instance
+ * 
+ * @note the returned unpacker object must be freed using tiny_bits_unpacker_destroy()
+ */
 tiny_bits_unpacker *tiny_bits_unpacker_create(void) {
 
     tiny_bits_unpacker *decoder = (tiny_bits_unpacker *)malloc(sizeof(tiny_bits_unpacker));
@@ -749,7 +896,18 @@ tiny_bits_unpacker *tiny_bits_unpacker_create(void) {
     return decoder;
 }
 
-void tiny_bits_unpacker_set_buffer(tiny_bits_unpacker *decoder, const unsigned char *buffer, size_t size) {
+/**
+ * @breif Provides a buffer to the unpacker for unpacking
+ * 
+ * @param decoder The unpakcer instance
+ *
+ * @param buffer A pointer to the buffer
+ *
+ * @param size Size of the region to be unpacked
+ *
+ * @note This function implicitly resets the unpacker object so no need to call tiny_bits_unpacker_reset()
+ */
+static inline void tiny_bits_unpacker_set_buffer(tiny_bits_unpacker *decoder, const unsigned char *buffer, size_t size) {
     if (!decoder) return;
     if (!buffer || size < 1) return;
     decoder->buffer = buffer;
@@ -758,12 +916,26 @@ void tiny_bits_unpacker_set_buffer(tiny_bits_unpacker *decoder, const unsigned c
     decoder->strings_count = 0;
 }
 
+/**
+ * @brief Resets internal data structure of the unpacker object
+ * 
+ * @param decoder The unpacker instance
+ *
+ * @note This function is useful if you want to operate on the same buffer again for some reason
+ */
 static inline void tiny_bits_unpacker_reset(tiny_bits_unpacker *decoder) {
     if (!decoder) return;
     decoder->current_pos = 0;
     decoder->strings_count = 0;
 }
 
+
+/**
+ * @brief Deallocate the unpacker object and its internal data structures
+ * 
+ * @param decoder The unpacker instance
+ *
+ */
 void tiny_bits_unpacker_destroy(tiny_bits_unpacker *decoder) {
     if (!decoder) return;
     if (decoder->strings) {
@@ -833,6 +1005,19 @@ static inline enum tiny_bits_type _unpack_double(tiny_bits_unpacker *decoder, ui
         return TINY_BITS_DOUBLE;
 }
 
+static inline enum tiny_bits_type _unpack_datetime(tiny_bits_unpacker *decoder, uint8_t tag, tiny_bits_value *value){
+    size_t pos = decoder->current_pos;
+    value->datetime_val.offset = decoder->buffer[pos] * (60*15); // convert offset back to seconds (from multiples of 15 minutes)
+    //uint8_t dbl_tag = decoder->buffer[decoder->current_pos++];
+    //tiny_bits_value dbl_val;
+    //_unpack_double(decoder, dbl_tag, &dbl_val);
+    //value->datetime_val.unixtime = dbl_val.double_val;
+    uint64_t unixtime = decode_uint64(decoder->buffer + pos + 1);
+    value->datetime_val.unixtime = itod_bits(unixtime);
+    decoder->current_pos += 9;
+    return TINY_BITS_DATETIME;
+}
+
 static inline enum tiny_bits_type _unpack_blob(tiny_bits_unpacker *decoder, uint8_t tag, tiny_bits_value *value){
         size_t pos = decoder->current_pos;
         size_t len = decode_varint(decoder->buffer, decoder->size, &pos);
@@ -884,13 +1069,51 @@ static inline enum tiny_bits_type _unpack_str(tiny_bits_unpacker *decoder, uint8
         return TINY_BITS_STR;
 }
 
+/**
+ * @brief Unpacks a value and returns its type while setting its value
+ *
+ * @param decoder The unpacker instance
+ * @param[out] value A supplied tiny_bits_value instance
+ * 
+ * @return enum tiny_bits_type
+ *
+ * This is the entry point to unpacking tinybits structures. You keep calling
+ * this method repeatedly until it returns TINY_BITS_FINISHED when it reaches end of buffer
+ * or if it returns TINY_BITS_ERROR if it stumbles on a malformed or unknown structure.
+ *
+ * TINY_BITS_SEP means the current object was fully unpacked, and that there is potentially another one
+ * this is specifically for stream unpacking multiple objects one after the other as they are being recieved 
+ *
+ * The location of the value you need in the value union will depend on the returned type as follows
+ * 
+ * TINY_BITS_TRUE, TINY_BITS_FALSE, TINY_BITS_NULL, TINY_BITS_NAN, TINY_BITS_INF & TINY_BITS_N_INF all
+ * don't set the value, the type itself is sufficient information for client code to reconstruct the value.
+ *
+ * TINY_BITS_INT sets value.int_val
+ *
+ * TINY_BITS_DOUBLE sets value.double_val
+ *
+ * TINY_BITS_ARRAY and TINY_BITS_MAP both set value.length, for TINY_BITS_ARRAY it means the number of entries,
+ * for TINY_BITS_MAP it means the number of key/value pairs. You have to keep calling unpac_value() afterwards to 
+ * get all the members of the stored array/map. Please note that tinybits doesn't do size checks on the elements supplied
+ * during packing of arrays/maps. It is the responsibility of client code to ensure a 3 element array actually packs 3 elements.
+ * 
+ * TINY_BITS_STR & TINY_BITS_BLOB both set the value.str_blob_val struct, which has two members, data, a pointer to the string/blob in the buffer and
+ * length. Since some returned strings might be deduplicated, they will return the same data pointer and length value for their other instances, there is also an id
+ * value in the struct, which will be only set for strings. You can use to quickly determine the state of the strings as follows
+ * 
+ * A positive value means the string is a duplicate of a previous string, speficially a duplicate of the (id-1)th unpacked, deduplicatable string
+ * 
+ * A negative value means the sting is not a duplicate but is deduplicatable
+ *
+ * A zero value means the string is not deduplicatable and no duplicates should be expected (this is a heuristic, as duplicates may still exist)
+ */
 static inline enum tiny_bits_type unpack_value(tiny_bits_unpacker *decoder, tiny_bits_value *value) {
     if (!decoder || !value || decoder->current_pos >= decoder->size) {
         return (decoder && decoder->current_pos >= decoder->size) ? TINY_BITS_FINISHED : TINY_BITS_ERROR;
     }
 
     uint8_t tag = decoder->buffer[decoder->current_pos++];
-    //printf("found tag %X\n", tag);
     // Dispatch based on tag
     if ((tag & TB_INT_TAG) == TB_INT_TAG) { // Integers
         return _unpack_int(decoder, tag, value);
@@ -912,12 +1135,17 @@ static inline enum tiny_bits_type unpack_value(tiny_bits_unpacker *decoder, tiny
         return _unpack_arr(decoder, tag, value);
     } else if (tag == TB_BLB_TAG) { // Blob
         return _unpack_blob(decoder, tag, value);
+    } else if (tag == TB_DTM_TAG) {
+        return _unpack_datetime(decoder, tag, value);
+    } else if (tag == TB_SEP_TAG) {
+        return TINY_BITS_SEP;
+    } else if (tag == TB_EXT_TAG) {
+        return TINY_BITS_EXT;
     } else if (tag == TB_TRU_TAG) {
         return TINY_BITS_TRUE;
     } else if (tag == TB_FLS_TAG) {
         return TINY_BITS_FALSE;
     }
-    //printf("UNKOWN TAG\n");
     return TINY_BITS_ERROR; // Unknown tag
 }
 

data/ext/tinybits/tinybits_ext.c

@@ -127,6 +127,11 @@ static inline int pack_ruby_object_recursive(tiny_bits_packer* packer, VALUE obj
             return pack_str(packer, RSTRING_PTR(str), RSTRING_LEN(str));
         }
         default:
+            if(rb_obj_is_kind_of(obj, rb_cTime)){
+                double unixtime = NUM2DBL(rb_funcall(obj, rb_intern("to_f"), 0));
+                return pack_datetime(packer, unixtime, FIX2INT(rb_time_utc_offset(obj)));    
+            }
+            //printf("Unsupported type encountered during packing: %s", rb_obj_classname(obj));
             rb_warn("Unsupported type encountered during packing: %s", rb_obj_classname(obj));
             return 0;
     }
@@ -160,6 +165,65 @@ static VALUE rb_pack(VALUE self, VALUE obj) {
     return result;
 }
 
+static VALUE rb_push(VALUE self, VALUE obj) {
+    PackerData* packer_data;
+    TypedData_Get_Struct(self, PackerData, &packer_data_type, packer_data);
+
+    if (!packer_data->packer) {
+        rb_raise(rb_eRuntimeError, "Packer not initialized");
+    }
+
+    size_t initial_pos = packer_data->packer->current_pos;
+
+    HashIterContext context;
+    context.packer = packer_data->packer;        // Pass the current packer
+    context.error_occurred = 0;   // Initialize error flag
+
+    
+    if(initial_pos > 0){
+       if(!pack_separator(packer_data->packer)){
+            rb_raise(rb_eRuntimeError, "Failed to pack object (multi-object packing error)");
+       } 
+    }
+    
+    // Call the optimized recursive function
+    if (!pack_ruby_object_recursive(packer_data->packer, obj, (VALUE)&context)) {
+        // Error occurred during packing (might be unsupported type or tiny_bits error)
+        rb_raise(rb_eRuntimeError, "Failed to pack object (unsupported type or packing error)");
+    }
+
+    return INT2FIX(packer_data->packer->current_pos - initial_pos);
+}
+
+static VALUE rb_to_s(VALUE self){
+    PackerData* packer_data;
+    TypedData_Get_Struct(self, PackerData, &packer_data_type, packer_data);
+
+    if (!packer_data->packer) {
+        rb_raise(rb_eRuntimeError, "Packer not initialized");
+    }
+
+    if(packer_data->packer->current_pos == 0){
+        return rb_str_new("", 0);
+    }
+    VALUE result = rb_str_new((const char*)packer_data->packer->buffer, packer_data->packer->current_pos);
+    rb_obj_freeze(result);
+    return result;
+}
+
+static VALUE rb_reset(VALUE self){
+    PackerData* packer_data;
+    TypedData_Get_Struct(self, PackerData, &packer_data_type, packer_data);
+
+
+    if (!packer_data->packer) {
+        rb_raise(rb_eRuntimeError, "Packer not initialized");
+    }
+
+    // Reset before packing (assuming this is efficient)
+    tiny_bits_packer_reset(packer_data->packer);
+    return self;
+}
 
 // Unpacker structure
 typedef struct {
@@ -271,10 +335,13 @@ static VALUE unpack_ruby_object(UnpackerData* unpacker_data, size_t interned) {
             return hash;
         }
         case TINY_BITS_BLOB:
-            // For simplicity, treat blobs as strings (similar to strings)
+            // For smplicity, treat blobs as strings (similar to strings)
             VALUE blob = rb_str_new(value.str_blob_val.data, value.str_blob_val.length);
             rb_obj_freeze(blob);
             return blob;
+        case TINY_BITS_DATETIME:
+            VALUE time = rb_time_num_new(DBL2NUM(value.datetime_val.unixtime), INT2FIX(((int16_t)value.datetime_val.offset)));
+            return time;
         default:
             return Qundef; // Error
     }
@@ -300,6 +367,81 @@ static VALUE rb_unpack(VALUE self, VALUE buffer) {
     return result;
 }
 
+static VALUE rb_set_buffer(VALUE self, VALUE buffer){
+    UnpackerData* unpacker_data;
+    TypedData_Get_Struct(self, UnpackerData, &unpacker_data_type, unpacker_data);
+
+    if (!unpacker_data->unpacker) {
+        rb_raise(rb_eRuntimeError, "Unpacker not initialized");
+    }
+
+    StringValue(buffer); // Ensure it's a string
+
+    tiny_bits_unpacker_set_buffer(unpacker_data->unpacker, (const unsigned char*)RSTRING_PTR(buffer), RSTRING_LEN(buffer));
+
+    // set the buffer as an instance variable to mainatin a reference to it
+    rb_iv_set(self, "@buffer", buffer);
+
+    return self;
+}
+
+static VALUE rb_pop(VALUE self) {
+
+    VALUE buffer = rb_iv_get(self, "@buffer");
+    if(buffer == Qnil){
+        rb_raise(rb_eRuntimeError, "No buffer is set");
+    }
+
+    UnpackerData* unpacker_data;
+    TypedData_Get_Struct(self, UnpackerData, &unpacker_data_type, unpacker_data);
+
+    if (!unpacker_data->unpacker) {
+        rb_raise(rb_eRuntimeError, "Unpacker not initialized");
+    }
+
+    tiny_bits_unpacker* unpacker = unpacker_data->unpacker;
+    tiny_bits_value value;
+
+    if(unpacker->current_pos >= unpacker->size - 1){
+        return Qnil;
+    }
+    
+    if(unpacker->current_pos > 0){
+        enum tiny_bits_type type = unpack_value(unpacker, &value);
+        if(type != TINY_BITS_SEP){
+            rb_raise(rb_eRuntimeError, "Malformed multi-object buffer");
+        }
+    }
+    
+    VALUE result = unpack_ruby_object(unpacker_data, 0);
+    if (result == Qundef) {
+        rb_raise(rb_eRuntimeError, "Failed to unpack data");
+    }
+
+    return result;
+}
+
+static VALUE rb_finished(VALUE self){
+    VALUE buffer = rb_iv_get(self, "@buffer");
+    if(buffer == Qnil){
+        rb_raise(rb_eRuntimeError, "No buffer is set");
+    }
+    UnpackerData* unpacker_data;
+    TypedData_Get_Struct(self, UnpackerData, &unpacker_data_type, unpacker_data);
+
+    if (!unpacker_data->unpacker) {
+        rb_raise(rb_eRuntimeError, "Unpacker not initialized");
+    }
+
+    tiny_bits_unpacker* unpacker = unpacker_data->unpacker;
+
+    if(unpacker->current_pos >= (unpacker->size - 1)){
+        return Qtrue;
+    }
+
+    return Qfalse;
+}
+
 void Init_tinybits_ext(void) {
     rb_mTinyBits = rb_define_module("TinyBits");
     rb_cPacker = rb_define_class_under(rb_mTinyBits, "Packer", rb_cObject);
@@ -308,8 +450,19 @@ void Init_tinybits_ext(void) {
     rb_define_alloc_func(rb_cPacker, rb_packer_alloc);
     rb_define_method(rb_cPacker, "initialize", rb_packer_init, 0);
     rb_define_method(rb_cPacker, "pack", rb_pack, 1);
+    rb_define_alias(rb_cPacker, "encode", "pack");
+    rb_define_alias(rb_cPacker, "dump", "pack");
+    rb_define_method(rb_cPacker, "push", rb_push, 1);
+    rb_define_alias(rb_cPacker, "<<", "push");
+    rb_define_method(rb_cPacker, "to_s", rb_to_s, 0);
+    rb_define_method(rb_cPacker, "reset", rb_reset, 0);
 
     rb_define_alloc_func(rb_cUnpacker, rb_unpacker_alloc);
     rb_define_method(rb_cUnpacker, "initialize", rb_unpacker_init, 0);
     rb_define_method(rb_cUnpacker, "unpack", rb_unpack, 1);
+    rb_define_alias(rb_cUnpacker, "load", "unpack");
+    rb_define_alias(rb_cUnpacker, "decode", "unpack");
+    rb_define_method(rb_cUnpacker, "buffer=", rb_set_buffer, 1);
+    rb_define_method(rb_cUnpacker, "pop", rb_pop, 0);
+    rb_define_method(rb_cUnpacker, "finished?", rb_finished, 0);
 }

data/lib/tinybits/version.rb

@@ -1,3 +1,3 @@
 module TinyBits
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.2.0'.freeze
 end

data/lib/tinybits.rb

@@ -1,4 +1,7 @@
 require_relative './tinybits/version'
 require 'tinybits_ext'
 
-
+module TinyBits
+  def self.pack(object) = Packer.new.pack(object)
+  def self.unpack(buffer) = Unpacker.new.unpack(buffer)
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: tinybits
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Mohamed Hassan
 bindir: bin
 cert_chain: []
-date: 2025-04-20 00:00:00.000000000 Z
+date: 2025-05-03 00:00:00.000000000 Z
 dependencies: []
 description: TinyBits is a Ruby gem that wraps the TinyBits C serializartion library,
   offering Rubyists the power of serializion with intger/float compression and string
@@ -19,6 +19,7 @@ extensions:
 extra_rdoc_files: []
 files:
 - ext/tinybits/extconf.rb
+- ext/tinybits/test_date.rb
 - ext/tinybits/tinybits.h
 - ext/tinybits/tinybits_ext.c
 - lib/tinybits.rb