dynamic_string.h

Go to the documentation of this file.

 
#ifndef DYNAMIC_STRING_H
#define DYNAMIC_STRING_H
 
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
 
// Configuration macros (user can override before including)
#ifndef DS_MALLOC
#define DS_MALLOC malloc
#endif
 
#ifndef DS_REALLOC
#define DS_REALLOC realloc
#endif
 
#ifndef DS_FREE
#define DS_FREE free
#endif
 
#ifndef DS_ASSERT
#include <assert.h>
#define DS_ASSERT assert
#endif
 
#ifndef DS_ATOMIC_REFCOUNT
#define DS_ATOMIC_REFCOUNT 0
#endif
 
// API macros
#ifdef DS_STATIC
#define DS_DEF static
#else
#define DS_DEF extern
#endif
 
/* Check C11 support for atomic operations */
#if DS_ATOMIC_REFCOUNT && __STDC_VERSION__ < 201112L
    #error "DS_ATOMIC_REFCOUNT requires C11 or later for atomic support (compile with -std=c11 or later)"
#endif
 
/* atomic operations */
#if DS_ATOMIC_REFCOUNT
    #include <stdatomic.h>
    #define DS_ATOMIC_SIZE_T _Atomic size_t
    #define DS_ATOMIC_FETCH_ADD(ptr, val) atomic_fetch_add(ptr, val)
    #define DS_ATOMIC_FETCH_SUB(ptr, val) atomic_fetch_sub(ptr, val)
    #define DS_ATOMIC_LOAD(ptr) atomic_load(ptr)
    #define DS_ATOMIC_STORE(ptr, val) atomic_store(ptr, val)
#else
    #define DS_ATOMIC_SIZE_T size_t
    #define DS_ATOMIC_FETCH_ADD(ptr, val) (*(ptr) += (val), *(ptr) - (val))
    #define DS_ATOMIC_FETCH_SUB(ptr, val) (*(ptr) -= (val), *(ptr) + (val))
    #define DS_ATOMIC_LOAD(ptr) (*(ptr))
    #define DS_ATOMIC_STORE(ptr, val) (*(ptr) = (val))
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
// ============================================================================
// INTERFACE
// ============================================================================
 
typedef char* ds_string;
 
DS_DEF ds_string ds_new(const char* text);
 
DS_DEF ds_string ds_create_length(const char* text, size_t length);
 
DS_DEF ds_string ds_retain(ds_string str);
 
DS_DEF void ds_release(ds_string* str);
 
// String operations (return new strings - immutable)
 
DS_DEF ds_string ds_append(ds_string str, const char* text);
 
DS_DEF ds_string ds_append_char(ds_string str, uint32_t codepoint);
 
DS_DEF ds_string ds_prepend(ds_string str, const char* text);
 
DS_DEF ds_string ds_insert(ds_string str, size_t index, const char* text);
 
DS_DEF ds_string ds_substring(ds_string str, size_t start, size_t len);
 
// String concatenation
 
DS_DEF ds_string ds_concat(ds_string a, ds_string b);
 
DS_DEF ds_string ds_join(ds_string* strings, size_t count, const char* separator);
 
// Utility functions (read-only)
DS_DEF size_t ds_length(ds_string str);
 
DS_DEF int ds_compare(ds_string a, ds_string b);
 
DS_DEF int ds_compare_ignore_case(ds_string a, ds_string b);
 
DS_DEF size_t ds_hash(ds_string str);
 
DS_DEF int ds_find(ds_string str, const char* needle);
 
DS_DEF int ds_find_last(ds_string str, const char* needle);
 
DS_DEF int ds_contains(ds_string str, const char* needle);
 
DS_DEF int ds_starts_with(ds_string str, const char* prefix);
 
DS_DEF int ds_ends_with(ds_string str, const char* suffix);
 
// String transformation functions
DS_DEF ds_string ds_trim(ds_string str);
 
DS_DEF ds_string ds_trim_left(ds_string str);
 
DS_DEF ds_string ds_trim_right(ds_string str);
 
// String replacement and manipulation
DS_DEF ds_string ds_replace(ds_string str, const char* old, const char* new);
 
DS_DEF ds_string ds_replace_all(ds_string str, const char* old, const char* new);
 
// Case transformation
DS_DEF ds_string ds_to_upper(ds_string str);
 
DS_DEF ds_string ds_to_lower(ds_string str);
 
// Utility transformations
DS_DEF ds_string ds_repeat(ds_string str, size_t times);
 
DS_DEF ds_string ds_truncate(ds_string str, size_t max_length, const char* ellipsis);
 
DS_DEF ds_string ds_reverse(ds_string str);
 
DS_DEF ds_string ds_pad_left(ds_string str, size_t width, char pad);
 
DS_DEF ds_string ds_pad_right(ds_string str, size_t width, char pad);
 
// String splitting
DS_DEF ds_string* ds_split(ds_string str, const char* delimiter, size_t* count);
 
DS_DEF void ds_free_split_result(ds_string* array, size_t count);
 
// String formatting
DS_DEF ds_string ds_format(const char* fmt, ...);
 
DS_DEF ds_string ds_format_v(const char* fmt, va_list args);
 
DS_DEF ds_string ds_escape_json(ds_string str);
 
DS_DEF ds_string ds_unescape_json(ds_string str);
 
// Reference count inspection
DS_DEF size_t ds_refcount(ds_string str);
 
DS_DEF int ds_is_shared(ds_string str);
 
DS_DEF int ds_is_empty(ds_string str);
 
// Unicode codepoint iteration (Rust-style)
typedef struct {
    const char* data;
    size_t pos; // Current byte position
    size_t end; // End byte position
} ds_codepoint_iter;
 
DS_DEF ds_codepoint_iter ds_codepoints(ds_string str);
 
DS_DEF uint32_t ds_iter_next(ds_codepoint_iter* iter);
 
DS_DEF int ds_iter_has_next(const ds_codepoint_iter* iter);
 
// Unicode utility functions
DS_DEF size_t ds_codepoint_length(ds_string str);
 
DS_DEF uint32_t ds_codepoint_at(ds_string str, size_t index);
 
