finish cleanup

3rd/str/snippets.md

@@ -0,0 +1,63 @@
+### Code Examples
+
+Here I provide various (hopefully, useful) functions and code examples that are not included into the
+main library. Some examples use non-POSIX and/or compiler-specific features that may or may
+not be suitable for a particular project. Also, these snippets were tested while being developed,
+but they may break in the future as the library evolves.
+
+##### `void str_sprintf(str* const dest, const char* fmt, ...)`
+
+Probably the simplest implementation utilising non-POSIX `asprintf(3)` function:
+```C
+#define _GNU_SOURCE
+
+#include "str.h"
+
+#define str_sprintf(dest, fmt, ...)	\
+({	\
+    char* ___p;	\
+    const int ___n = asprintf(&___p, (fmt),  ##__VA_ARGS__);	\
+    str_assign((dest), str_acquire_chars(___p, ___n));	\
+})
+```
+This code does not check for errors. A more standard-conforming implementation would probably go
+through `open_memstream(3)` function.
+
+##### `int str_from_int(str* const dest, const int val)`
+```C
+int str_from_int(str* const dest, const int val)
+{
+    char buff[256];	// of some "big enough" size
+
+    return str_cpy(dest, str_ref_chars(buff, snprintf(buff, sizeof(buff), "%d", val)));
+}
+```
+
+This code can also be used as a template for other functions converting from `double`, `struct tm`, etc.
+
+##### `int str_append(str* const dest, ...)`
+```C
+#define str_append(dest, ...)	\
+    ({ str* const ___p = (dest); str_cat(___p, *___p, ##__VA_ARGS__); })
+```
+Test case and usage example:
+```C
+    str s = str_lit("zzz");
+
+    assert(str_append(&s, str_lit(" "), str_lit("aaa")) == 0);
+    assert(str_eq(s, str_lit("zzz aaa")));
+
+    str_free(s);
+```
+
+##### Using `str` objects with `printf` family of functions
+
+Since a string object is not guaranteed to refer to a null-terminated string it should be formatted
+with explicitly specified length, for example:
+```C
+	str s = ...
+
+	printf("%.*s\n", (int)str_len(s), str_ptr(s));
+```
+_Note:_ The maximum length of the string is limited to `INT_MAX` bytes, and formatting will stop
+at the first null byte within the string.