about summary refs log tree commit diff
path: root/libste.3
blob: 994d12a8d39d73acdebc3e0774967f577464461f (plain) (blame)
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
.Dd November 5, 2021
.Dt LIBSTE 3
.Os
.Sh NAME
.Nm stecpy ,
.Nm stecpe ,
.Nm stechr ,
.Nm steprn
.Nd string library based on string ends
.Sh SYNOPSIS
.In ste.h
.Ft "char *"
.Fn stecpy "char *dst" "char *end" "const char *src"
.Ft "char *"
.Fn steccpy "char *dst" "char *end" "const char *src" "int c"
.Ft "char *"
.Fn stecpe "char *dst" "char *end" "const char *src" "const char *srcend"
.Ft "char *"
.Fn stechr "const char *src" "const char *end" "int c"
.Ft "char *"
.Fn steprn "char *dst" "char *end" "const char *fmt" "..."
.Sh DESCRIPTION
.Nm libste
provides five useful functions for dealing with strings.
.Pp
.Nm stecpy
copies the NUL-terminated string
.Fa src
to
.Fa dst ,
but writes no characters beyond
.Fa end .
If any characters are copied,
.Fa dst
will be NUL-terminated
and the return value is a pointer to the NUL byte.
On truncation,
.Fa end
is returned.
.Pp
.Nm steccpy
copies the NUL-terminated string
.Fa src
to
.Fa dst ,
stopping when the character
.Fa c
is found.
It writes no characters beyond
.Fa end .
If any characters are copied,
.Fa dst
will be NUL-terminated
and the return value is a pointer to the NUL byte.
On truncation,
.Fa end
is returned.
.Pp
.Nm stecpe
copies the string between
.Fa src
and
.Fa srcend
to
.Fa dst ,
but writes no characters beyond
.Fa end .
If any characters are copied,
.Fa dst
will be NUL-terminated
and the return value is a pointer to the NUL byte.
On truncation,
.Fa end
is returned.
.Pp
.Nm stechr
returns a pointer to the first occurence of
.Fa c
.Pq converted to a Vt char
in the NUL-terminated string pointed to by
.Fa src ,
but reads no characters beyond
.Fa end .
If
.Fa c
is not found,
.Nm stechr
returns a pointer to the first NUL byte in
.Fa src ,
or
.Fa end
if none was found.
.Pp
.Nm steprn
uses
.Xr vsnprintf 3
to write formatted output to
.Fa dst ,
but writes no characters beyond
.Fa end .
If any characters are written,
.Fa dst
will be NUL-terminated
and the return value is a pointer to the NUL byte.
On truncation,
.Fa end
is returned.
.Pp
Note that it is safe to pass the return value of all functions listed above
as argument for
.Fa dst
when the same
.Fa end
is reused.
In this case, the function call does nothing but return
.Fa dst
again.
At any point, truncation can be checked by comparing the return value to
.Fa end .
.\" .Sh RETURN VALUES
.\" .Sh SEE ALSO
.\" .Sh STANDARDS
.\" .Sh HISTORY
.Sh IMPLEMENTATION DETAILS
.Nm libste
is written in portable C99.
.Pp
Functions do not use vectorization to keep code size small
and because the inputs are expected to be small enough to not benefit from it.  
.Pp
The functions can be vendored or inlined into your codebase easily.
.Sh AUTHORS
.An Leah Neukirchen Aq Mt leah@vuxu.org
.Sh LICENSE
.Nm libste
is in the public domain.
.Pp
To the extent possible under law,
the creator of this work
has waived all copyright and related or
neighboring rights to this work.
.Pp
.Lk http://creativecommons.org/publicdomain/zero/1.0/