// Convenience macros for common operations
#define ds_empty() ds_new("")
#define ds_from_literal(lit) ds_new(lit)
 
// ============================================================================
// STRINGBUILDER - Mutable builder for efficient string construction
// ============================================================================
 
typedef struct {
    ds_string data; // Points to string data (same layout as ds_string)
    size_t capacity; // Capacity for growth (length is in metadata)
} ds_stringbuilder;
 
// StringBuilder creation and management
DS_DEF ds_stringbuilder ds_builder_create(void);
DS_DEF ds_stringbuilder ds_builder_create_with_capacity(size_t capacity);
DS_DEF void ds_builder_destroy(ds_stringbuilder* sb);
 
// Mutable operations (modify the builder in-place)
DS_DEF int ds_builder_append(ds_stringbuilder* sb, const char* text);
DS_DEF int ds_builder_append_char(ds_stringbuilder* sb, uint32_t codepoint);
DS_DEF int ds_builder_append_string(ds_stringbuilder* sb, ds_string str);
DS_DEF int ds_builder_insert(ds_stringbuilder* sb, size_t index, const char* text);
DS_DEF void ds_builder_clear(ds_stringbuilder* sb);
 
// Conversion to immutable string (the magic happens here!)
DS_DEF ds_string ds_builder_to_string(ds_stringbuilder* sb);
 
// StringBuilder inspection
DS_DEF size_t ds_builder_length(const ds_stringbuilder* sb);
DS_DEF size_t ds_builder_capacity(const ds_stringbuilder* sb);
DS_DEF const char* ds_builder_cstr(const ds_stringbuilder* sb);
 
#ifdef __cplusplus
}
#endif
 
// ============================================================================
// IMPLEMENTATION
// ============================================================================
 
#ifdef DS_IMPLEMENTATION
 
typedef struct ds_internal {
    DS_ATOMIC_SIZE_T refcount;
    size_t length;
} ds_internal;
 
// ============================================================================
// INTERNAL HELPER FUNCTIONS
// ============================================================================
 
static ds_internal* ds_meta(ds_string str) { return (ds_internal*)(str - sizeof(ds_internal)); }
 
static ds_string ds_alloc(size_t length) {
    // Allocate: metadata + string data + null terminator
    void* block = DS_MALLOC(sizeof(ds_internal) + length + 1);
    DS_ASSERT(block && "Memory allocation failed");
 
    // Initialize metadata
    ds_internal* meta = block;
    DS_ATOMIC_STORE(&meta->refcount, 1);
    meta->length = length;
 
    // Return pointer to string data portion
    ds_string str = (char*)block + sizeof(ds_internal);
    str[length] = '\0'; // Always null-terminate
 
    return str;
}
 
static void ds_dealloc(ds_string str) {
    if (str) {
        // Get original malloc pointer and free it
        void* block = str - sizeof(ds_internal);
        DS_FREE(block);
    }
}
 
// ============================================================================
// CORE STRING FUNCTIONS
// ============================================================================
 
DS_DEF size_t ds_length(ds_string str) {
    DS_ASSERT(str && "ds_length: str cannot be NULL");
    return ds_meta(str)->length;
}
 
DS_DEF size_t ds_refcount(ds_string str) {
    DS_ASSERT(str && "ds_refcount: str cannot be NULL");
    return DS_ATOMIC_LOAD(&ds_meta(str)->refcount);
}
 
DS_DEF int ds_is_shared(ds_string str) {
    DS_ASSERT(str && "ds_is_shared: str cannot be NULL");
    return DS_ATOMIC_LOAD(&ds_meta(str)->refcount) > 1;
}
 
DS_DEF int ds_is_empty(ds_string str) {
    DS_ASSERT(str && "ds_is_empty: str cannot be NULL");
    return ds_meta(str)->length == 0;
}
 
DS_DEF ds_string ds_new(const char* text) {
    DS_ASSERT(text && "ds_new: text cannot be NULL");
    
    size_t len = strlen(text);
    return ds_create_length(text, len);
}
 
DS_DEF ds_string ds_create_length(const char* text, size_t length) {
    DS_ASSERT(text && "ds_create_length: text cannot be NULL");
    
    size_t text_len = strlen(text);
    size_t actual_len = text_len < length ? text_len : length;
    
    ds_string str = ds_alloc(actual_len);
 
    if (actual_len > 0) {
        memcpy(str, text, actual_len);
    }
 
    return str;
}
 
DS_DEF ds_string ds_retain(ds_string str) {
    DS_ASSERT(str && "ds_retain: str cannot be NULL");
    DS_ATOMIC_FETCH_ADD(&ds_meta(str)->refcount, 1);
    return str;
}
 
DS_DEF void ds_release(ds_string* str) {
    if (str && *str) {
        ds_internal* meta = ds_meta(*str);
        size_t old_count = DS_ATOMIC_FETCH_SUB(&meta->refcount, 1);
        if (old_count == 1) {  // We were the last reference
            ds_dealloc(*str);
        }
        *str = NULL;
    }
}
 
DS_DEF ds_string ds_append(ds_string str, const char* text) {
    DS_ASSERT(str && "ds_append: str cannot be NULL");
    DS_ASSERT(text && "ds_append: text cannot be NULL");
 
    size_t text_len = strlen(text);
    if (text_len == 0) {
        return ds_retain(str);
    }
 
    size_t new_length = ds_meta(str)->length + text_len;
    ds_string result = ds_alloc(new_length);
 
    // Copy original string
    memcpy(result, str, ds_meta(str)->length);
    // Append new text
    memcpy(result + ds_meta(str)->length, text, text_len);
 
    return result;
}
 
