strbuf_split*(): document functions
Document strbuf_split_buf(), strbuf_split_str(), strbuf_split_max(), strbuf_split(), and strbuf_list_free() in the header file and in api-strbuf.txt. (These functions were previously completely undocumented.) Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Signed-off-by: Jeff King <peff@peff.net>
Michael Haggerty committed
Nov 4, 2012 at 07:46 UTC
06379a65098212aef05010598ba3a8549bd78474
2 files changed
+49
Documentation/technical/api-strbuf.txt
+16
@@ -279,6 +279,22 @@ same behaviour as well.
279
Strip whitespace from a buffer. The second parameter controls if
280
comments are considered contents to be removed or not.
281
282
+`strbuf_split_buf`::
283
+`strbuf_split_str`::
284
+`strbuf_split_max`::
285
+`strbuf_split`::
286
+
287
+ Split a string or strbuf into a list of strbufs at a specified
288
+ terminator character. The returned substrings include the
289
+ terminator characters. Some of these functions take a `max`
290
+ parameter, which, if positive, limits the output to that
291
+ number of substrings.
292
+
293
+`strbuf_list_free`::
294
+
295
+ Free a list of strbufs (for example, the return values of the
296
+ `strbuf_split()` functions).
297
+
298
`launch_editor`::
299
300
Launch the user preferred editor to edit a file and fill the buffer
strbuf.h
+33
@@ -44,23 +44,56 @@ extern void strbuf_rtrim(struct strbuf *);
44
extern void strbuf_ltrim(struct strbuf *);
45
extern int strbuf_cmp(const struct strbuf *, const struct strbuf *);
46
47
+/*
48
+ * Split str (of length slen) at the specified terminator character.
49
+ * Return a null-terminated array of pointers to strbuf objects
50
+ * holding the substrings. The substrings include the terminator,
51
+ * except for the last substring, which might be unterminated if the
52
+ * original string did not end with a terminator. If max is positive,
53
+ * then split the string into at most max substrings (with the last
54
+ * substring containing everything following the (max-1)th terminator
55
+ * character).
56
+ *
57
+ * For lighter-weight alternatives, see string_list_split() and
58
+ * string_list_split_in_place().
59
+ */
60
extern struct strbuf **strbuf_split_buf(const char *, size_t,
61
int terminator, int max);
62
+
63
+/*
64
+ * Split a NUL-terminated string at the specified terminator
65
+ * character. See strbuf_split_buf() for more information.
66
+ */
67
static inline struct strbuf **strbuf_split_str(const char *str,
68
int terminator, int max)
69
{
70
return strbuf_split_buf(str, strlen(str), terminator, max);
71
}
72
+
73
+/*
74
+ * Split a strbuf at the specified terminator character. See
75
+ * strbuf_split_buf() for more information.
76
+ */
77
static inline struct strbuf **strbuf_split_max(const struct strbuf *sb,
78
int terminator, int max)
79
{
80
return strbuf_split_buf(sb->buf, sb->len, terminator, max);
81
}
82
+
83
+/*
84
+ * Split a strbuf at the specified terminator character. See
85
+ * strbuf_split_buf() for more information.
86
+ */
87
static inline struct strbuf **strbuf_split(const struct strbuf *sb,
88
int terminator)
89
{
90
return strbuf_split_max(sb, terminator, 0);
91
}
92
+
93
+/*
94
+ * Free a NULL-terminated list of strbufs (for example, the return
95
+ * values of the strbuf_split*() functions).
96
+ */
97
extern void strbuf_list_free(struct strbuf **);
98
99
/*----- add data in your buffer -----*/