~donmcc/astr

f3b4c1fa29f1aeedce1aabf6b2f8a55673797313 — Don McCaughey 1 year, 8 months ago 6a7af50
Change _args suffix to _with_va_list.

Rename `_args` functions to `_with_va_list`:

    astr_alloc_formatted_with_va_list()
    astr_formatted_length_with_va_list()

Also updated the man page to reflect these changes and name changes from
the previous commit.
4 files changed, 51 insertions(+), 25 deletions(-)

M README.md
M astr.3
M astr.c
M astr.h
M README.md => README.md +3 -3
@@ 10,7 10,7 @@ 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 
Functions that end with the suffix `_from_va_list` take variable arguments as a 
`va_list` object from `stdarg.h`.

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


@@ 28,7 28,7 @@ Allocate an empty string.
Allocate a formatted string.

    char *
    astr_alloc_formatted_args(char const *format, va_list arguments);
    astr_alloc_formatted_from_va_list(char const *format, va_list arguments);

Allocate a formatted string using a `va_list` object.



@@ 43,7 43,7 @@ Compare the bytes of two strings for equality; `s1` and `s2` may be `NULL`.
Calculate the length in bytes needed for the formatted string.

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

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

M astr.3 => astr.3 +42 -16
@@ 3,26 3,34 @@
.Os
.Sh NAME
.Nm astr_alloc_empty ,
.Nm astr_alloc_format ,
.Nm astr_alloc_format_args ,
.Nm astr_eq_bytes
.Nm astr_alloc_formatted ,
.Nm astr_alloc_formatted_from_va_list ,
.Nm astr_eq ,
.Nm astr_formatted_length ,
.Nm astr_formatted_length_from_va_list
.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_format "char const *format" "..."
.Fn astr_alloc_formatted "char const *format" "..."
.Ft char *
.Fn astr_alloc_format_args "char const *format" "va_list arguments"
.Fn astr_alloc_formatted_from_va_list "char const *format" "va_list arguments"
.Ft bool
.Fn astr_eq_bytes "char const s1" "char const s2"
.Fn astr_eq "char const s1" "char const s2"
.Ft size_t
.Fn astr_formatted_length "char const *format" "..."
.Ft size_t
.Fn astr_formatted_length_from_va_list "char const *format" "va_list arguments"
.Sh DESCRIPTION
The
.Nm astr
library provides functions for working with dynamically allocated strings,
building on top of
.Fn vasprintf .
.Fn vasprintf
and
.Fn vsnprintf .
.Pp
All functions in the
.Nm astr


@@ 35,7 43,7 @@ in their name; the caller is responsible for calling
.Fn free
on the returned pointer.
Functions with
.Sy _format
.Sy _formatted
in their name take a
.Fa format
string as specified for


@@ 43,7 51,7 @@ string as specified for
along with zero or more additional arguments as determined by the given format
and produce formatted output.
Functions that end with the suffix
.Sy _args
.Sy _from_va_list
take a variable number of
.Fa arguments
as a


@@ 54,12 62,12 @@ object defined in
.Fn astr_alloc_empty
allocates an empty string.
.Pp
.Fn astr_alloc_format
.Fn astr_alloc_formatted
and
.Fn astr_alloc_format_args
.Fn astr_alloc_formatted_from_va_list
allocate formatted strings.
.Pp
.Fn astr_eq_bytes
.Fn astr_eq
compares two string pointers for equality in an encoding agnostic way.
The arguments
.Fa s1


@@ 67,12 75,18 @@ and
.Fa s2
may be
.Dv NULL .
.Pp
The
.Fn astr_formatted_length
and
.Fn astr_formatted_length_from_va_list
functions calculate the length in bytes required to hold the formatted string.
.Sh RETURN VALUES
.Fn astr_alloc_empty
returns a pointer to a zero-length string on success.
.Fn astr_alloc_format
.Fn astr_alloc_formatted
and
.Fn astr_alloc_format_args
.Fn astr_alloc_formatted_from_va_list
return a pointer to a formatted string on success.
.Pp
If there is an error, these functions return a


@@ 82,14 96,26 @@ pointer and set
to
.Er ENOMEM .
.Pp
.Fn astr_eq_bytes
.Fn astr_eq
returns
.Dv true
if the two string pointers are equal or point to the same sequence of bytes.
.Pp
.Fn astr_formatted_length
and
.Fn astr_formatted_length_from_va_list
return the number of bytes needed to store the formatted string, not including
the terminating null character on success.
.Pp
If there is an error, these functions return zero and set
.Va errno
to
.Er EINVAL .
.Sh SEE ALSO
.Xr free 3 ,
.Xr printf 3 ,
.Xr stdarg 3 ,
.Xr vasprintf 3
.Xr vasprintf 3 ,
.Xr vsnprintf 3
.Sh AUTHORS
.An Don McCaughey

M astr.c => astr.c +4 -4
@@ 9,14 9,14 @@ astr_alloc_formatted(char const *format, ...)
{
    va_list arguments;
    va_start(arguments, format);
    char *s = astr_alloc_formatted_args(format, arguments);
    char *s = astr_alloc_formatted_from_va_list(format, arguments);
    va_end(arguments);
    return s;
}


char *
astr_alloc_formatted_args(char const *format, va_list arguments)
astr_alloc_formatted_from_va_list(char const *format, va_list arguments)
{
    if (!format) {
        errno = EINVAL;


@@ 37,14 37,14 @@ astr_formatted_length(char const *format, ...)
{
    va_list arguments;
    va_start(arguments, format);
    size_t length = astr_formatted_length_args(format, arguments);
    size_t length = astr_formatted_length_from_va_list(format, arguments);
    va_end(arguments);
    return length;
}


size_t
astr_formatted_length_args(char const *format, va_list arguments)
astr_formatted_length_from_va_list(char const *format, va_list arguments)
{
    if (!format) {
        errno = EINVAL;

M astr.h => astr.h +2 -2
@@ 12,13 12,13 @@ char *
astr_alloc_formatted(char const *format, ...);

char *
astr_alloc_formatted_args(char const *format, va_list arguments);
astr_alloc_formatted_from_va_list(char const *format, va_list arguments);

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

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


inline char *