static size_t ds_encode_utf8(uint32_t codepoint, char* buffer) {
    if (codepoint <= 0x7F) {
        buffer[0] = (char)codepoint;
        return 1;
    }
    if (codepoint <= 0x7FF) {
        buffer[0] = (char)(0xC0 | codepoint >> 6);
        buffer[1] = (char)(0x80 | codepoint & 0x3F);
        return 2;
    }
    if (codepoint <= 0xFFFF) {
        buffer[0] = (char)(0xE0 | codepoint >> 12);
        buffer[1] = (char)(0x80 | codepoint >> 6 & 0x3F);
        buffer[2] = (char)(0x80 | codepoint & 0x3F);
        return 3;
    }
    if (codepoint <= 0x10FFFF) {
        buffer[0] = (char)(0xF0 | codepoint >> 18);
        buffer[1] = (char)(0x80 | codepoint >> 12 & 0x3F);
        buffer[2] = (char)(0x80 | codepoint >> 6 & 0x3F);
        buffer[3] = (char)(0x80 | codepoint & 0x3F);
        return 4;
    }
 
    // Invalid codepoint - use replacement character (U+FFFD)
    buffer[0] = (char)0xEF;
    buffer[1] = (char)0xBF;
    buffer[2] = (char)0xBD;
    return 3;
}
 
DS_DEF ds_string ds_append_char(ds_string str, uint32_t codepoint) {
    DS_ASSERT(str && "ds_append_char: str cannot be NULL");
    
    char utf8_buffer[4];
    size_t bytes_needed = ds_encode_utf8(codepoint, utf8_buffer);
 
    char temp_str[5];
    memcpy(temp_str, utf8_buffer, bytes_needed);
    temp_str[bytes_needed] = '\0';
 
    return ds_append(str, temp_str);
}
 
DS_DEF ds_string ds_prepend(ds_string str, const char* text) {
    DS_ASSERT(str && "ds_prepend: str cannot be NULL");
    DS_ASSERT(text && "ds_prepend: text cannot be NULL");
 
    size_t text_len = strlen(text);
    if (text_len == 0) {
        return ds_retain(str);
    }
 
    size_t new_length = ds_meta(str)->length + text_len;
    ds_string result = ds_alloc(new_length);
 
    // Copy new text first
    memcpy(result, text, text_len);
    // Copy original string after
    memcpy(result + text_len, str, ds_meta(str)->length);
 
    return result;
}
 
DS_DEF ds_string ds_insert(ds_string str, size_t index, const char* text) {
    DS_ASSERT(str && "ds_insert: str cannot be NULL");
    DS_ASSERT(text && "ds_insert: text cannot be NULL");
    
    // Clamp index to end of string if beyond bounds
    size_t str_len = ds_meta(str)->length;
    if (index > str_len) {
        index = str_len;
    }
 
    size_t text_len = strlen(text);
    if (text_len == 0) {
        return ds_retain(str);
    }
 
    size_t new_length = str_len + text_len;
    ds_string result = ds_alloc(new_length);
 
    // Copy part before insertion point
    memcpy(result, str, index);
    // Copy inserted text
    memcpy(result + index, text, text_len);
    // Copy part after insertion point
    memcpy(result + index + text_len, str + index, str_len - index);
 
    return result;
}
 
DS_DEF ds_string ds_substring(ds_string str, size_t start, size_t len) {
    DS_ASSERT(str && "ds_substring: str cannot be NULL");
    
    if (start >= ds_meta(str)->length) {
        return ds_new("");
    }
 
    size_t str_len = ds_meta(str)->length;
    if (start + len > str_len) {
        len = str_len - start;
    }
 
    return ds_create_length(str + start, len);
}
 
DS_DEF ds_string ds_concat(ds_string a, ds_string b) {
    DS_ASSERT(a && "ds_concat: a cannot be NULL");
    DS_ASSERT(b && "ds_concat: b cannot be NULL");
 
    size_t new_length = ds_meta(a)->length + ds_meta(b)->length;
    ds_string result = ds_alloc(new_length);
 
    memcpy(result, a, ds_meta(a)->length);
    memcpy(result + ds_meta(a)->length, b, ds_meta(b)->length);
 
    return result;
}
 
DS_DEF ds_string ds_join(ds_string* strings, size_t count, const char* separator) {
    DS_ASSERT(strings && "ds_join: strings cannot be NULL");
    
    if (count == 0) {
        return ds_new("");
    }
 
    if (count == 1) {
        DS_ASSERT(strings[0] && "ds_join: strings[0] cannot be NULL");
        return ds_retain(strings[0]);
    }
 
    ds_stringbuilder sb = ds_builder_create();
 
    for (size_t i = 0; i < count; i++) {
        DS_ASSERT(strings[i] && "ds_join: strings[i] cannot be NULL");
        ds_builder_append_string(&sb, strings[i]);
 
        if (i < count - 1 && separator) {
            ds_builder_append(&sb, separator);
        }
    }
 
    ds_string result = ds_builder_to_string(&sb);
    ds_builder_destroy(&sb);
    return result;
}
 
DS_DEF int ds_compare(ds_string a, ds_string b) {
    DS_ASSERT(a && "ds_compare: a cannot be NULL");
    DS_ASSERT(b && "ds_compare: b cannot be NULL");
    
    // Fast path: same object
    if (a == b)
        return 0;
 
    return strcmp(a, b);
}
 
DS_DEF int ds_compare_ignore_case(ds_string a, ds_string b) {
    DS_ASSERT(a && "ds_compare_ignore_case: a cannot be NULL");
    DS_ASSERT(b && "ds_compare_ignore_case: b cannot be NULL");
    
    // Fast path: same object
    if (a == b)
        return 0;
 
    const char* a_str = a;
    const char* b_str = b;
    
    // Manual case-insensitive comparison (portable)
    while (*a_str && *b_str) {
        char ca = (char)tolower((unsigned char)*a_str);
        char cb = (char)tolower((unsigned char)*b_str);
        if (ca != cb) {
            return ca - cb;
        }
        a_str++;
        b_str++;
    }
    
    return (unsigned char)tolower((unsigned char)*a_str) - (unsigned char)tolower((unsigned char)*b_str);
}
 
DS_DEF size_t ds_hash(ds_string str) {
    DS_ASSERT(str && "ds_hash: str cannot be NULL");
    
    // FNV-1a hash algorithm
    const size_t FNV_PRIME = sizeof(size_t) == 8 ? 1099511628211ULL : 16777619U;
    const size_t FNV_OFFSET_BASIS = sizeof(size_t) == 8 ? 14695981039346656037ULL : 2166136261U;
    
    size_t hash = FNV_OFFSET_BASIS;
    size_t len = ds_length(str);
    
    for (size_t i = 0; i < len; i++) {
        hash ^= (unsigned char)str[i];
        hash *= FNV_PRIME;
    }
    
    return hash;
}
 
