cstr.h

Go to the documentation of this file.

 
#ifndef CSTR_H
#define CSTR_H
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "macros.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* -------------------------------------------------------------------------
 * Platform / compiler helpers
 * ---------------------------------------------------------------------- */
 
#if defined(__GNUC__) || defined(__clang__)
#define CSTR_LIKELY(x)    __builtin_expect(!!(x), 1)
#define CSTR_UNLIKELY(x)  __builtin_expect(!!(x), 0)
#define CSTR_INLINE       static inline __attribute__((always_inline))
#define CSTR_NONNULL(...) __attribute__((nonnull(__VA_ARGS__)))
#define CSTR_PURE         __attribute__((pure))
#define CSTR_WARN_UNUSED  __attribute__((warn_unused_result))
#define CSTR_RESTRICT     __restrict__
#else
#define CSTR_LIKELY(x)   (x)
#define CSTR_UNLIKELY(x) (x)
#define CSTR_INLINE      static inline
#define CSTR_NONNULL(...)
#define CSTR_PURE
#define CSTR_WARN_UNUSED
#define CSTR_RESTRICT
#endif
 
/* -------------------------------------------------------------------------
 * Constants
 * ---------------------------------------------------------------------- */
 
#define CSTR_MAX_LEN ((uint32_t)0x7FFFFFFFu)
 
#define CSTR_SSO_CAP 16u /* 15 usable chars + NUL */
 
#define CSTR_HEAP_FLAG ((uint32_t)0x80000000u)
 
#define CSTR_NPOS (-1)
 
/* Minimum heap allocation to avoid tiny reallocs */
#define CSTR_MIN_HEAP 32u
 
/* -------------------------------------------------------------------------
 * Core struct  (32 bytes on 64-bit systems)
 * ---------------------------------------------------------------------- */
 
typedef struct cstr {
    char* data;             
    uint32_t length;        
    uint32_t capacity;      
    char buf[CSTR_SSO_CAP]; 
} cstr;
 
#ifndef STATIC_ASSERT
#if defined(__cplusplus)
#define STATIC_ASSERT(cond, msg) static_assert(cond, msg)
#else
#define STATIC_ASSERT(cond, msg) _Static_assert(cond, msg)
#endif
#endif
 
/* Compile-time layout assertions */
#if defined(__GNUC__) || defined(__clang__)
STATIC_ASSERT(sizeof(cstr) == 32, "cstr must be exactly 32 bytes");
#endif
 
/* -------------------------------------------------------------------------
 * Lightweight string view
 * ---------------------------------------------------------------------- */
 
typedef struct {
    const char* data;
    uint32_t length;
} cstr_view;
 
/* -------------------------------------------------------------------------
 * Internal predicates (inlined, zero overhead)
 * ---------------------------------------------------------------------- */
 
CSTR_INLINE bool cstr_is_heap(const cstr* s) CSTR_PURE;
CSTR_INLINE bool cstr_is_heap(const cstr* s) { return (s->capacity & CSTR_HEAP_FLAG) != 0; }
 
CSTR_INLINE uint32_t cstr_heap_cap(const cstr* s) CSTR_PURE;
CSTR_INLINE uint32_t cstr_heap_cap(const cstr* s) { return s->capacity & ~CSTR_HEAP_FLAG; }
 
/* -------------------------------------------------------------------------
 * Public API — information
 * ---------------------------------------------------------------------- */
 
CSTR_INLINE size_t cstr_len(const cstr* s) CSTR_PURE;
CSTR_INLINE size_t cstr_len(const cstr* s) { return CSTR_LIKELY(s != NULL) ? (size_t)s->length : 0; }
 
CSTR_INLINE size_t cstr_capacity(const cstr* s) CSTR_PURE;
CSTR_INLINE size_t cstr_capacity(const cstr* s) {
    if (CSTR_UNLIKELY(s == NULL)) return 0;
    return cstr_is_heap(s) ? (size_t)cstr_heap_cap(s) : (size_t)(CSTR_SSO_CAP - 1);
}
 
