Edit File: Design.Strings.txt
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 2018-02-28 04:42)