DS_DEF int ds_find(ds_string str, const char* needle) {
    DS_ASSERT(str && "ds_find: str cannot be NULL");
    DS_ASSERT(needle && "ds_find: needle cannot be NULL");
 
    const char* found = strstr(str, needle);
    return found ? (int)(found - str) : -1;
}
 
DS_DEF int ds_find_last(ds_string str, const char* needle) {
    DS_ASSERT(str && "ds_find_last: str cannot be NULL");
    DS_ASSERT(needle && "ds_find_last: needle cannot be NULL");
    
    size_t needle_len = strlen(needle);
    if (needle_len == 0)
        return 0;  // Empty string found at beginning
    
    size_t str_len = ds_length(str);
    if (needle_len > str_len)
        return -1;
    
    // Search backwards from the end
    for (size_t i = str_len - needle_len; i != SIZE_MAX; i--) {
        if (memcmp(str + i, needle, needle_len) == 0) {
            return (int)i;
        }
    }
    
    return -1;
}
 
DS_DEF int ds_contains(ds_string str, const char* needle) {
    DS_ASSERT(str && "ds_contains: str cannot be NULL");
    DS_ASSERT(needle && "ds_contains: needle cannot be NULL");
    return ds_find(str, needle) != -1;
}
 
DS_DEF int ds_starts_with(ds_string str, const char* prefix) {
    DS_ASSERT(str && "ds_starts_with: str cannot be NULL");
    DS_ASSERT(prefix && "ds_starts_with: prefix cannot be NULL");
 
    size_t prefix_len = strlen(prefix);
    if (prefix_len > ds_meta(str)->length)
        return 0;
 
    return memcmp(str, prefix, prefix_len) == 0;
}
 
DS_DEF int ds_ends_with(ds_string str, const char* suffix) {
    DS_ASSERT(str && "ds_ends_with: str cannot be NULL");
    DS_ASSERT(suffix && "ds_ends_with: suffix cannot be NULL");
 
    size_t suffix_len = strlen(suffix);
    size_t str_len = ds_meta(str)->length;
    if (suffix_len > str_len)
        return 0;
 
    return memcmp(str + str_len - suffix_len, suffix, suffix_len) == 0;
}
 
// ============================================================================
// STRING TRANSFORMATION FUNCTIONS
// ============================================================================
 
static int ds_is_whitespace(char c) {
    return c == ' ' || c == '\t' || c == '\n' || c == '\r' || c == '\v' || c == '\f';
}
 
DS_DEF ds_string ds_trim_left(ds_string str) {
    DS_ASSERT(str && "ds_trim_left: str cannot be NULL");
    
    size_t len = ds_length(str);
    if (len == 0) return ds_retain(str);
    
    size_t start = 0;
    while (start < len && ds_is_whitespace(str[start])) {
        start++;
    }
    
    if (start == 0) {
        return ds_retain(str); // No trimming needed
    }
    
    return ds_substring(str, start, len - start);
}
 
DS_DEF ds_string ds_trim_right(ds_string str) {
    DS_ASSERT(str && "ds_trim_right: str cannot be NULL");
    
    size_t len = ds_length(str);
    if (len == 0) return ds_retain(str);
    
    size_t end = len;
    while (end > 0 && ds_is_whitespace(str[end - 1])) {
        end--;
    }
    
    if (end == len) {
        return ds_retain(str); // No trimming needed
    }
    
    return ds_substring(str, 0, end);
}
 
DS_DEF ds_string ds_trim(ds_string str) {
    DS_ASSERT(str && "ds_trim: str cannot be NULL");
    
    size_t len = ds_length(str);
    if (len == 0) return ds_retain(str);
    
    // Find start of non-whitespace
    size_t start = 0;
    while (start < len && ds_is_whitespace(str[start])) {
        start++;
    }
    
    // Find end of non-whitespace
    size_t end = len;
    while (end > start && ds_is_whitespace(str[end - 1])) {
        end--;
    }
    
    if (start == 0 && end == len) {
        return ds_retain(str); // No trimming needed
    }
    
    return ds_substring(str, start, end - start);
}
 
// ============================================================================
// STRING REPLACEMENT FUNCTIONS
// ============================================================================
 
DS_DEF ds_string ds_replace(ds_string str, const char* old, const char* new) {
    DS_ASSERT(str && "ds_replace: str cannot be NULL");
    DS_ASSERT(old && "ds_replace: old cannot be NULL");
    DS_ASSERT(new && "ds_replace: new cannot be NULL");
    
    int pos = ds_find(str, old);
    if (pos == -1) {
        return ds_retain(str); // Nothing to replace
    }
    
    size_t old_len = strlen(old);
    size_t new_len = strlen(new);
    size_t str_len = ds_length(str);
    
    ds_stringbuilder sb = ds_builder_create();
    
    // Add part before match
    if (pos > 0) {
        ds_string before = ds_substring(str, 0, pos);
        ds_builder_append_string(&sb, before);
        ds_release(&before);
    }
    
    // Add replacement
    ds_builder_append(&sb, new);
    
    // Add part after match
    if (pos + old_len < str_len) {
        ds_string after = ds_substring(str, pos + old_len, str_len - (pos + old_len));
        ds_builder_append_string(&sb, after);
        ds_release(&after);
    }
    
    ds_string result = ds_builder_to_string(&sb);
    ds_builder_destroy(&sb);
    return result;
}
 
