~donmcc/astr

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

refs

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

builds.sr.ht status

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

#Usage

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.

#Functions

char *
astr_dup(char const *s);

Duplicate a string; s may be NULL.

char *
astr_empty(void);

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.

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_eq(char const *s1, char const *s2);

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

bool
astr_is_empty(char const *s);

Check if a string is NULL or zero-length.

int
astr_len(char const *s);

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

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

int
astr_len_f_va(char const *format, va_list args);

Calculate the length in bytes needed for the formatted string.

#Dependencies

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.

cmake -S . -B tmp -DADDRESS_SANITIZER=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

#License

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