~donmcc/astr

ref: 6a7af5061199752b6dc6c374b8162d4eec212169 astr/astr.3 -rw-r--r-- 1.9 KiB
6a7af506Don McCaughey Renamed functions with "_format" in their names. 1 year, 10 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
.Dd February 23, 2020
.Dt ASTR 3
.Os
.Sh NAME
.Nm astr_alloc_empty ,
.Nm astr_alloc_format ,
.Nm astr_alloc_format_args ,
.Nm astr_eq_bytes
.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" "..."
.Ft char *
.Fn astr_alloc_format_args "char const *format" "va_list arguments"
.Ft bool
.Fn astr_eq_bytes "char const s1" "char const s2"
.Sh DESCRIPTION
The
.Nm astr
library provides functions for working with dynamically allocated strings,
building on top of
.Fn vasprintf .
.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 _format
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 _args
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_format
and
.Fn astr_alloc_format_args
allocate formatted strings.
.Pp
.Fn astr_eq_bytes
compares two string pointers for equality in an encoding agnostic way.
The arguments
.Fa s1
and
.Fa s2
may be
.Dv NULL .
.Sh RETURN VALUES
.Fn astr_alloc_empty
returns a pointer to a zero-length string on success.
.Fn astr_alloc_format
and
.Fn astr_alloc_format_args
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_bytes
returns
.Dv true
if the two string pointers are equal or point to the same sequence of bytes.
.Sh SEE ALSO
.Xr free 3 ,
.Xr printf 3 ,
.Xr stdarg 3 ,
.Xr vasprintf 3
.Sh AUTHORS
.An Don McCaughey