dd613e6b87 · matheusbsbs/matheus-bagliano

@@ -1,6 +1,241 @@

1 strbuf API

2 ==========

3

4 -Talk about <strbuf.h>

4 +strbuf's are meant to be used with all the usual C string and memory

5 +APIs. Given that the length of the buffer is known, it's often better to

6 +use the mem* functions than a str* one (memchr vs. strchr e.g.).

7 +Though, one has to be careful about the fact that str* functions often

8 +stop on NULs and that strbufs may have embedded NULs.

9

6 -(Pierre, JC)

10 +An strbuf is NUL terminated for convenience, but no function in the

11 +strbuf API actually relies on the string being free of NULs.

12 +

13 +strbufs has some invariants that are very important to keep in mind:

14 +

15 +. The `buf` member is never NULL, so you it can be used in any usual C

16 +string operations safely. strbuf's _have_ to be initialized either by

17 +`strbuf_init()` or by `= STRBUF_INIT` before the invariants, though.

18 ++

19 +Do *not* assume anything on what `buf` really is (e.g. if it is

20 +allocated memory or not), use `strbuf_detach()` to unwrap a memory

21 +buffer from its strbuf shell in a safe way. That is the sole supported

22 +way. This will give you a malloced buffer that you can later `free()`.

23 ++

24 +However, it it totally safe to modify anything in the string pointed by

25 +the `buf` member, between the indices `0` and `len-1` (inclusive).

26 +

27 +. The `buf` member is a byte array that has at least `len + 1` bytes

28 + allocated. The extra byte is used to store a `'\0'`, allowing the

29 + `buf` member to be a valid C-string. Every strbuf function ensure this

30 + invariant is preserved.

31 ++

32 +NOTE: It is OK to "play" with the buffer directly if you work it this

33 + way:

34 ++

35 +----

36 +strbuf_grow(sb, SOME_SIZE); <1>

37 +strbuf_setlen(sb, sb->len + SOME_OTHER_SIZE);

38 +----

39 +<1> Here, the memory array starting at `sb->buf`, and of length

40 +`strbuf_avail(sb)` is all yours, and you can be sure that

41 +`strbuf_avail(sb)` is at least `SOME_SIZE`.

42 ++

43 +NOTE: `SOME_OTHER_SIZE` must be smaller or equal to `strbuf_avail(sb)`.

44 ++

45 +Doing so is safe, though if it has to be done in many places, adding the

46 +missing API to the strbuf module is the way to go.

47 ++

48 +WARNING: Do _not_ assume that the area that is yours is of size `alloc

49 +- 1` even if it's true in the current implementation. Alloc is somehow a

50 +"private" member that should not be messed with. Use `strbuf_avail()`

51 +instead.

52 +

53 +Data structures

54 +---------------

55 +

56 +* `struct strbuf`

57 +

58 +This is string buffer structure. The `len` member can be used to

59 +determine the current length of the string, and `buf` member provides access to

60 +the string itself.

61 +

62 +Functions

63 +---------

64 +

65 +* Life cycle

66 +

67 +`strbuf_init`::

68 +

69 + Initialize the structure. The second parameter can be zero or a bigger

70 + number to allocate memory, in case you want to prevent further reallocs.

71 +

72 +`strbuf_release`::

73 +

74 + Release a string buffer and the memory it used. You should not use the

75 + string buffer after using this function, unless you initialize it again.

76 +

77 +`strbuf_detach`::

78 +

79 + Detach the string from the strbuf and returns it; you now own the

80 + storage the string occupies and it is your responsibility from then on

81 + to release it with `free(3)` when you are done with it.

82 +

83 +`strbuf_attach`::

84 +

85 + Attach a string to a buffer. You should specify the string to attach,

86 + the current length of the string and the amount of allocated memory.

87 + The amount must be larger than the string length, because the string you

88 + pass is supposed to be a NUL-terminated string. This string _must_ be

89 + malloc()ed, and after attaching, the pointer cannot be relied upon

90 + anymore, and neither be free()d directly.

91 +

92 +`strbuf_swap`::

93 +

94 + Swap the contents of two string buffers.

95 +

96 +* Related to the size of the buffer

97 +

98 +`strbuf_avail`::

99 +

100 + Determine the amount of allocated but unused memory.

101 +

102 +`strbuf_grow`::

103 +

104 + Ensure that at least this amount of unused memory is available after

105 + `len`. This is used when you know a typical size for what you will add

106 + and want to avoid repetitive automatic resizing of the underlying buffer.

107 + This is never a needed operation, but can be critical for performance in

