cKit/Foundation/c_StringBuffer.h

#ifndef INCLUDED_C_STRINGBUFFER_H
#define INCLUDED_C_STRINGBUFFER_H

#ifndef INCLUDED_C_TYPES_H
#include <c_Types.h>
#endif /*INCLUDED_C_TYPES_H*/

#ifndef INCLUDED_STDARG_H
#define INCLUDED_STDARG_H
#include <stdarg.h>
#endif /*INCLUDED_STDARG_H*/

#ifndef INCLUDED_C_ALLOCATOR_H
#include <c_Allocator.h>
#endif /*INCLUDED_C_ALLOCATOR_H*/



/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

typedef struct {
    char* buffer;
    c_size_t capacity;
    c_size_t size;
    c_Allocator_t allocator;
}c_StringBuffer_t;

/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

C_STATIC_FORCE_INLINE
c_size_t c_StringBuffer_Size(c_StringBuffer_t* self) {
    if (!self) return 0;
    return self->size;
}

C_STATIC_FORCE_INLINE
const char* c_StringBuffer_CStr(c_StringBuffer_t* self) {
    if (!self) return NULL;
    return self->buffer;
}

/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

c_err_t c_StringBuffer_Init(c_StringBuffer_t* self, c_size_t capacity, c_Allocator_t* allocator);

void c_StringBuffer_Destroy(c_StringBuffer_t* self);

c_err_t c_StringBuffer_Resize(c_StringBuffer_t* self, c_size_t new_capacity);

c_err_t c_StringBuffer_Append(c_StringBuffer_t* self, const char* string, c_size_t length);

c_err_t c_StringBuffer_Prepend(c_StringBuffer_t* self, const char* string, c_size_t length);

c_err_t c_StringBuffer_InsertAt(c_StringBuffer_t* self, c_size_t index, const char* string, c_size_t length);

c_err_t c_StringBuffer_RemoveAt(c_StringBuffer_t* self, c_size_t index, c_size_t length);

void c_StringBuffer_Clear(c_StringBuffer_t* self);

c_err_t c_StringBuffer_AppendChar(c_StringBuffer_t* self, char ch);
c_err_t c_StringBuffer_AppendStr(c_StringBuffer_t* self, const char* string);
c_err_t c_StringBuffer_PrependStr(c_StringBuffer_t* self, const char* string);
c_err_t c_StringBuffer_InsertStrAt(c_StringBuffer_t* self, const char* string, c_size_t index);

c_err_t c_StringBuffer_CopyTo(c_StringBuffer_t* self, c_size_t index, c_size_t length, char* buffer, c_size_t buffer_length);

c_err_t c_StringBuffer_Printf(c_StringBuffer_t* self, const char* format, ...);
c_err_t c_StringBuffer_PrintfAt(c_StringBuffer_t* self, c_size_t index, const char* format, ...);

c_err_t c_StringBuffer_VPrintf(c_StringBuffer_t* self, const char* format, va_list args);
c_err_t c_StringBuffer_VPrintfAt(c_StringBuffer_t* self, c_size_t index, const char* format, va_list args);

c_err_t c_StringBuffer_AppendTimestamp(c_StringBuffer_t* self, const char* format, const struct tm* time_info);
c_err_t c_StringBuffer_AppendCurrentTimestamp(c_StringBuffer_t* self, const char* format, int use_utc);
c_err_t c_StringBuffer_InsertTimestampAt(c_StringBuffer_t* self, c_size_t index, const char* format, const struct tm* time_info);

c_index_t c_StringBuffer_IndexOfStr(c_StringBuffer_t* self, c_size_t start_index, const char* substr);
c_index_t c_StringBuffer_IndexOfChar(c_StringBuffer_t* self, c_size_t start_index, char target);
c_index_t c_StringBuffer_LastIndexOfStr(c_StringBuffer_t* self, c_size_t start_index, const char* substr);
c_index_t c_StringBuffer_LastIndexOfChar(c_StringBuffer_t* self, c_size_t start_index, char target);

c_err_t c_StringBuffer_ReplaceStr(c_StringBuffer_t* self, const char* old_str, const char* new_str);

c_err_t c_StringBuffer_Trim(c_StringBuffer_t* self);
c_err_t c_StringBuffer_TrimLeft(c_StringBuffer_t* self);
c_err_t c_StringBuffer_TrimRight(c_StringBuffer_t* self);

c_err_t c_StringBuffer_ToLower(c_StringBuffer_t* self);
c_err_t c_StringBuffer_ToUpper(c_StringBuffer_t* self);

/*
 * 重新设计的 Split 函数
 * @param self: 原始字符串缓冲区指针
 * @param delimiter: 分隔符字符串（不能为 NULL 或空字符串）
 * @param out_tokens: 输出参数，用于接收分配的 c_StringBuffer_t 结构体数组指针
 * @param out_count: 输出参数，用于接收拆分出来的 Token 总数
 */
c_err_t c_StringBuffer_Split(c_StringBuffer_t* self, const char* delimiter, c_StringBuffer_t** out_tokens, c_size_t* out_count);

c_err_t c_StringBuffer_Join(c_StringBuffer_t* self, const c_StringBuffer_t tokens[], c_size_t count, const char* separator);

int c_StringBuffer_Equals(const c_StringBuffer_t* self, const char* string);
int c_StringBuffer_EqualsIgnoreCase(const c_StringBuffer_t* self, const char* string);

int c_StringBuffer_Compare(const c_StringBuffer_t* self, const char* string);
c_err_t c_StringBuffer_Reverse(c_StringBuffer_t* self);

c_err_t c_StringBuffer_Substr(c_StringBuffer_t* self, c_size_t index, c_size_t length, c_StringBuffer_t* out_substring);
c_err_t c_StringBuffer_Slice(c_StringBuffer_t* self, c_size_t start_index, c_size_t end_index, c_StringBuffer_t* out_slice);

/*
 * Parses an unsigned long value from the buffer starting at a specific index.
 * @param self: The string buffer instance.
 * @param start_index: The index position to start scanning from.
 * @param base: The number base system to parse (0, 2-36).
 * @param out_value: Destination pointer for the parsed unsigned long.
 * @param out_end_index: Optional destination pointer for the index of the first character after the number.
 */
c_err_t c_StringBuffer_strtoul(const c_StringBuffer_t* self, c_size_t start_index, int base, unsigned long* out_value, c_size_t* out_end_index);


/**
 * Set the logical character length of the string buffer.
 * If the new length is less than the current size, the string is truncated.
 * If the new length is greater, the buffer expands and is zero-padded.
 *
 * @param sb         Pointer to the active c_StringBuffer_t instance
 * @param new_length The targeted logical length boundary to apply
 * @return
 *  - C_ERR_OK if success
 *  - C_ERR_PARAM if parameters are invalid
 *  - C_ERR_NOMEM if expansion fails due to system exhaustion
 */
c_err_t c_StringBuffer_SetLength(c_StringBuffer_t* sb, c_size_t new_length);


c_err_t c_StringBuffer_PopBack(c_StringBuffer_t* self);

#endif /*INCLUDED_C_STRINGBUFFER_H*/