CSTR_INLINE bool cstr_empty(const cstr* s) CSTR_PURE;
CSTR_INLINE bool cstr_empty(const cstr* s) { return CSTR_UNLIKELY(s == NULL) || s->length == 0; }
 
CSTR_INLINE bool cstr_allocated(const cstr* s) CSTR_PURE;
CSTR_INLINE bool cstr_allocated(const cstr* s) { return CSTR_LIKELY(s != NULL) && cstr_is_heap(s); }
 
/* -------------------------------------------------------------------------
 * Public API — data access
 * ---------------------------------------------------------------------- */
 
CSTR_INLINE char* cstr_data(cstr* s) CSTR_PURE;
CSTR_INLINE char* cstr_data(cstr* s) { return CSTR_LIKELY(s != NULL) ? s->data : NULL; }
 
CSTR_INLINE const char* cstr_data_const(const cstr* s) CSTR_PURE;
CSTR_INLINE const char* cstr_data_const(const cstr* s) { return CSTR_LIKELY(s != NULL) ? s->data : NULL; }
 
CSTR_INLINE char cstr_at(const cstr* s, size_t index) CSTR_PURE;
CSTR_INLINE char cstr_at(const cstr* s, size_t index) {
    if (CSTR_UNLIKELY(!s) || CSTR_UNLIKELY(index >= (size_t)s->length)) return '\0';
    return s->data[index];
}
 
CSTR_INLINE cstr_view cstr_as_view(const cstr* s);
CSTR_INLINE cstr_view cstr_as_view(const cstr* s) {
    cstr_view v = {NULL, 0};
    if (CSTR_LIKELY(s != NULL)) {
        v.data   = s->data;
        v.length = s->length;
    }
    return v;
}
 
/* -------------------------------------------------------------------------
 * Lifecycle
 * ---------------------------------------------------------------------- */
 
CSTR_INLINE void cstr_init_inplace(cstr* s);
CSTR_INLINE void cstr_init_inplace(cstr* s) {
    s->buf[0]   = '\0';
    s->data     = s->buf;
    s->length   = 0;
    s->capacity = 0; /* SSO, no heap flag */
}
 
cstr* cstr_init(size_t initial_capacity) CSTR_WARN_UNUSED;
 
cstr* cstr_new(const char* input) CSTR_WARN_UNUSED;
 
cstr* cstr_new_len(const char* data, size_t length) CSTR_WARN_UNUSED;
 
void cstr_free(cstr* s);
 
void cstr_drop(cstr* s);
 
void cstr_debug(const cstr* s);
 
/* -------------------------------------------------------------------------
 * Capacity management
 * ---------------------------------------------------------------------- */
 
bool cstr_reserve(cstr* s, size_t capacity) CSTR_NONNULL(1) CSTR_WARN_UNUSED;
 
CSTR_INLINE bool cstr_resize(cstr* s, size_t capacity) CSTR_NONNULL(1) CSTR_WARN_UNUSED;
CSTR_INLINE bool cstr_resize(cstr* s, size_t capacity) { return cstr_reserve(s, capacity); }
 
void cstr_shrink_to_fit(cstr* s) CSTR_NONNULL(1);
 
/* -------------------------------------------------------------------------
 * Mutation
 * ---------------------------------------------------------------------- */
 
CSTR_INLINE void cstr_clear(cstr* s);
CSTR_INLINE void cstr_clear(cstr* s) {
    if (CSTR_LIKELY(s != NULL)) {
        s->length  = 0;
        s->data[0] = '\0';
    }
}
 
bool cstr_append(cstr* s, const char* CSTR_RESTRICT append) CSTR_NONNULL(1, 2);
 
bool cstr_append_cstr(cstr* s, const cstr* append) CSTR_NONNULL(1, 2);
 