DS_DEF ds_string ds_replace_all(ds_string str, const char* old, const char* new) {
    DS_ASSERT(str && "ds_replace_all: str cannot be NULL");
    DS_ASSERT(old && "ds_replace_all: old cannot be NULL");
    DS_ASSERT(new && "ds_replace_all: new cannot be NULL");
    
    size_t old_len = strlen(old);
    if (old_len == 0) return ds_retain(str);
    
    ds_stringbuilder sb = ds_builder_create();
    size_t start = 0;
    size_t str_len = ds_length(str);
    
    while (start < str_len) {
        const char* found = strstr(str + start, old);
        if (!found) {
            // No more matches, add remainder
            ds_string remainder = ds_substring(str, start, str_len - start);
            ds_builder_append_string(&sb, remainder);
            ds_release(&remainder);
            break;
        }
        
        size_t match_pos = found - str;
        
        // Add part before match
        if (match_pos > start) {
            ds_string before = ds_substring(str, start, match_pos - start);
            ds_builder_append_string(&sb, before);
            ds_release(&before);
        }
        
        // Add replacement
        ds_builder_append(&sb, new);
        
        // Move past the match
        start = match_pos + old_len;
    }
    
    ds_string result = ds_builder_to_string(&sb);
    ds_builder_destroy(&sb);
    return result;
}
 
// ============================================================================
// CASE TRANSFORMATION FUNCTIONS
// ============================================================================
 
#include <ctype.h>
 
DS_DEF ds_string ds_to_upper(ds_string str) {
    DS_ASSERT(str && "ds_to_upper: str cannot be NULL");
    
    size_t len = ds_length(str);
    if (len == 0) return ds_retain(str);
    
    ds_stringbuilder sb = ds_builder_create_with_capacity(len);
    
    for (size_t i = 0; i < len; i++) {
        char c = str[i];
        char upper_c = (char)toupper((unsigned char)c);
        ds_builder_append_char(&sb, upper_c);
    }
    
    ds_string result = ds_builder_to_string(&sb);
    ds_builder_destroy(&sb);
    return result;
}
 
DS_DEF ds_string ds_to_lower(ds_string str) {
    DS_ASSERT(str && "ds_to_lower: str cannot be NULL");
    
    size_t len = ds_length(str);
    if (len == 0) return ds_retain(str);
    
    ds_stringbuilder sb = ds_builder_create_with_capacity(len);
    
    for (size_t i = 0; i < len; i++) {
        char c = str[i];
        char lower_c = (char)tolower((unsigned char)c);
        ds_builder_append_char(&sb, lower_c);
    }
    
    ds_string result = ds_builder_to_string(&sb);
    ds_builder_destroy(&sb);
    return result;
}
 
// ============================================================================
// UTILITY TRANSFORMATION FUNCTIONS
// ============================================================================
 
DS_DEF ds_string ds_repeat(ds_string str, size_t times) {
    DS_ASSERT(str && "ds_repeat: str cannot be NULL");
    if (times == 0) return ds_new("");
    if (times == 1) return ds_retain(str);
    
    size_t str_len = ds_length(str);
    if (str_len == 0) return ds_retain(str);
    
    ds_stringbuilder sb = ds_builder_create_with_capacity(str_len * times);
    
    for (size_t i = 0; i < times; i++) {
        ds_builder_append_string(&sb, str);
    }
    
    ds_string result = ds_builder_to_string(&sb);
    ds_builder_destroy(&sb);
    return result;
}
 
DS_DEF ds_string ds_truncate(ds_string str, size_t max_length, const char* ellipsis) {
    DS_ASSERT(str && "ds_truncate: str cannot be NULL");
    
    size_t str_len = ds_length(str);
    if (str_len <= max_length) {
        return ds_retain(str);  // No truncation needed
    }
    
    size_t ellipsis_len = ellipsis ? strlen(ellipsis) : 0;
    if (max_length < ellipsis_len) {
        // Max length is too small for ellipsis, just truncate without ellipsis
        return ds_substring(str, 0, max_length);
    }
    
    if (ellipsis_len == 0) {
        // No ellipsis, just truncate
        return ds_substring(str, 0, max_length);
    }
    
    // Use builder for efficient construction
    ds_stringbuilder sb = ds_builder_create_with_capacity(max_length + ellipsis_len);
    
    // Add truncated part
    size_t truncate_at = max_length - ellipsis_len;
    ds_string truncated_part = ds_substring(str, 0, truncate_at);
    ds_builder_append_string(&sb, truncated_part);
    ds_release(&truncated_part);
    
    // Add ellipsis
    ds_builder_append(&sb, ellipsis);
    
    ds_string result = ds_builder_to_string(&sb);
    ds_builder_destroy(&sb);
    return result;
}
 
DS_DEF ds_string ds_reverse(ds_string str) {
    DS_ASSERT(str && "ds_reverse: str cannot be NULL");
    
    size_t len = ds_length(str);
    if (len <= 1) return ds_retain(str);
    
    ds_stringbuilder sb = ds_builder_create_with_capacity(len);
    
    // Reverse by codepoints for proper Unicode handling
    ds_codepoint_iter iter = ds_codepoints(str);
    uint32_t* codepoints = DS_MALLOC(ds_codepoint_length(str) * sizeof(uint32_t));
    size_t cp_count = 0;
    
    uint32_t cp;
    while ((cp = ds_iter_next(&iter)) != 0) {
        codepoints[cp_count++] = cp;
    }
    
    // Add codepoints in reverse order
    for (size_t i = cp_count; i > 0; i--) {
        ds_builder_append_char(&sb, codepoints[i - 1]);
    }
    
    DS_FREE(codepoints);
    
    ds_string result = ds_builder_to_string(&sb);
    ds_builder_destroy(&sb);
    return result;
}
 
DS_DEF ds_string ds_pad_left(ds_string str, size_t width, char pad) {
    DS_ASSERT(str && "ds_pad_left: str cannot be NULL");
    
    size_t len = ds_length(str);
    if (len >= width) return ds_retain(str);
    
    size_t pad_count = width - len;
    ds_stringbuilder sb = ds_builder_create_with_capacity(width);
    
    // Add padding
    for (size_t i = 0; i < pad_count; i++) {
        ds_builder_append_char(&sb, pad);
    }
    
    // Add original string
    ds_builder_append_string(&sb, str);
    
    ds_string result = ds_builder_to_string(&sb);
    ds_builder_destroy(&sb);
    return result;
}
 
