Problem - Kevin Tafuro

safestr_release( ) or safestr_free( ) is called to decrement the string’s reference
count.
People are sometimes confused about when actually to use SAFESTR_TEMP( ), as well
as how to use it properly. Use SAFESTR_TEMP( ) when you need to pass a constant
string as an argument to a function that is expecting a safestr_t. A perfect example
of such a case would be safestr_sprintf( ), which has the following signature:
int safestr_sprintf(safestr_t *output, safestr_t *fmt, ...);
The string that specifies the format must be a safe string, but because you should
always use constant strings for the format specification (see Recipe 3.2), you should
use SAFESTR_TEMP( ). The alternative is to use SAFESTR_CREATE( ) to create the string
before calling safestr_sprintf( ), and free it immediately afterward with safestr_
free( ).
int i = 42;
safestr_t fmt, output;
output = SAFESTR_ALLOC(1);
/* Instead of doing this: */
fmt = SAFESTR_CREATE("The value of i is %d.\n");
safestr_sprintf(&output, fmt, i);
safestr_free(fmt);
/* You can do this: */
safestr_sprintf(&output, SAFESTR_TEMP("The value of i is %d.\n"), i);
When using temporary strings, remember that the temporary string will be destroyed
automatically after a call to any SafeStr API function except safestr_reference( ),
which will increment the string’s reference count. If a temporary string’s reference
count is incremented, the string will then survive any number of API calls until its
reference count is decremented to the extent that it will be destroyed. The API functions
safestr_release( ) and safestr_free( ) may be used interchangeably to decrement
a string’s reference count.
For example, if you are writing a function that accepts a safestr_t as an argument
(which may or may not be passed as a temporary string) and you will be performing
multiple operations on the string, you should increment the string’s reference count
before operating on it, and decrement it again when you are finished. This will
ensure that the string is not prematurely destroyed if a temporary string is passed in
to the function.
void some_function(safestr_t *base, safestr_t extra) {
safestr_reference(extra);
if (safestr_length(*base) + safestr_length(extra) < 17)
safestr_append(base, extra);
safestr_release(extra);
}
This is the Title of the Book, eMatter Edition
Copyright © 2007 O’Reilly & Associates, Inc. All rights reserved.
Using the SafeStr Library | 87