bool cstr_ncat(cstr* dest, const cstr* src, size_t n) CSTR_NONNULL(1, 2);
 
CSTR_INLINE bool cstr_cat(cstr* dest, const cstr* src) CSTR_NONNULL(1, 2);
CSTR_INLINE bool cstr_cat(cstr* dest, const cstr* src) { return cstr_append_cstr(dest, src); }
 
CSTR_INLINE bool cstr_append_fast(cstr* s, const char* CSTR_RESTRICT append) CSTR_NONNULL(1, 2);
CSTR_INLINE bool cstr_append_fast(cstr* s, const char* CSTR_RESTRICT append) {
    size_t n  = strlen(append);
    char* dst = s->data + s->length;
    memcpy(dst, append, n + 1); /* includes NUL */
    s->length += (uint32_t)n;
    return true;
}
 
bool cstr_append_char(cstr* s, char c) CSTR_NONNULL(1);
 
PRINTF_FORMAT(1, 2) cstr* cstr_format(const char* format, ...) CSTR_WARN_UNUSED;
 
PRINTF_FORMAT(2, 3) bool cstr_append_fmt(cstr* s, const char* format, ...) CSTR_NONNULL(1, 2);
 
bool cstr_prepend(cstr* s, const char* prepend) CSTR_NONNULL(1, 2);
 
bool cstr_prepend_cstr(cstr* s, const cstr* prepend) CSTR_NONNULL(1, 2);
 
bool cstr_prepend_fast(cstr* s, const char* prepend) CSTR_NONNULL(1, 2);
 
bool cstr_insert(cstr* s, size_t index, const char* insert) CSTR_NONNULL(1, 3);
 
bool cstr_insert_cstr(cstr* s, size_t index, const cstr* insert) CSTR_NONNULL(1, 3);
 
bool cstr_remove(cstr* s, size_t index, size_t count) CSTR_NONNULL(1);
 
size_t cstr_remove_all(cstr* s, const char* substr) CSTR_NONNULL(1, 2);
size_t cstr_remove_all_cstr(cstr* s, const cstr* substr) CSTR_NONNULL(1, 2);
 
void cstr_remove_char(cstr* s, char c) CSTR_NONNULL(1);
 
void cstr_remove_substr(cstr* str, size_t start, size_t substr_length) CSTR_NONNULL(1);
 
bool cstr_copy(cstr* dest, const cstr* src) CSTR_NONNULL(1, 2);
 
CSTR_INLINE bool cstr_assign(cstr* dest, const cstr* src) CSTR_NONNULL(1, 2);
CSTR_INLINE bool cstr_assign(cstr* dest, const cstr* src) { return cstr_copy(dest, src); }
 
/* -------------------------------------------------------------------------
 * Case conversion & formatting
 * ---------------------------------------------------------------------- */
 
void cstr_lower(cstr* s) CSTR_NONNULL(1);
void cstr_upper(cstr* s) CSTR_NONNULL(1);
bool cstr_snakecase(cstr* s) CSTR_NONNULL(1) CSTR_WARN_UNUSED;
void cstr_camelcase(cstr* s) CSTR_NONNULL(1);
void cstr_pascalcase(cstr* s) CSTR_NONNULL(1);
void cstr_titlecase(cstr* s) CSTR_NONNULL(1);
 
/* -------------------------------------------------------------------------
 * Trim
 * ---------------------------------------------------------------------- */
 
void cstr_trim(cstr* s) CSTR_NONNULL(1);
void cstr_rtrim(cstr* s) CSTR_NONNULL(1);
void cstr_ltrim(cstr* s) CSTR_NONNULL(1);
void cstr_trim_chars(cstr* s, const char* chars) CSTR_NONNULL(1, 2);
 
/* -------------------------------------------------------------------------
 * Comparison & search
 * ---------------------------------------------------------------------- */
 