DS_DEF ds_string ds_pad_right(ds_string str, size_t width, char pad) {
    DS_ASSERT(str && "ds_pad_right: str cannot be NULL");
    
    size_t len = ds_length(str);
    if (len >= width) return ds_retain(str);
    
    size_t pad_count = width - len;
    ds_stringbuilder sb = ds_builder_create_with_capacity(width);
    
    // Add original string
    ds_builder_append_string(&sb, str);
    
    // Add padding
    for (size_t i = 0; i < pad_count; i++) {
        ds_builder_append_char(&sb, pad);
    }
    
    ds_string result = ds_builder_to_string(&sb);
    ds_builder_destroy(&sb);
    return result;
}
 
// ============================================================================
// STRING SPLITTING FUNCTIONS
// ============================================================================
 
DS_DEF ds_string* ds_split(ds_string str, const char* delimiter, size_t* count) {
    DS_ASSERT(str && "ds_split: str cannot be NULL");
    DS_ASSERT(delimiter && "ds_split: delimiter cannot be NULL");
    
    if (count) *count = 0;
    
    size_t delim_len = strlen(delimiter);
    if (delim_len == 0) {
        // Split into individual characters
        size_t str_len = ds_length(str);
        if (str_len == 0) return NULL;
        
        ds_string* result = DS_MALLOC(str_len * sizeof(ds_string));
        if (!result) return NULL;
        
        for (size_t i = 0; i < str_len; i++) {
            result[i] = ds_substring(str, i, 1);
        }
        
        if (count) *count = str_len;
        return result;
    }
    
    // Count occurrences to allocate array
    size_t split_count = 1; // At least one part
    const char* pos = str;
    while ((pos = strstr(pos, delimiter)) != NULL) {
        split_count++;
        pos += delim_len;
    }
    
    ds_string* result = DS_MALLOC(split_count * sizeof(ds_string));
    if (!result) return NULL;
    
    // Split the string
    size_t result_index = 0;
    size_t start = 0;
    size_t str_len = ds_length(str);
    
    if (str_len >= delim_len) {
        for (size_t i = 0; i <= str_len - delim_len; i++) {
            if (memcmp(str + i, delimiter, delim_len) == 0) {
                // Found delimiter
                result[result_index++] = ds_substring(str, start, i - start);
                i += delim_len - 1; // Skip delimiter (loop will increment i)
                start = i + 1;
            }
        }
    }
    
    // Add the last part
    result[result_index] = ds_substring(str, start, str_len - start);
    
    if (count) *count = split_count;
    return result;
}
 
DS_DEF void ds_free_split_result(ds_string* array, size_t count) {
    if (!array) return;
    
    for (size_t i = 0; i < count; i++) {
        ds_release(&array[i]);
    }
    
    DS_FREE(array);
}
 
// ============================================================================
// STRING FORMATTING FUNCTIONS
// ============================================================================
 
#include <stdarg.h>
 
DS_DEF ds_string ds_format(const char* fmt, ...) {
    if (!fmt) return NULL;
    
    va_list args;
    va_start(args, fmt);
    ds_string result = ds_format_v(fmt, args);
    va_end(args);
    
    return result;
}
 
DS_DEF ds_string ds_format_v(const char* fmt, va_list args) {
    if (!fmt) return NULL;
    
    // Get required size
    va_list args_copy;
    va_copy(args_copy, args);
    int size = vsnprintf(NULL, 0, fmt, args_copy);
    va_end(args_copy);
    
    if (size < 0) {
        return NULL;
    }
    
    // Allocate and format
    ds_string result = ds_alloc(size);
    vsnprintf(result, size + 1, fmt, args);
    
    return result;
}
 
DS_DEF ds_string ds_escape_json(ds_string str) {
    DS_ASSERT(str && "ds_escape_json: str cannot be NULL");
    
    size_t len = ds_length(str);
    if (len == 0) return ds_retain(str);
    
    // Use builder with reasonable initial capacity (assume some escaping needed)
    ds_stringbuilder sb = ds_builder_create_with_capacity(len * 2);
    
    for (size_t i = 0; i < len; i++) {
        unsigned char c = (unsigned char)str[i];
        
        switch (c) {
            case '"':  ds_builder_append(&sb, "\\\""); break;
            case '\\': ds_builder_append(&sb, "\\\\"); break;
            case '\b': ds_builder_append(&sb, "\\b"); break;
            case '\f': ds_builder_append(&sb, "\\f"); break;
            case '\n': ds_builder_append(&sb, "\\n"); break;
            case '\r': ds_builder_append(&sb, "\\r"); break;
            case '\t': ds_builder_append(&sb, "\\t"); break;
            default:
                if (c < 0x20) {
                    // Control characters - escape as \uXXXX
                    ds_string escaped = ds_format("\\u%04x", c);
                    ds_builder_append_string(&sb, escaped);
                    ds_release(&escaped);
                } else {
                    ds_builder_append_char(&sb, c);
                }
                break;
        }
    }
    
    ds_string result = ds_builder_to_string(&sb);
    ds_builder_destroy(&sb);
    return result;
}
 
DS_DEF ds_string ds_unescape_json(ds_string str) {
    DS_ASSERT(str && "ds_unescape_json: str cannot be NULL");
    
    size_t len = ds_length(str);
    if (len == 0) return ds_retain(str);
    
    ds_stringbuilder sb = ds_builder_create_with_capacity(len);
    
    for (size_t i = 0; i < len; i++) {
        if (str[i] == '\\' && i + 1 < len) {
            switch (str[i + 1]) {
                case '"':  ds_builder_append_char(&sb, '"'); i++; break;
                case '\\': ds_builder_append_char(&sb, '\\'); i++; break;
                case '/':  ds_builder_append_char(&sb, '/'); i++; break;
                case 'b':  ds_builder_append_char(&sb, '\b'); i++; break;
                case 'f':  ds_builder_append_char(&sb, '\f'); i++; break;
                case 'n':  ds_builder_append_char(&sb, '\n'); i++; break;
                case 'r':  ds_builder_append_char(&sb, '\r'); i++; break;
                case 't':  ds_builder_append_char(&sb, '\t'); i++; break;
                case 'u':
                    // Unicode escape sequence \uXXXX
                    if (i + 5 < len) {
                        char hex[5] = {str[i+2], str[i+3], str[i+4], str[i+5], '\0'};
                        char* endptr;
                        unsigned long codepoint = strtoul(hex, &endptr, 16);
                        if (endptr == hex + 4) {  // Valid 4-digit hex
                            ds_builder_append_char(&sb, (uint32_t)codepoint);
                            i += 5;
                        } else {
                            // Invalid escape, keep as-is
                            ds_builder_append_char(&sb, str[i]);
                        }
                    } else {
                        // Incomplete escape at end of string
                        ds_builder_append_char(&sb, str[i]);
                    }
                    break;
                default:
                    // Unknown escape, keep both characters
                    ds_builder_append_char(&sb, str[i]);
                    break;
            }
        } else {
            ds_builder_append_char(&sb, str[i]);
        }
    }
    
    ds_string result = ds_builder_to_string(&sb);
    ds_builder_destroy(&sb);
    return result;
}
 
