~donmcc/astr

ac3df2b0fe8137392c52135183d878a914b999e6 — Don McCaughey 1 year, 9 months ago 7aeb198
Added `astr_alloc_formatted()` function.

Also added tests for the function and documentation to the man page and
the readme file.
5 files changed, 86 insertions(+), 11 deletions(-)

M README.md
M astr.3
M astr.c
M astr.h
M astr_tests.c
M README.md => README.md +5 -0
@@ 19,6 19,11 @@ responsible for calling [`free()`][1] on the returned pointer.

Allocate an empty string.

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

Allocate a formatted string.

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

M astr.3 => astr.3 +28 -11
@@ 1,15 1,18 @@
.\" Modified from man(1) of FreeBSD, the NetBSD mdoc.template and mdoc.samples
.\" See man mdoc for the short list of editing options
.Dd February 22, 2020
.Dd February 23, 2020
.Dt ASTR 3
.Os
.Sh NAME
.Nm astr_alloc_empty
.Nm astr_alloc_empty ,
.Nm astr_alloc_formatted
.Nd functions for working with dynamically allocated strings.
.Sh SYNOPSIS
.In astr.h
.Ft char *
.Fn astr_alloc_empty "void"
.Ft char *
.Fn astr_alloc_formatted "char const *format" "..."
.Sh DESCRIPTION
The
.Nm astr


@@ 17,31 20,45 @@ library provides functions for working with dynamically allocated strings,
building on top of
.Fn vasprintf .
.Pp
All functions in
All functions in the
.Nm astr
begin with the
.Sy astr_
library begin with the
.Sy astr
prefix.
Functions that return newly allocated strings will contain
.Sy alloc_
.Sy alloc
in their name; the caller is responsible for calling
.Fn free
on the returned pointer.
Functions with
.Sy formatted
in their name take a
.Fa format
string as specified for
.Xr printf 3
along with zero or more additional arguments as determined by the given format
and produce formatted output.
.Pp
.Fn astr_alloc_empty
allocates an empty string.
.Pp
.Fn astr_alloc_formatted
allocates a formatted string.
.Sh RETURN VALUES
On success,
.Fn astr_alloc_empty
returns a pointer to a zero-length string.
If there is an error, a
returns a pointer to a zero-length string on success.
.Fn astr_alloc_formatted
returns a pointer to a formatted string on success.
.Pp
If there is an error, these functions return a
.Dv NULL
pointer is returned and
pointer and set
.Va errno
is set to
to
.Er ENOMEM .
.Sh SEE ALSO
.Xr free 3 ,
.Xr printf 3 ,
.Xr vasprintf 3
.Sh AUTHORS
.An Don McCaughey

M astr.c => astr.c +24 -0
@@ 1,6 1,30 @@
#include "astr.h"

#include <errno.h>
#include <stdarg.h>
#include <stdio.h>


extern char *
astr_alloc_empty(void);


char *
astr_alloc_formatted(char const *format, ...)
{
    if (!format) {
        errno = EINVAL;
        return NULL;
    }

    char *s;

    va_list arguments;
    va_start(arguments, format);
    int chars_printed = vasprintf(&s, format, arguments);
    va_end(arguments);

    if (chars_printed < 0) return NULL;
    return s;
}


M astr.h => astr.h +3 -0
@@ 11,6 11,9 @@ astr_alloc_empty(void)
    return calloc(1, sizeof(char));
}

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


#endif


M astr_tests.c => astr_tests.c +26 -0
@@ 1,4 1,5 @@
#include <assert.h>
#include <errno.h>
#include <string.h>
#include "astr.h"



@@ 13,10 14,35 @@ test_astr_alloc_empty(void)
}


static void
test_astr_alloc_formatted(void)
{

    char *s = astr_alloc_formatted("answer: %i", 42);
    assert(s);
    assert(10 == strlen(s));
    assert(0 == strcmp("answer: 42", s));
    free(s);
}


static void
test_astr_alloc_formatted_for_NULL_format(void)
{
    errno = 0;
    char *s = astr_alloc_formatted(NULL);
    assert(!s);
    assert(EINVAL == errno);
    free(s);
}


int
main(int argc, char *argv[])
{
    test_astr_alloc_empty();
    test_astr_alloc_formatted();
    test_astr_alloc_formatted_for_NULL_format();
    return EXIT_SUCCESS;
}