# astr

A C99 library for working with dynamically allocated strings.

[![builds.sr.ht status](https://builds.sr.ht/~donmcc/astr.svg)](https://builds.sr.ht/~donmcc/astr?)

## 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()`][1] function
brings to string building.

[1]: http://man7.org/linux/man-pages/man3/asprintf.3.html

### 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()`][2] 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`.

[2]: http://man7.org/linux/man-pages/man3/free.3.html

## 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 const 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 const 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 const 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][3].

[3]: https://www.gnu.org/software/automake/faq/autotools-faq.html

## 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][4] file
for details.

[4]: https://git.sr.ht/~donmcc/astr/tree/master/LICENSE