// ============================================================================
// UNICODE CODEPOINT ITERATION
// ============================================================================
 
static uint32_t ds_decode_utf8_at(const char* data, size_t pos, size_t end, size_t* bytes_consumed) {
    if (pos >= end) {
        *bytes_consumed = 0;
        return 0;
    }
 
    unsigned char first = (unsigned char)data[pos];
 
    if (first <= 0x7F) {
        *bytes_consumed = 1;
        return first;
    }
 
    if ((first & 0xE0) == 0xC0) {
        if (pos + 1 >= end) {
            *bytes_consumed = 0;
            return 0;
        }
        *bytes_consumed = 2;
        return (first & 0x1F) << 6 | (unsigned char)data[pos + 1] & 0x3F;
    }
 
    if ((first & 0xF0) == 0xE0) {
        if (pos + 2 >= end) {
            *bytes_consumed = 0;
            return 0;
        }
        *bytes_consumed = 3;
        return (first & 0x0F) << 12 | ((unsigned char)data[pos + 1] & 0x3F) << 6 | (unsigned char)data[pos + 2] & 0x3F;
    }
 
    if ((first & 0xF8) == 0xF0) {
        if (pos + 3 >= end) {
            *bytes_consumed = 0;
            return 0;
        }
        *bytes_consumed = 4;
        return (first & 0x07) << 18 | ((unsigned char)data[pos + 1] & 0x3F) << 12 |
            ((unsigned char)data[pos + 2] & 0x3F) << 6 | (unsigned char)data[pos + 3] & 0x3F;
    }
 
    *bytes_consumed = 1;
    return 0xFFFD; // Unicode replacement character
}
 
DS_DEF ds_codepoint_iter ds_codepoints(ds_string str) {
    DS_ASSERT(str && "ds_codepoints: str cannot be NULL");
    
    ds_codepoint_iter iter;
    iter.data = str;
    iter.pos = 0;
    iter.end = ds_meta(str)->length;
 
    return iter;
}
 
DS_DEF uint32_t ds_iter_next(ds_codepoint_iter* iter) {
    if (!iter || iter->pos >= iter->end) {
        return 0;
    }
 
    size_t bytes_consumed;
    uint32_t codepoint = ds_decode_utf8_at(iter->data, iter->pos, iter->end, &bytes_consumed);
 
    if (bytes_consumed == 0) {
        return 0;
    }
 
    iter->pos += bytes_consumed;
    return codepoint;
}
 
DS_DEF int ds_iter_has_next(const ds_codepoint_iter* iter) { return iter && iter->pos < iter->end; }
 
DS_DEF size_t ds_codepoint_length(ds_string str) {
    DS_ASSERT(str && "ds_codepoint_length: str cannot be NULL");
 
    ds_codepoint_iter iter = ds_codepoints(str);
    size_t count = 0;
 
    while (ds_iter_next(&iter) != 0) {
        count++;
    }
 
    return count;
}
 
DS_DEF uint32_t ds_codepoint_at(ds_string str, size_t index) {
    DS_ASSERT(str && "ds_codepoint_at: str cannot be NULL");
 
    ds_codepoint_iter iter = ds_codepoints(str);
    size_t current_index = 0;
    uint32_t codepoint;
 
    while ((codepoint = ds_iter_next(&iter)) != 0) {
        if (current_index == index) {
            return codepoint;
        }
        current_index++;
    }
 
    return 0;
}
 
// ============================================================================
// STRINGBUILDER
// ============================================================================
 
#ifndef DS_SB_INITIAL_CAPACITY
#define DS_SB_INITIAL_CAPACITY 32
#endif
 
#ifndef DS_SB_GROWTH_FACTOR
#define DS_SB_GROWTH_FACTOR 2
#endif
 
// StringBuilder helper functions
static int ds_sb_ensure_capacity(ds_stringbuilder* sb, size_t required_capacity) {
    if (sb->capacity >= required_capacity) {
        return 1; // Already have enough capacity
    }
    size_t new_capacity = sb->capacity;
    if (new_capacity == 0) {
        new_capacity = DS_SB_INITIAL_CAPACITY;
    }
 
    while (new_capacity < required_capacity) {
        new_capacity *= DS_SB_GROWTH_FACTOR;
    }
 
    // Get original block pointer and resize
    void* old_block = (char*)sb->data - sizeof(ds_internal);
    void* new_block = DS_REALLOC(old_block, sizeof(ds_internal) + new_capacity);
    DS_ASSERT(new_block && "Memory re-allocation failed");
 
    sb->data = (char*)new_block + sizeof(ds_internal);
    sb->capacity = new_capacity;
    return 1;
}
 
static int ds_sb_ensure_unique(ds_stringbuilder* sb) {
    if (!sb->data)
        return 0;
 
    ds_internal* meta = ds_meta(sb->data);
    if (DS_ATOMIC_LOAD(&meta->refcount) <= 1) {
        return 1; // Already unique
    }
 
    // Need to create our own copy - just allocate exactly what we need
    size_t current_length = meta->length;
    ds_string new_str = ds_alloc(current_length);
 
    // Copy current content
    memcpy(new_str, sb->data, current_length);
 
    // Release old reference properly
    ds_string old_str = sb->data;
    ds_release(&old_str);
 
    // Update StringBuilder - capacity is just what ds_alloc gave us
    sb->data = new_str;
    sb->capacity = current_length + 1; // ds_alloc gives us length + null terminator
 
    return 1;
}
 
