A string library for C99.
Build on Debian with the address sanitizer enabled.
Add functions for centering text in a given width.
Minimize #includes in "astr.h".


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.

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 that return newly allocated strings will contain _alloc in their names; the caller is responsible for calling free() on the returned pointer. Functions with _realloc in their names take a pointer to a string as an in-out parameter; these functions may reallocate the string, replacing the pointed-to string value. Functions with _format take a printf() style format string. Functions with _append in their name will add characters to the end of the given string. Functions that end with the suffix _from_va_list take variable arguments as a va_list object from stdarg.h.


char *

Allocate an empty string.

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

char *
astr_alloc_formatted_from_va_list(char const *format, va_list arguments);

Allocate a formatted string.

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_empty(char const *s);

Check if a string is NULL or zero-length.

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

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

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

astr_formatted_length_from_va_list(char const *format, va_list arguments);

Calculate the length in bytes needed for the formatted string.

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

astr_realloc_append_formatted_from_va_list(char **s, char const *format, va_list arguments);

Append formatted characters to the end of the given string, returning 0 on success and -1 on error. The parameter s may point to different address on success.

char *
astr_alloc_centered_formatted(unsigned width, char const *format, ...);

char *
astr_alloc_centered_formatted_from_va_list(unsigned width, 
                                           char const *format, 
                                           va_list arguments);

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


Building from repository source requires GNU Autotools.

#Building from Repository Source

Clone the repository then generate the configure script, configure and build.

git clone https://git.sr.ht/~donmcc/astr
cd astr
autoreconf -i
mkdir tmp && cd tmp
../configure && make && sudo make install


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