The String module provides a string type and the set of associated primitives that can be used instead of (or in combination with) the classic NUL-terminated C strings. The convenience in using u_string_t objects in your code is that you can forget the buffer length constraints (with their implied checks) and string explicit termination that come with C char arrays, since any needed buffer resizing and consistency is handled by the String machinery transparently.
Anyway, a bunch of C code lines is better than any further word:
u_string_t *s = NULL; // create and initialize a new string object 's' dbg_err_if (u_string_create("pi", strlen("pi"), &s)); // append the value of pi to 's' dbg_err_if (u_string_aprintf(s, " = %.30f", M_PI)); // print it out (should give: "pi = 3.141592653589793115997963468544") u_con("%s", u_string_c(s)); // clear the string dbg_err_if (u_string_clear(s)); // go again with other stuff dbg_err_if (u_string_set(s, "2^(1/2)", strlen("2^(1/2)"))); // append the value of 2^1/2 to 's' dbg_err_if (u_string_aprintf(s, " = %.30f", M_SQRT2)); // print it out (should give: "2^(1/2) = 1.414213562373095145474621858739") u_con("%s", u_string_c(s)); // when your done, dispose it u_string_free(s);
Defines | |
#define | u_string_ncat(s, buf, len) u_string_append(s, buf, len) |
Append at most len characters of a NUL-terminated string to a string object. | |
#define | u_string_cat(s, buf) u_string_append(s, buf, strlen(buf)) |
Append a NUL-terminated string to a string object. | |
Typedefs | |
typedef struct u_string_s | u_string_t |
The base string type. | |
Functions | |
const char * | u_string_c (u_string_t *s) |
Return the string value. | |
int | u_string_append (u_string_t *s, const char *buf, size_t len) |
Append a NUL-terminated string to a string object. | |
int | u_string_aprintf (u_string_t *s, const char *fmt,...) |
Append to the string the supplied printf-style arguments. | |
int | u_string_clear (u_string_t *s) |
Clear a string. | |
int | u_string_copy (u_string_t *dst, u_string_t *src) |
Copy the value of a string to another. | |
int | u_string_create (const char *buf, size_t len, u_string_t **ps) |
Create a new string. | |
int | u_string_do_printf (u_string_t *s, int clear, const char *fmt,...) |
Set or append a printf-style formatted string to the given string. | |
int | u_string_free (u_string_t *s) |
Free a string. | |
int | u_string_reserve (u_string_t *s, size_t size) |
Enlarge the underlying memory block of the given buffer. | |
int | u_string_set (u_string_t *s, const char *buf, size_t len) |
Set the value of a string. | |
int | u_string_set_length (u_string_t *s, size_t len) |
Set the length of a string (shortening it). | |
int | u_string_sprintf (u_string_t *s, const char *fmt,...) |
Set the string from printf-style arguments. | |
int | u_string_trim (u_string_t *s) |
Remove leading and trailing blanks. | |
size_t | u_string_len (u_string_t *s) |
Return the string length. | |
char * | u_string_detach_cstr (u_string_t *s) |
Detach the NUL-terminated C string associated to the supplied u_string_t object. |
#define u_string_cat | ( | s, | |||
buf | ) | u_string_append(s, buf, strlen(buf)) |
Append the NUL-terminated string buf
to the given u_string_t object s
s | an u_string_t object | |
buf | the NUL-terminated string that will be appended to s |
0 | on success | |
~0 | on failure |
Definition at line 58 of file str.h.
Referenced by u_hmap_dbg(), and u_hmap_pcy_dbg().
#define u_string_ncat | ( | s, | |||
buf, | |||||
len | ) | u_string_append(s, buf, len) |
Append at most len
chars from the NUL-terminated string buf
to the given u_string_t object s
s | an u_string_t object | |
buf | the NUL-terminated string that will be appended to s | |
len | length of buf |
0 | on success | |
~0 | on failure |
int u_string_append | ( | u_string_t * | s, | |
const char * | buf, | |||
size_t | len | |||
) |
Append the NUL-terminated string buf
to the u_string_t object s
s | an u_string_t object | |
buf | NUL-terminated string that will be appended to s | |
len | length of buf |
0 | on success | |
~0 | on failure |
Definition at line 379 of file str.c.
References u_string_reserve().
Referenced by u_config_set_value(), u_hmap_dbg(), u_string_copy(), u_string_create(), and u_string_set().
int u_string_aprintf | ( | u_string_t * | s, | |
const char * | fmt, | |||
... | ||||
) |
Append the format string fmt
to the supplied u_string_t object s
s | an u_string_t object | |
fmt | printf-style format | |
... | variable list of arguments that feed fmt |
0 | on success | |
~0 | on failure |
Definition at line 444 of file str.c.
Referenced by u_hmap_dbg(), and u_hmap_pcy_dbg().
const char * u_string_c | ( | u_string_t * | s | ) | [inline] |
Return the NUL-terminated C string handled by the given u_string_t object s
. Such const value cannot be modified, realloc'd nor free'd.
s | an u_string_t object |
NULL
if the string is empty Definition at line 172 of file str.c.
Referenced by u_config_save_to_buf(), u_config_set_value(), u_hmap_dbg(), and u_hmap_pcy_dbg().
int u_string_clear | ( | u_string_t * | s | ) |
Erase the content of the given u_string_t object s
s | an u_string_t object |
0 | on success | |
~0 | on failure |
Definition at line 211 of file str.c.
Referenced by u_hmap_dbg(), u_hmap_pcy_dbg(), u_string_copy(), and u_string_set().
int u_string_copy | ( | u_string_t * | dst, | |
u_string_t * | src | |||
) | [inline] |
Copy src
string to dst
string. Both src
and dst
must be already TODO...
dst | destination u_string_t object | |
src | source u_string_t object |
0 | on success | |
~0 | on failure |
Definition at line 191 of file str.c.
References u_string_append(), and u_string_clear().
int u_string_create | ( | const char * | buf, | |
size_t | len, | |||
u_string_t ** | ps | |||
) |
Create a new u_string_t object and save its reference to *ps
. If buf
is not NULL
(and len > 0
), the string will be initialized with the content of buf
buf | initial string value, or NULL | |
len | length of buf | |
ps | result argument that will get the newly created u_string_t object on success |
0 | on success | |
~0 | on failure |
Definition at line 240 of file str.c.
References u_malloc(), u_string_append(), and u_string_free().
Referenced by u_config_save_to_buf(), u_config_set_value(), u_hmap_dbg(), u_hmap_pcy_dbg(), and u_json_encode().
char * u_string_detach_cstr | ( | u_string_t * | s | ) |
Detach the NUL-terminated C string embedded into the supplied u_string_t object. The original string object is then free'd and can't be accessed anymore.
s | an u_string_t object |
a | NUL-terminated C string |
Definition at line 83 of file str.c.
References u_free().
Referenced by u_json_encode().
int u_string_do_printf | ( | u_string_t * | s, | |
int | clear, | |||
const char * | fmt, | |||
... | ||||
) |
Set or append (depending on clear
value) the printf-style format string fmt
to the given u_string_t object s
s | an u_string_t object | |
clear | 1 to set, 0 to append | |
fmt | printf-style format | |
... | variable list of arguments that feed fmt |
0 | on success | |
~0 | on failure |
int u_string_free | ( | u_string_t * | s | ) |
Release all resources allocated to the supplied u_string_t object s
s | the u_string_t object that will be destroyed |
0 | always |
Definition at line 274 of file str.c.
References u_free().
Referenced by u_config_save_to_buf(), u_config_set_value(), u_hmap_dbg(), u_hmap_pcy_dbg(), u_json_encode(), and u_string_create().
size_t u_string_len | ( | u_string_t * | s | ) | [inline] |
Return the length of the given string s
s | an u_string_t object |
Definition at line 155 of file str.c.
Referenced by u_config_save_to_buf(), and u_hmap_dbg().
int u_string_reserve | ( | u_string_t * | s, | |
size_t | size | |||
) |
Enlarge the buffer data block of the supplied u_string_t object s
to (at least) size
bytes.
s | an u_string_t object | |
size | the requested new size |
0 | on success | |
~0 | on failure |
Definition at line 319 of file str.c.
References u_realloc().
Referenced by u_string_append().
int u_string_set | ( | u_string_t * | s, | |
const char * | buf, | |||
size_t | len | |||
) |
Set the value of the supplied s
to buf
s | an u_string_t object | |
buf | the value that will be assigned to s | |
len | length of buf |
0 | on success | |
~0 | on failure |
Definition at line 298 of file str.c.
References u_string_append(), and u_string_clear().
Referenced by u_config_set_value().
int u_string_set_length | ( | u_string_t * | s, | |
size_t | len | |||
) |
Set the length of the supplied string s
to len
s | an u_string_t object | |
len | new (shorter) length of s |
0 | on success | |
~0 | on failure |
int u_string_sprintf | ( | u_string_t * | s, | |
const char * | fmt, | |||
... | ||||
) |
Set an u_string_t object s
from the printf-style arguments fmt
s | an u_string_t object | |
fmt | printf-style format | |
... | variable list of arguments that feed fmt |
0 | on success | |
~0 | on failure |
int u_string_trim | ( | u_string_t * | s | ) |
Remove leading and trailing blanks from the given string
s | an u_string_t object |
0 | on success | |
~0 | on failure |
Definition at line 106 of file str.c.
References u_trim().
Referenced by u_config_set_value().