This is a book about

16. === str_release_all

Lines 3 to 5 and 10 to 12 of Listing 6-16 show the outputs of STR_display() for an uninitialized Str and
for an Str with a 16-character C string. Notice that line 12 shows a length of 17 because it calculates it as the
difference between the size of the allocated block (i.e., 57) and the size of Str structures (i.e., 40). Therefore,
it includes the string-terminating NULL .

String Update
In this section I describe macros and functions that set characters in strings, copy strings, convert strings to
upper- or lowercase, and remove parts of strings.
You can set individual characters within a macro, without need for a function:
#define STR_set_char(str, k, c) { \
if((str)->s != NULL && strlen((str)->s) > k && k >= 0) (str)->s[k] = c; \
else STR_crash("STR_set_char: character outside a string"); \
}
Obviously, you dont need a macro at all. For example, to set character 38 of a string to 'k' , instead of
typing STR_set_char(str, 38, 'k') , you could simply type str->s[38] = 'k' . But what if the string is,
say, 30 characters long? Without the boundary checks built into the macro, you would be in trouble. As I
said concerning STR_char() , you might like to modify the macro so that it only performs the checks when
STR_DEBUG is set. Its entirely up to you!
But lets look at something more interesting.
CHAPTER 6 STRING UTILITIES
156
String Copy
With the expression string copy you might mean two different operations:
Create a new string that is identical to an existing one
Copy the content of a string to another existing string
But the first type of operation is a duplication, rather than a copy. The term copy seems only
appropriate when the destination string already exists. The problem with the second type of operation is that
the destination string might be shorter than the source string, in which case a full copy is impossible. You
could hybridize the two operations and allocate a new destination string but only if the existing one is too
short. The problem with that solution is that the new string would be at a different location in memory, and
that would cause any additional existing reference to the original destination string to become invalid.
The most reasonable solution seems to be a copy with truncation or padding when necessary.
Listing 6-17 shows five examples of how to copy strings.
Listing 6-17. test_update()String Copy
1. printf("\n-------------------------------------------copy_string\n");
2. str = STR_new("0123456789");
3.
4. size_t len = STR_copy_string(str, "Giulio", '$');
5. printf("--- %zu character%s copied: \"%s\"\n\n",
6. len, (len == 1) ? "" : "s", STR_string(str));
7.
8. len = STR_copy_string(str, "Giulio", '\0');
9. printf("--- %zu character%s copied: \"%s\"\n\n",
10. len, (len == 1) ? "" : "s", STR_string(str));
11.
12. len = STR_copy_string(str, "Giulio Zambon", '%');
13. printf("--- %zu character%s copied: \"%s\"\n\n",
14. len, (len == 1) ? "" : "s", STR_string(str));
15.
16. len = STR_copy_string(str, "", '+');
17. printf("--- %zu character%s copied: \"%s\"\n\n",
18. len, (len == 1) ? "" : "s", STR_string(str));
19.
20. len = STR_copy_string(str, NULL, '$');
21. printf("--- %zu character%s copied: \"%s\"\n\n",
22. len, (len == 1) ? "" : "s", STR_string(str));
The first parameter of STR_copy_string() points to the destination Str ; the second parameter is the
source string; and the third parameter is the character to be used for padding if necessary. The output of the
code in Listing 6-17 is shown in Listing 6-18 .
Listing 6-18. Output of test_update()String Copy
1. -------------------------------------------copy_string
2. === str_new: (nil) 0 "0123456789" '\0'-> 0x1105060
3. === str_copy_string: "Giulio" '$' -> 0x1105060
4. --- 6 characters copied: "Giulio$$$$"
5.