bstr: add missing function docs

Kacper Michajłow committed 2 years ago

Commit 216abbc1 parent 3fd6c312 files · +43 −6Browse files

Unified · Split

2 files

misc/bstr.c +0 −6
misc/bstr.h +43 −0

@@ -361,11 +361,6 @@ static void resize_append(void talloc_ctx, bstr s, size_t append_min) · 360 unmodified lines
361	361	}
362	362	}
363	363
364		−// Append the string, so that s = s + append. s->start is expected to be
365		−// a talloc allocation (which can be realloced) or NULL.
366		−// This function will always implicitly append a \0 after the new string for
367		−// convenience.
368		−// talloc_ctx will be used as parent context, if s->start is NULL.
369	364	void bstr_xappend(void talloc_ctx, bstr s, bstr append)
370	365	{
371	366	if (!append.len)
@@ -385,7 +380,6 @@ int bstr_xappend_asprintf(void talloc_ctx, bstr s, const char *fmt, ...) · 13 unmodified lines
385	380	return ret;
386	381	}
387	382
388		−// Exactly as bstr_xappend(), but with a formatted string.
389	383	int bstr_xappend_vasprintf(void talloc_ctx, bstr s, const char *fmt,
390	384	va_list ap)
391	385	{

misc/bstr.h+43−0

@@ -135,9 +135,52 @@ static inline struct bstr bstr_getline(struct bstr str, struct bstr *rest) · 134 unmodified lines
135	135	// and will remove the trailing \n or \r\n sequence.
136	136	struct bstr bstr_strip_linebreaks(struct bstr str);
137	137
	138	+/**
	139	+ * @brief Append a string to the existing bstr.
	140	+ *
	141	+ * This function appends the content of the `append` bstr to the `s` bstr.
	142	+ * `s->start` is expected to be a talloc allocation (which can be resized) or NULL.
	143	+ * A null terminator ('\0') is always appended for convenience. If `s->start`
	144	+ * is NULL, the `talloc_ctx` will be used as the parent context to allocate
	145	+ * memory.
	146	+ *
	147	+ * @param talloc_ctx The parent talloc context.
	148	+ * @param s The destination bstr to which the `append` string is appended.
	149	+ * @param append The string to append to `s`.
	150	+ */
138	151	void bstr_xappend(void talloc_ctx, bstr s, bstr append);
	152	+
	153	+/**
	154	+ * @brief Append a formatted string to the existing bstr.
	155	+ *
	156	+ * This function works like bstr_xappend() but appends a formatted string using
	157	+ * a format string and additional arguments. The formatted string is created
	158	+ * using vsnprintf. The function takes care of resizing the destination
	159	+ * buffer if necessary.
	160	+ *
	161	+ * @param talloc_ctx The parent talloc context.
	162	+ * @param s The destination bstr to which the formatted string is appended.
	163	+ * @param fmt The format string (same as in vsnprintf).
	164	+ * @param ... Additional arguments for the format string.
	165	+ * @return The number of characters added (excluding the null terminator)
	166	+ * or a negative value on error.
	167	+ */
139	168	int bstr_xappend_asprintf(void talloc_ctx, bstr s, const char *fmt, ...)
140	169	PRINTF_ATTRIBUTE(3, 4);
	170	+
	171	+/**
	172	+ * @brief Append a formatted string to the existing bstr using a va_list.
	173	+ *
	174	+ * This function is identical to bstr_xappend_asprintf() but takes a `va_list`
	175	+ * instead of a variable number of arguments.
	176	+ *
	177	+ * @param talloc_ctx The parent talloc context.
	178	+ * @param s The destination bstr to which the formatted string is appended.
	179	+ * @param fmt The format string (same as in printf).
	180	+ * @param ap The `va_list` containing the arguments for the format string.
	181	+ * @return The number of characters added (excluding the null terminator)
	182	+ * or a negative value on error.
	183	+ */
141	184	int bstr_xappend_vasprintf(void talloc_ctx, bstr s, const char *fmt, va_list va)
142	185	PRINTF_ATTRIBUTE(3, 0);
143	186

bstr: add missing function docs

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code