int cstr_cmp(const cstr* s1, const cstr* s2) CSTR_PURE;
int cstr_ncmp(const cstr* s1, const cstr* s2, size_t n) CSTR_PURE;
 
CSTR_INLINE bool cstr_equals(const cstr* s1, const cstr* s2) CSTR_PURE;
CSTR_INLINE bool cstr_equals(const cstr* s1, const cstr* s2) {
    if (s1 == s2) return true;
    if (!s1 || !s2) return false;
    if (s1->length != s2->length) return false;
    return memcmp(s1->data, s2->data, s1->length) == 0;
}
 
bool cstr_starts_with(const cstr* s, const char* prefix) CSTR_NONNULL(1, 2) CSTR_PURE;
bool cstr_starts_with_cstr(const cstr* s, const cstr* prefix) CSTR_NONNULL(1, 2) CSTR_PURE;
bool cstr_ends_with(const cstr* s, const char* suffix) CSTR_NONNULL(1, 2) CSTR_PURE;
bool cstr_ends_with_cstr(const cstr* s, const cstr* suffix) CSTR_NONNULL(1, 2) CSTR_PURE;
 
int cstr_find(const cstr* s, const char* substr) CSTR_NONNULL(1, 2) CSTR_PURE;
int cstr_find_cstr(const cstr* s, const cstr* substr) CSTR_NONNULL(1, 2) CSTR_PURE;
 
int cstr_rfind(const cstr* s, const char* substr) CSTR_NONNULL(1, 2) CSTR_PURE;
int cstr_rfind_cstr(const cstr* s, const cstr* substr) CSTR_NONNULL(1, 2) CSTR_PURE;
 
CSTR_INLINE bool cstr_contains(const cstr* s, const char* substr) CSTR_NONNULL(1, 2) CSTR_PURE;
CSTR_INLINE bool cstr_contains(const cstr* s, const char* substr) { return cstr_find(s, substr) != CSTR_NPOS; }
 
CSTR_INLINE bool cstr_contains_cstr(const cstr* s, const cstr* sub) CSTR_NONNULL(1, 2) CSTR_PURE;
CSTR_INLINE bool cstr_contains_cstr(const cstr* s, const cstr* sub) { return cstr_find_cstr(s, sub) != CSTR_NPOS; }
 
size_t cstr_count_substr(const cstr* s, const char* substr) CSTR_NONNULL(1, 2) CSTR_PURE;
size_t cstr_count_substr_cstr(const cstr* s, const cstr* substr) CSTR_NONNULL(1, 2) CSTR_PURE;
 
/* -------------------------------------------------------------------------
 * Substrings & replacement  (all return new cstr — caller must free)
 * ---------------------------------------------------------------------- */
 
cstr* cstr_substr(const cstr* s, size_t start, size_t length) CSTR_NONNULL(1) CSTR_WARN_UNUSED;
cstr* cstr_replace(const cstr* s, const char* old_str, const char* new_str) CSTR_NONNULL(1, 2, 3) CSTR_WARN_UNUSED;
cstr* cstr_replace_all(const cstr* s, const char* old_str, const char* new_str) CSTR_NONNULL(1, 2, 3) CSTR_WARN_UNUSED;
 
/* -------------------------------------------------------------------------
 * Split & join
 * ---------------------------------------------------------------------- */
 
cstr** cstr_split(const cstr* s, const char* delim, size_t* count_out) CSTR_NONNULL(1, 3) CSTR_WARN_UNUSED;
 
cstr* cstr_join(const cstr** strings, size_t count, const char* delim) CSTR_WARN_UNUSED;
 
/* -------------------------------------------------------------------------
 * Reverse
 * ---------------------------------------------------------------------- */
 
cstr* cstr_reverse(const cstr* s) CSTR_NONNULL(1) CSTR_WARN_UNUSED;
void cstr_reverse_inplace(cstr* s) CSTR_NONNULL(1);
 
#ifdef __cplusplus
}
#endif
 
#endif /* CSTR_H */