108 + some cases.

109 +

110 +`strbuf_setlen`::

111 +

112 + Set the length of the buffer to a given value. This function does *not*

113 + allocate new memory, so you should not perform a `strbuf_setlen()` to a

114 + length that is larger than `len + strbuf_avail()`. `strbuf_setlen()` is

115 + just meant as a 'please fix invariants from this strbuf I just messed

116 + with'.

117 +

118 +`strbuf_reset`::

119 +

120 + Empty the buffer by setting the size of it to zero.

121 +

122 +* Related to the contents of the buffer

123 +

124 +`strbuf_rtrim`::

125 +

126 + Strip whitespace from the end of a string.

127 +

128 +`strbuf_cmp`::

129 +

130 + Compare two buffers. Returns an integer less than, equal to, or greater

131 + than zero if the first buffer is found, respectively, to be less than,

132 + to match, or be greater than the second buffer.

133 +

134 +* Adding data to the buffer

135 +

136 +NOTE: All of these functions in this section will grow the buffer as

137 + necessary.

138 +

139 +`strbuf_addch`::

140 +

141 + Add a single character to the buffer.

142 +

143 +`strbuf_insert`::

144 +

145 + Insert data to the given position of the buffer. The remaining contents

146 + will be shifted, not overwritten.

147 +

148 +`strbuf_remove`::

149 +

150 + Remove given amount of data from a given position of the buffer.

151 +

152 +`strbuf_splice`::

153 +

154 + Remove the bytes between `pos..pos+len` and replace it with the given

155 + data.

156 +

157 +`strbuf_add`::

158 +

159 + Add data of given length to the buffer.

160 +

161 +`strbuf_addstr`::

162 +

163 +Add a NUL-terminated string to the buffer.

164 ++

165 +NOTE: This function will *always* be implemented as an inline or a macro

166 +that expands to:

167 ++

168 +----

169 +strbuf_add(..., s, strlen(s));

170 +----

171 ++

172 +Meaning that this is efficient to write things like:

173 ++

174 +----

175 +strbuf_addstr(sb, "immediate string");

176 +----

177 +

178 +`strbuf_addbuf`::

179 +

180 + Copy the contents of an other buffer at the end of the current one.

181 +

182 +`strbuf_adddup`::

183 +

184 + Copy part of the buffer from a given position till a given length to the

185 + end of the buffer.

186 +

187 +`strbuf_expand`::

188 +

189 + This function can be used to expand a format string containing

190 + placeholders. To that end, it parses the string and calls the specified

191 + function for every percent sign found.

192 ++

193 +The callback function is given a pointer to the character after the `%`

194 +and a pointer to the struct strbuf. It is expected to add the expanded

195 +version of the placeholder to the strbuf, e.g. to add a newline

196 +character if the letter `n` appears after a `%`. The function returns

197 +the length of the placeholder recognized and `strbuf_expand()` skips

198 +over it.

199 ++

200 +All other characters (non-percent and not skipped ones) are copied

201 +verbatim to the strbuf. If the callback returned zero, meaning that the

202 +placeholder is unknown, then the percent sign is copied, too.

203 ++

204 +In order to facilitate caching and to make it possible to give

205 +parameters to the callback, `strbuf_expand()` passes a context pointer,

206 +which can be used by the programmer of the callback as she sees fit.

207 +

208 +`strbuf_addf`::

209 +

210 + Add a formatted string to the buffer.

211 +

212 +`strbuf_fread`::

213 +

214 + Read a given size of data from a FILE* pointer to the buffer.

215 ++

216 +NOTE: The buffer is rewinded if the read fails. If -1 is returned,

217 +`errno` must be consulted, like you would do for `read(3)`.

218 +`strbuf_read()`, `strbuf_read_file()` and `strbuf_getline()` has the

219 +same behaviour as well.

220 +

221 +`strbuf_read`::

222 +

223 + Read the contents of a given file descriptor. The third argument can be

224 + used to give a hint about the file size, to avoid reallocs.

225 +

226 +`strbuf_read_file`::

227 +

228 + Read the contents of a file, specified by its path. The third argument

229 + can be used to give a hint about the file size, to avoid reallocs.

230 +

231 +`strbuf_getline`::

232 +

233 + Read a line from a FILE* pointer. The second argument specifies the line

234 + terminator character, typically `'\n'`.

235 +

236 +`stripspace`::

237 +

238 + Strip whitespace from a buffer. The second parameter controls if

239 + comments are considered contents to be removed or not.

240 +

241 +`launch_editor`::

Strbuf documentation: document most functions