~donmcc/astr

ref: e770c72484e685ddc740c736b221439fb6071573 astr/astr.3 -rw-r--r-- 4.3 KiB
e770c724Don McCaughey Adding environment variables for OpenBSD build. 1 year, 1 month 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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
.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_cmp ,
.Nm astr_empty ,
.Nm astr_eq ,
.Nm astr_formatted_length ,
.Nm astr_formatted_length_from_va_list ,
.Nm astr_realloc_append_formatted ,
.Nm astr_realloc_append_formatted_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 int
.Fn astr_cmp "char const *s1" "char const *s2"
.Ft bool
.Fn astr_empty "char const *s"
.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"
.Ft int
.Fn astr_realloc_append_formatted "char **s" "char const *format"
.Ft int
.Fn astr_realloc_append_formatted_from_va_list "char **s" "char const *format" "va_list arguments"
.Sh DESCRIPTION
The
.Nm astr
library provides functions that make working with dynamically allocated strings
easier and less error prone.
All functions in
.Nm astr
accept
.Dv NULL
string pointers, treating them similarly to a zero-length string.
Reallocating functions make string building easier automatically resizing the
string as needed.
.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 that resize a string will contain
.Sy _realloc
in their name; they will take a pointer to a string as an
.Em in-out
parameter.
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 with
.Sy _append
in their name will add characters to the end of the given string.
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_cmp
compares the bytes of two strings.
The string pointer arguments
.Fa s1
and
.Fa s2
may be
.Dv NULL .
.Pp
.Fn astr_empty
tests if a given string pointer is
.Dv NULL
or zero-length.
.Pp
.Fn astr_eq
compares the bytes of two strings for equality.
The string pointer 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.
.Pp
The
.Fn astr_realloc_append_formatted
and
.Fn astr_realloc_append_foramtted_from_va_list
functions append formatted characters to a 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 EINVAL .
.Pp
.Fn astr_cmp
returns a negative integer if
.Fa s1
is ordered before
.Fa s2 ,
a positive integer if
.Fa s1
is ordered after
.Fa s2
and zero if
.Fa s1
equals
.Fa s2 .
A
.Dv NULL
string pointer is ordered before all
.Pf non- Dv NULL
string pointers.
.Pp
.Fn astr_empty
returns
.Dv true
if the string pointer is
.Dv NULL
or points to an empty string.
.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.
.Pp
On success,
.Fn astr_realloc_append_formatted
and
.Fn astr_realloc_append_foramtted_from_va_list
return 0 and
.Fa s
may contain a different string address.
.Pp
On failure, these functions return -1 and set
.Va errno
to
.Er EINVAL .
.Sh SEE ALSO
.Xr free 3 ,
.Xr printf 3 ,
.Xr stdarg 3
.Sh AUTHORS
.An Don McCaughey