stdx_strbuilder.h

home

STDX - Dynamic String Builder for C Part of the STDX General Purpose C Library by marciovmf License: MIT https://github.com/marciovmf/stdx

Overview

This header provides a simple interface for constructing strings efficiently: - Dynamic growth as data is appended - Append strings, characters, substrings, and formatted text - Convert to null-terminated C string - Clear or destroy the builder when done

To customize how this module allocates memory, define X_STRBUILDER_ALLOC / X_STRBUILDER_REALLOC / X_STRBUILDER_FREE before including.

How to compile

To compile the implementation define X_IMPL_STRBUILDER in one source file before including this header.

Macro

X_STRBUILDER_VERSION_MAJOR

#define X_STRBUILDER_VERSION_MAJOR 1
Macro

X_STRBUILDER_VERSION_MINOR

#define X_STRBUILDER_VERSION_MINOR 0
Macro

X_STRBUILDER_VERSION_PATCH

#define X_STRBUILDER_VERSION_PATCH 0
Macro

STRBUILDER_STACK_BUFFER_SIZE

#define STRBUILDER_STACK_BUFFER_SIZE 255
Struct

XStrBuilder

typedef struct XStrBuilder{
  char *data;
  size_t capacity;
  size_t length;
}XStrBuilder;
Struct

XWStrBuilder

typedef struct XWStrBuilder{
  wchar_t *data;
  size_t capacity;
  size_t length;
}XWStrBuilder;
Macro

x_strbuilder_append_cstr

#define x_strbuilder_append_cstr(sb, str) x_strbuilder_append((sb), (str))
Function

x_strbuilder_create

Creates a XStrBuilder

XStrBuilder * x_strbuilder_create();

Parameters

(none)
@return pointer to the XStrBuilder or NULL if creation fails
Function

x_strbuilder_append

Appends a C-string to the builder

void x_strbuilder_append(
 XStrBuilder *sb,
 const char *str
);

Parameters

XStrBuilder *sb
Destination builder
const char *str
Source null-terminated string (NULL is ignored)
Function

x_strbuilder_append_char

Appends one character

void x_strbuilder_append_char(
 XStrBuilder *sb,
 char c
);

Parameters

XStrBuilder *sb
Destination builder
char c
Character to append
Function

x_strbuilder_append_format

Appends formatted text (printf-style)

void x_strbuilder_append_format(
 XStrBuilder *sb,
 const char *format,
 ...
);

Parameters

XStrBuilder *sb
Destination builder
const char *format
Format string (printf-style)
Function

x_strbuilder_append_substring

Appends a substring

void x_strbuilder_append_substring(
 XStrBuilder *sb,
 const char *start,
 size_t length
);

Parameters

XStrBuilder *sb
Destination builder
const char *start
Pointer to first byte
size_t length
Number of bytes to copy
Function

x_strbuilder_to_string

Returns internal buffer pointer

char * x_strbuilder_to_string(const XStrBuilder *sb);

Parameters

const XStrBuilder *sb
Builder to query

Returns

Pointer to internal NUL-terminated buffer (invalidated by later appends)

Function

x_strbuilder_destroy

Destroys the builder and frees memory

void x_strbuilder_destroy(XStrBuilder *sb);

Parameters

XStrBuilder *sb
Builder to destroy (may be NULL)
Function

x_strbuilder_clear

Clears the builder content

void x_strbuilder_clear(XStrBuilder *sb);

Parameters

XStrBuilder *sb
Builder to clear
Function

x_strbuilder_length

Returns current length in bytes

size_t x_strbuilder_length(XStrBuilder *sb);

Parameters

XStrBuilder *sb
Builder to query

Returns

Length in bytes (excluding the NUL)

Function

x_strbuilder_append_utf8_substring

Appends a UTF-8 substring by code-point range

void x_strbuilder_append_utf8_substring(
 XStrBuilder *sb,
 const char *utf8,
 size_t start_cp,
 size_t len_cp
);

Parameters

XStrBuilder *sb
Destination builder
const char *utf8
Source UTF-8 string
size_t start_cp
Start code-point index
size_t len_cp
Number of code points to append
Function

x_strbuilder_utf8_charlen

Counts UTF-8 code points contained in the builder

size_t x_strbuilder_utf8_charlen(const XStrBuilder *sb);

Parameters

const XStrBuilder *sb
Builder to query

Returns

Number of Unicode code points

Function

x_wstrbuilder_create

Creates a wide-character string builder param (none)

XWStrBuilder * x_wstrbuilder_create();

Returns

Pointer to builder or NULL on failure

Function

x_wstrbuilder_append

Appends a wide C-string

void x_wstrbuilder_append(
 XWStrBuilder *sb,
 const wchar_t *str
);

Parameters

XWStrBuilder *sb
Destination builder
const wchar_t *str
Source wide string (NULL is ignored)
Function

x_wstrbuilder_append_char

Appends one wide character

void x_wstrbuilder_append_char(
 XWStrBuilder *sb,
 wchar_t c
);

Parameters

XWStrBuilder *sb
Destination builder
wchar_t c
Character to append
Function

x_wstrbuilder_append_format

Appends formatted wide text (printf-style)

void x_wstrbuilder_append_format(
 XWStrBuilder *sb,
 const wchar_t *format,
 ...
);

Parameters

XWStrBuilder *sb
Destination builder
const wchar_t *format
Wide format string
Function

x_wstrbuilder_clear

Clears the wide builder content

void x_wstrbuilder_clear(XWStrBuilder *sb);

Parameters

XWStrBuilder *sb
Builder to clear
Function

x_wstrbuilder_destroy

Destroys the wide builder and frees memory

void x_wstrbuilder_destroy(XWStrBuilder *sb);

Parameters

XWStrBuilder *sb
Builder to destroy (may be NULL)
Function

x_wstrbuilder_to_string

Returns internal wide buffer pointer param sb Builder to query return Pointer to internal NUL-terminated wide buffer (invalidated by later appends)

wchar_t * x_wstrbuilder_to_string(const XWStrBuilder *sb);
Function

x_wstrbuilder_length

Returns current length in wide characters param sb Builder to query return Number of wchar_t (excluding the NUL)

size_t x_wstrbuilder_length(const XWStrBuilder *sb);
Macro

X_STRBUILDER_ALLOC

#define X_STRBUILDER_ALLOC(sz) malloc(sz)
Macro

X_STRBUILDER_REALLOC

#define X_STRBUILDER_REALLOC(p, sz) realloc((p), (sz))
Macro

X_STRBUILDER_FREE

#define X_STRBUILDER_FREE(p) free(p)
Function

x_wstrbuilder_grow

X_STRBUILDER_API void x_wstrbuilder_grow(
 XWStrBuilder *sb,
 size_t needed_len
);