Adding upstream version 1:2.3.21+dfsg1.upstream/1%2.3.21+dfsg1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 70 insertions, 0 deletions

diff --git a/doc/wiki/Design.Strings.txt b/doc/wiki/Design.Strings.txt
new file mode 100644
index 0000000..72ca055
--- /dev/null
+++ b/doc/wiki/Design.Strings.txt
@@ -0,0 +1,70 @@
+Dynamic Strings
+===============
+
+'lib/str.h' describes Dovecot's dynamically growing strings. Strings are
+actually only a simple wrapper on top of <buffers> [Design.Buffers.txt]. Even
+the 'string_t' type is only a typedef of 'buffer_t', so it's possible to use
+'buffer_*()' functions with strings (although it's ugly so it should be
+avoided). The decision of whether to use a string_t or a buffer_t is mainly for
+human readability: if the buffer's contents are (ASCII/UTF8) text use string_t,
+otherwise for binary data use buffer_t.
+
+Once you're done modifying a string with 'str_*()' functions, you can get it
+out as a NUL-terminated string with 'str_c()' or 'str_c_modifiable()'. These
+pointers shouldn't be accessed after modifying the string again, they could
+have moved elsewhere in memory and they're no longer guaranteed to be
+NUL-terminated.
+
+Example:
+
+---%<-------------------------------------------------------------------------
+T_BEGIN {
+  string_t *str = t_str_new(64);
+
+  str_append(str, "hello world");
+  str_printfa(str, "\nand %u", str_len(str));
+
+  printf("%s\n", str_c(str));
+} T_END;
+---%<-------------------------------------------------------------------------
+
+String Handling Functions
+=========================
+
+'lib/strfuncs.h' contains a lot of functions intended to make string handling
+easier. They use C's NUL-terminated strings instead of Dovecot's dynamic
+strings.
+
+ * '[pt]_strdup_printf()' and '[pt]_strconcat()' are the most commonly used
+   functions.'*_strconcat' is slightly faster than '*_strdup_printf()', so use
+   it if you simply need to concatenate strings.
+ * Various functions for doing a 'strdup()' from wanted input.
+ * 'i_snprintf()' is a wrapper to 'snprintf()' that makes it easier to check if
+   result was truncated. It also adds few other safety checks. This should be
+   avoided in general, except in situations where you just don't want to use
+   data stack and there's no way for the result to get truncated.
+ * 'i_strocpy()' is similar to 'strlcpy()', but makes it easier to check if
+   result was truncated. This has the same problems as 'i_snprintf()'.
+ * Functions for uppercasing and lowercasing strings.
+ * Functions you can pass to 'bsearch()' and 'qsort()' for handling string
+   arrays.
+ * '[pt]_strsplit()' is an easy way to split a string into an array of strings
+   from given separator.
+    * 't_strarray_join()' reverses this.
+    * There are also some other functions to handle array of strings, like
+      getting its length or finding a given string.
+ * 'dec2str()' can be used to convert a number to a string. This can be useful
+   if you don't know the correct type and don't want to add casting (that could
+   potentially truncate the string). For example:'print("pid = %s\n",
+   dec2str(getpid()));'
+
+String Escaping
+===============
+
+'lib/strescape.h' contains functions to escape and unescape <">. <'> and <\>
+characters in strings using<\> character.\
+
+Dovecot's internal protocols are often line-based with TAB as the field
+separator. This file also contains functions to escape and unescape such data.
+
+(This file was created from the wiki on 2019-06-19 12:42)