# 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

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()`][1] on the returned pointer.
Functions with `_format` take a `printf()` style format string.
Functions that end with the suffix `_args` take variable arguments as a 
`va_list` object from `stdarg.h`.

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

## Functions

    char *
    astr_alloc_empty(void);

Allocate an empty string.

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

Allocate a formatted string.

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

Allocate a formatted string using a `va_list` object.

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

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

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

Calculate the length in bytes needed for the formatted string.

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

Calculate the length in bytes needed for the formatted string using a `va_list`
object.

## Dependencies
`astr` requires that `<stdio.h>` defines the [`vasprintf()`][2] and
[`vsnprintf()`][3] functions.
Building from repository source requires [GNU Autotools][4].

[2]: http://man7.org/linux/man-pages/man3/asprintf.3.html
[3]: http://man7.org/linux/man-pages/man3/printf.3.html
[4]: 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