DS_DEF ds_stringbuilder ds_builder_create(void) { return ds_builder_create_with_capacity(DS_SB_INITIAL_CAPACITY); }
 
DS_DEF ds_stringbuilder ds_builder_create_with_capacity(size_t capacity) {
    ds_stringbuilder sb;
 
    if (capacity == 0)
        capacity = DS_SB_INITIAL_CAPACITY;
 
    void* block = DS_MALLOC(sizeof(ds_internal) + capacity);
    DS_ASSERT(block && "Memory allocation failed");
 
    ds_internal* meta = (ds_internal*)block;
    DS_ATOMIC_STORE(&meta->refcount, 1);
    meta->length = 0;
 
    sb.data = (char*)block + sizeof(ds_internal);
    sb.data[0] = '\0';
    sb.capacity = capacity;
 
    return sb;
}
 
DS_DEF void ds_builder_destroy(ds_stringbuilder* sb) {
    if (sb) {
        ds_release(&sb->data); // Handles refcount decrement and freeing
        sb->capacity = 0;
    }
}
 
DS_DEF int ds_builder_append(ds_stringbuilder* sb, const char* text) {
    if (!sb || !text || !sb->data)
        return 0;
 
    size_t text_len = strlen(text);
    if (text_len == 0)
        return 1;
 
    if (!ds_sb_ensure_unique(sb))
        return 0;
 
    ds_internal* meta = ds_meta(sb->data);
    if (!ds_sb_ensure_capacity(sb, meta->length + text_len + 1))
        return 0;
 
    meta = ds_meta(sb->data);
    memcpy(sb->data + meta->length, text, text_len);
    meta->length += text_len;
    sb->data[meta->length] = '\0';
 
    return 1;
}
 
DS_DEF int ds_builder_append_char(ds_stringbuilder* sb, uint32_t codepoint) {
    if (!sb || !sb->data)
        return 0;
 
    char utf8_buffer[4];
    size_t bytes_needed = ds_encode_utf8(codepoint, utf8_buffer);
 
    if (!ds_sb_ensure_unique(sb))
        return 0;
 
    ds_internal* meta = ds_meta(sb->data);
    if (!ds_sb_ensure_capacity(sb, meta->length + bytes_needed + 1))
        return 0;
 
    meta = ds_meta(sb->data);
    memcpy(sb->data + meta->length, utf8_buffer, bytes_needed);
    meta->length += bytes_needed;
    sb->data[meta->length] = '\0';
 
    return 1;
}
 
DS_DEF int ds_builder_append_string(ds_stringbuilder* sb, ds_string str) {
    if (!sb || !str)
        return 0;
 
    if (!ds_sb_ensure_unique(sb))
        return 0;
 
    ds_internal* sb_meta = ds_meta(sb->data);
    ds_internal* str_meta = ds_meta(str);
 
    if (!ds_sb_ensure_capacity(sb, sb_meta->length + str_meta->length + 1))
        return 0;
 
    sb_meta = ds_meta(sb->data);
    memcpy(sb->data + sb_meta->length, str, str_meta->length);
    sb_meta->length += str_meta->length;
    sb->data[sb_meta->length] = '\0';
 
    return 1;
}
 
DS_DEF int ds_builder_insert(ds_stringbuilder* sb, size_t index, const char* text) {
    if (!sb || !text || !sb->data)
        return 0;
 
    ds_internal* meta = ds_meta(sb->data);
    if (index > meta->length)
        return 0;
 
    size_t text_len = strlen(text);
    if (text_len == 0)
        return 1;
 
    if (!ds_sb_ensure_unique(sb))
        return 0;
    if (!ds_sb_ensure_capacity(sb, meta->length + text_len + 1))
        return 0;
 
    meta = ds_meta(sb->data);
 
    // Move content after insertion point
    memmove(sb->data + index + text_len, sb->data + index, meta->length - index + 1);
 
    // Insert the text
    memcpy(sb->data + index, text, text_len);
    meta->length += text_len;
 
    return 1;
}
 
DS_DEF void ds_builder_clear(ds_stringbuilder* sb) {
    if (!sb || !sb->data)
        return;
 
    if (!ds_sb_ensure_unique(sb))
        return;
 
    ds_internal* meta = ds_meta(sb->data);
    meta->length = 0;
    sb->data[0] = '\0';
}
 
DS_DEF ds_string ds_builder_to_string(ds_stringbuilder* sb) {
    if (!sb || !sb->data) {
        return NULL;
    }
 
    ds_internal* meta = ds_meta(sb->data);
 
    // Shrink to exact size
    size_t exact_size = sizeof(ds_internal) + meta->length + 1;
    void* old_block = (char*)sb->data - sizeof(ds_internal);
    void* shrunk_block = DS_REALLOC(old_block, exact_size);
 
    ds_string result;
    if (shrunk_block) {
        result = (char*)shrunk_block + sizeof(ds_internal);
        meta = (ds_internal*)shrunk_block;
    } else {
        result = sb->data; // Use original if realloc failed
    }
 
    // IMPORTANT: Mark StringBuilder as consumed to prevent reuse
    // This eliminates the complex copy-on-write bugs
    sb->data = NULL;
    sb->capacity = 0;
 
    return result;
}
 
DS_DEF size_t ds_builder_length(const ds_stringbuilder* sb) {
    if (!sb || !sb->data)
        return 0;
    ds_internal* meta = ds_meta(sb->data);
    return meta->length;
}
 
DS_DEF size_t ds_builder_capacity(const ds_stringbuilder* sb) { return sb ? sb->capacity : 0; }
 
DS_DEF const char* ds_builder_cstr(const ds_stringbuilder* sb) { return sb && sb->data ? sb->data : ""; }
 
#endif // DS_IMPLEMENTATION
 
#endif // DYNAMIC_STRING_H