A string library for C99
Fix overly aggressive rename.
Add `BUILD_TESTING` build option.
Add `CHECK_ARG()` macro to `astr.c`.


browse  log 



You can also use your local clone with git send-email.


A C99 library for working with dynamically allocated strings.

builds.sr.ht status


astr is a library of functions that make working with dynamically allocated strings easier and less error prone. All functions in astr accept NULL string pointers, treating them similarly to a zero-length string. Reallocating functions make string building easier by automatically resizing the string as needed. All allocations are checked; astr will call abort() if memory allocation fails.

astr was inspired by the improvements that the asprintf() function brings to string building.

#Naming Conventions

All functions in astr begin with the astr_ prefix. Functions with _f in their name take a printf() style format string. Functions with _cat in their name will add characters to the end of the given string, returning a new string. Functions that end with the suffix _va take variable arguments as a va_list object from stdarg.h.


All astr functions that return a char * value are returning a dynamically allocated string; the caller is responsible for calling free() on the returned pointer. It is not necessary to check these returned values for NULL; astr checks all memory allocations and will call abort() on memory exhaustion. If the first parameter of a function is a char * value, the address of that string may be invalid after the function is called.


char *
astr_dup(char const *s);

Duplicate a string; s may be NULL.

char *

Allocate an empty string.

char *
astr_f(char const *format, ...);

char *
astr_f_va(char const *format, va_list args);

Allocate a formatted string.

char *
astr_cat_f(char *s, char const *format, ...);

char *
astr_cat_f_va(char *s, char const *format, va_list args);

Append formatted characters to the end of the given string, returning the new string; the address of the original string may be invalid after this function is called.

char *
astr_centered_f(int width, char const *format, ...);

char *
astr_centered_f_va(int width, char const *format, va_list args);

Allocate a formatted string centered in a string of the given width. The formatted string is not truncated if it is wider than width.

astr_cmp(char const *s1, char const *s2);

Compare the bytes of two strings; s1 and s2 may be NULL. The return value is negative if s1 is ordered before s2, positive if s1 is ordered after s2 and zero if s1 equals s2. A NULL string pointers is ordered before all non-NULL string pointers.

astr_eq(char const *s1, char const *s2);

Compare the bytes of two strings for equality; s1 and s2 may be NULL.

astr_is_empty(char const *s);

Check if a string is NULL or zero-length.

astr_len(char const *s);

Calculate the length in bytes of a string; s may be NULL.

astr_len_f(char const *format, ...);

astr_len_f_va(char const *format, va_list args);

Calculate the length in bytes needed for the formatted string.


Building requires CMake 3.15 or later.

#Building from Repository Source

Clone the repository, generate the build system and build.

git clone https://git.sr.ht/~donmcc/astr
cd astr
cmake -S . -B tmp
cmake --build tmp
cmake --install tmp

To run tests:

cmake --build tmp --target all test

#Build Options

To build with the AddressSanitizer enabled, set the ADDRESS-SANITIZER option to ON.


Set the BUILD_TESTING option to OFF to disable building tests. (It's ON by default.)

cmake -S . -B tmp -DBUILD_TESTING=OFF

Set the WALL option to ON turns on additional warnings using the -Wall compiler flag and also treats warnings as errors. WALL is off by default but is recommended for development and integration builds.

cmake -S . -B tmp -DWALL=ON


astr is made available under a BSD-style license; see the LICENSE file for details.