#ifndef INCLUDED_C_STRINGBUFFER_H
#define INCLUDED_C_STRINGBUFFER_H

#ifndef INCLUDED_C_BASE_H
#include <c_Base.h>
#endif /*INCLUDED_C_BASE_H*/

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



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

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

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

c_err_t c_StringBuffer_Init(c_StringBuffer_t* self, c_size_t capacity);

void c_StringBuffer_Destroy(c_StringBuffer_t* self);

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_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(const c_StringBuffer_t* self, c_size_t index, c_size_t length, c_StringBuffer_t* out_substring);
c_err_t c_StringBuffer_Slice(const 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);


#endif /*INCLUDED_C_STRINGBUFFER_H*/