String


Overview

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 Documentation

#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

Parameters:
s an u_string_t object
buf the NUL-terminated string that will be appended to s
Return values:
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

Parameters:
s an u_string_t object
buf the NUL-terminated string that will be appended to s
len length of buf
Return values:
0 on success
~0 on failure

Definition at line 44 of file str.h.


Function Documentation

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

Parameters:
s an u_string_t object
buf NUL-terminated string that will be appended to s
len length of buf
Return values:
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

Parameters:
s an u_string_t object
fmt printf-style format
... variable list of arguments that feed fmt
Return values:
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.

Parameters:
s an u_string_t object
Returns:
the string value or 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

Parameters:
s an u_string_t object
Return values:
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...

Parameters:
dst destination u_string_t object
src source u_string_t object
Return values:
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

Parameters:
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
Return values:
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.

Parameters:
s an u_string_t object
Return values:
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

Parameters:
s an u_string_t object
clear 1 to set, 0 to append
fmt printf-style format
... variable list of arguments that feed fmt
Return values:
0 on success
~0 on failure

Definition at line 355 of file str.c.

int u_string_free ( u_string_t s  ) 

Release all resources allocated to the supplied u_string_t object s

Parameters:
s the u_string_t object that will be destroyed
Return values:
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

Parameters:
s an u_string_t object
Returns:
the string length

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.

Parameters:
s an u_string_t object
size the requested new size
Return values:
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

Parameters:
s an u_string_t object
buf the value that will be assigned to s
len length of buf
Return values:
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

Parameters:
s an u_string_t object
len new (shorter) length of s
Return values:
0 on success
~0 on failure

Definition at line 130 of file str.c.

int u_string_sprintf ( u_string_t s,
const char *  fmt,
  ... 
)

Set an u_string_t object s from the printf-style arguments fmt

Parameters:
s an u_string_t object
fmt printf-style format
... variable list of arguments that feed fmt
Return values:
0 on success
~0 on failure

Definition at line 420 of file str.c.

int u_string_trim ( u_string_t s  ) 

Remove leading and trailing blanks from the given string

Parameters:
s an u_string_t object
Return values:
0 on success
~0 on failure

Definition at line 106 of file str.c.

References u_trim().

Referenced by u_config_set_value().


←Products
© 2005-2012 - KoanLogic S.r.l. - All rights reserved