Well, for a change, a vaguely usefull blog post ;) - I was sitting down looking at the DBDO code, that I got ivan to look at a few months ago. Being a gtk guy, he had copied the gstring api into DBDO, which from my recollection of the PHP internals is pretty similar to smart_str. However, there is no documentation for smart_str, other than the source. So here is a first go at it....
** feel free to make comments / correction notes.
SMART STRING API
from:
#include "ext/standard/php_smart_str.h"
The Struct:
typedef struct {
char *c; // data goes here..
size_t len; // the current length
size_t a; // the allocated size
} smart_str;EXAMPLE:
smart_str *sstr;
sstr = emalloc(sizeof(smart_str));
smart_str_sets(sstr, strdup("")); // start it clean.
.....
smart_str_free(sstr);
smart_str sstr = {0};
smart_str_alloc(&sstr, 100);
smart_str_sets(&sstr, strdup("This is a string"));
smart_str_free(&sstr); If you are setting up a pointer to the smart_str, it's probably best to use the _sets method, to fix the memory
Creating Memory:
void smart_str_alloc(smart_str *str, int len, int is_persistant);
EXAMPLE:
smart_str *sstr;
sstr = emalloc(sizeof(smart_str));
smart_str_alloc(sstr, 100);
Note: This only allocates memory for the string inside the smart_str, if you are using a pointer to the smart_str you must still emalloc that.
Initialize:
void smart_str_sets(smart_str *dest, char *src);
EXAMPLE:
smart_str *sstr;
sstr = emalloc(sizeof(smart_str));
smart_str_sets(sstr, strdup("This is a string"));
Note: this does not copy the string (so freeing the string after using this will likely resulting in a double free error
This is usefull when working with a pointer to the smart_str, where you can not initialize it as empty.
Closing a String
void smart_str_0(smart_str *str);
EXAMPLE:
smart_str *sstr;
sstr = emalloc(sizeof(smart_str));
smart_str_appends(sstr, "Hello World");
smart_str_0(sstr);
printf("the string is %s", sstr->c);
Note: If you need to pass the string to a function that accepts \0 deliminated strings, you should use this function.
Add a Character to a string
smart_str_appendc(smart_str *dest, char c)
EXAMPLE:
smart_str *sstr;
char c = "C";
sstr = emalloc(sizeof(smart_str));
smart_str_appendc(sstr, c);
Notes: do we need to pre-allocate the string in any manner?
Add a string
smart_str_append(smart_str *dest, smart_str *add);
smart_str_appends(smart_str *dest, char *add);
smart_str_appendl(smart_str *dest, char *add, int n);
EXAMPLE:
smart_str sstr1 = {0};
smart_str sstr2 = {0};
smart_str sstr3 = {0};
smart_str_appends(&sstr1, "the cat");
smart_str_appendl(&sstr1, " the dog", 3);
smart_str_appends(&sstr2, "the cat");
smart_str_appendl(&sstr2, " the dog", 3);
smart_str_append(&sstr3, &str1);
smart_str_append(&sstr3, &str2);Notes:
appendl: adds only the first n characters to the smart string.
appends: adds the new string to the smart string (assumes \0 terminated.
Adding Numbers to a smart string:
smart_str_append_long(smart_str *dest, long val);
smart_str_append_unsigned(smart_str *dest, unsigned long val);
smart_str_append_off_t(smart_str *dest, off_t val);
EXAMPLE:
smart_str_append_long(sstr, 120);
Free the String:
smart_str_free(smart_str *str);
Example:
smart_str *sstr;
sstr = emalloc(sizeof(smart_str));
smart_str_sets(*sstr1, strdup("the cat"));
... do something ...
smart_str_free(sstr);
See Also:
autoallocating sprintf. (with \0 terminated added)
snprintf(char *buffer, int max_size, char *format, .....);
