~donmcc/astr

ref: f3b4c1fa29f1aeedce1aabf6b2f8a55673797313 astr/astr.3 -rw-r--r-- 2.6 KiB
f3b4c1faDon McCaughey Change _args suffix to _with_va_list. 1 year, 9 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
.Dd February 23, 2020
.Dt ASTR 3
.Os
.Sh NAME
.Nm astr_alloc_empty ,
.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_formatted "char const *format" "..."
.Ft char *
.Fn astr_alloc_formatted_from_va_list "char const *format" "va_list arguments"
.Ft bool
.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
and
.Fn vsnprintf .
.Pp
All functions in the
.Nm astr
library begin with the
.Sy astr_
prefix.
Functions that return newly allocated strings will contain
.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.
Functions that end with the suffix
.Sy _from_va_list
take a variable number of
.Fa arguments
as a
.Sy va_list
object defined in
.Xr stdarg 3 .
.Pp
.Fn astr_alloc_empty
allocates an empty string.
.Pp
.Fn astr_alloc_formatted
and
.Fn astr_alloc_formatted_from_va_list
allocate formatted strings.
.Pp
.Fn astr_eq
compares two string pointers for equality in an encoding agnostic way.
The arguments
.Fa s1
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_formatted
and
.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
.Dv NULL
pointer and set
.Va errno
to
.Er ENOMEM .
.Pp
.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 vsnprintf 3
.Sh AUTHORS
.An Don McCaughey