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().