~donmcc/astr

A string library for C99.
Made `astr_alloc_formatted_from_va_list()` inline.
Reimplement `astr_alloc_formatted_from_va_list()`.
Added a better overview section.

refs

master
browse  log 

clone

read-only
https://git.sr.ht/~donmcc/astr
read/write
git@git.sr.ht:~donmcc/astr

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

astr

A C99 library for working with dynamically allocated strings.

Overview

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 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.

Functions

char *
astr_alloc_empty(void);

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.

int
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.

bool
astr_empty(char const *s);

Check if a string is NULL or zero-length.

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

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

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

size_t
astr_formatted_length_from_va_list(char const *format, va_list arguments);

Calculate the length in bytes needed for the formatted string.

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

int
astr_realloc_append_foramtted_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.

Dependencies

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

License

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