Synopsis
char* kit_strdup (const char *s);
char* kit_strndup (const char *s,
size_t n);
char* kit_strdup_printf (const char *format,
...);
char* kit_strdup_vprintf (const char *format,
va_list args);
char* kit_str_append (char *s,
const char *s2);
kit_bool_t kit_str_has_prefix (const char *s,
const char *prefix);
kit_bool_t kit_str_has_suffix (const char *s,
const char *suffix);
char** kit_strsplit (const char *s,
char delim,
size_t *num_tokens);
void kit_strfreev (char **str_array);
size_t kit_strv_length (char **str_array);
kit_bool_t (*KitStringEntryParseFunc) (const char *key,
const char *value,
void *user_data);
kit_bool_t kit_string_entry_parse (const char *entry,
KitStringEntryParseFunc func,
void *user_data);
kit_bool_t kit_string_percent_decode (char *s);
size_t kit_string_percent_encode (char *buf,
size_t buf_size,
const char *s);
size_t kit_string_entry_create (char *buf,
size_t buf_size,
...);
size_t kit_string_entry_createv (char *buf,
size_t buf_size,
const char *kv_pairs[]);
KitString;
KitString* kit_string_new (const char *init,
size_t len);
char* kit_string_free (KitString *s,
kit_bool_t free_segment,
size_t *out_segment_size);
kit_bool_t kit_string_ensure_size (KitString *s,
size_t new_size);
kit_bool_t kit_string_append_c (KitString *s,
char c);
kit_bool_t kit_string_append (KitString *s,
const char *str);
Details
kit_strdup ()
char* kit_strdup (const char *s);
Duplicate a string. Similar to strdup(3).
s : | string |
Returns : | Allocated memory or NULL on OOM. Free with kit_free(). |
kit_strndup ()
char* kit_strndup (const char *s,
size_t n);
Duplicate a string but copy at most n characters. If s is longer than n, only n characters are copied, and a terminating null byte is added. Similar to strndup(3).
s : | string |
n : | size |
Returns : | Allocated memory or NULL on OOM. Free with kit_free(). |
kit_strdup_printf ()
char* kit_strdup_printf (const char *format,
...);
Similar to the standard C sprintf(3) function but safer, since it calculates the maximum space required and allocates memory to hold the result. The returned string should be freed when no longer needed.
format : | sprintf(3) format string |
... : | the parameters to insert into the format string. |
Returns : | A newly allocated string or NULL on OOM. Free with kit_free(). |
kit_strdup_vprintf ()
char* kit_strdup_vprintf (const char *format,
va_list args);
Similar to the standard C vsprintf(3) function but safer, since it calculates the maximum space required and allocates memory to hold the result. The returned string should be freed when no longer needed.
format : | printf(3) format string |
args : | list of parameters to insert |
Returns : | A newly allocated string or NULL on OOM. Free with kit_free(). |
kit_str_append ()
char* kit_str_append (char *s,
const char *s2);
Append a string to an existing string.
s : | either NULL or a string previously allocated on the heap |
s2 : | string to append |
Returns : | NULL on OOM or the new string; possibly at the same location as s. |
kit_str_has_prefix ()
kit_bool_t kit_str_has_prefix (const char *s,
const char *prefix);
Determines if a string has a given prefix.
s : | string to check |
prefix : | prefix to check for |
Returns : | TRUE only if s starts with prefix |
kit_str_has_suffix ()
kit_bool_t kit_str_has_suffix (const char *s,
const char *suffix);
Determines if a string has a given suffix.
s : | string to check |
suffix : | suffix to check for |
Returns : | TRUE only if s ends with suffix |
kit_strsplit ()
char** kit_strsplit (const char *s,
char delim,
size_t *num_tokens);
Split a given string into components given a delimiter.
s : | string to split |
delim : | delimiter used for splitting |
num_tokens : | return location for number of elements or NULL |
Returns : | A NULL terminated array of strings. Free with kit_strfreev(). Returns NULL on OOM. |
kit_strfreev ()
void kit_strfreev (char **str_array);
Free a NULL terminated string array.
kit_strv_length ()
size_t kit_strv_length (char **str_array);
Compute number of elements in a NULL terminated string array.
str_array : | string array |
Returns : | Number of elements not including the terminating NULL |
KitStringEntryParseFunc ()
kit_bool_t (*KitStringEntryParseFunc) (const char *key,
const char *value,
void *user_data);
Type of callback function to use in kit_string_entry_parse()
key : | key of one of the entries |
value : | value of one of the entries |
user_data : | user data passed to kit_string_entry_parse() |
Returns : | If FALSE is returned the parsing will be aborted and kit_string_entry_parse() will return FALSE. |
kit_string_entry_parse ()
kit_bool_t kit_string_entry_parse (const char *entry,
KitStringEntryParseFunc func,
void *user_data);
Parse a line of the form key1=val1:key2=val2:key3=val3.
The given entry is said not to be wellformed if a) it doesn't follow this structure (for example key1=val1:key2:key3=val3 is not well-formed because it's missing the '=' character) or the extracted key and value strings are not properly percent encoded.
Both the key and value values are run through the kit_string_percent_decode() function prior to being passed to func. Normally this function is used to decode strings produced with kit_string_entry_create().
entry : | line to parse |
func : | callback function |
user_data : | user data to pass to func |
Returns : | TRUE if the line is wellformed and the callback didn't short-circuit the iteration. Returns FALSE on OOM (and errno will be set to ENOMEM) or if entry is not wellformed (and errno will be set to EINVAL). |
kit_string_percent_decode ()
kit_bool_t kit_string_percent_decode (char *s);
Percent-decodes a string in place. See kit_string_percent_encode() for details on the encoding format.
s : | string to modify in place |
Returns : | FALSE if string is not properly encoded (and errno will be set to EINVAL) |
kit_string_percent_encode ()
size_t kit_string_percent_encode (char *buf,
size_t buf_size,
const char *s);
Percent encodes a string; each occurence of an ASCII characters in the set " !*'();:@&=+$,/?%#[]\n\r\t" will be replaced by a three character sequence started by the percent sign "%" and then the hexidecimal representation of the ASCII character in question.
buf : | return location for output |
buf_size : | size of buffer |
s : | string to encode |
Returns : | This function do not write more than buf_size bytes (including the trailing zero). If the output was truncated due to this limit then the return value is the number of characters (not including the trailing zero) which would have been written to the final string if enough space had been available. Thus, a return value of buf_size or more means that the output was truncated. |
kit_string_entry_create ()
size_t kit_string_entry_create (char *buf,
size_t buf_size,
...);
See kit_string_entry_create().
buf : | return location for output |
buf_size : | size of buffer |
... : | NULL terminated array of key/value pairs. |
Returns : | See kit_string_entry_create(). Up to 64 pairs can be passed; if there are more pairs, this function will return zero and errno will be set to EOVERFLOW. |
kit_string_entry_createv ()
size_t kit_string_entry_createv (char *buf,
size_t buf_size,
const char *kv_pairs[]);
Takes an array of key/value pairs and generates a string "k1=v1:k2=v2:...:k_n=v_n" where k_i and v_i are percent encoded representations of the given key/value pairs.
The string can later be parsed with kit_string_entry_parse() to get the exact same list of key/value pairs back.
buf : | return location for output |
buf_size : | size of buffer |
kv_pairs : | NULL terminated array of key/value pairs. |
Returns : | This function do not write more than buf_size bytes (including the trailing zero). If the output was truncated due to this limit then the return value is the number of characters (not including the trailing zero) which would have been written to the final string if enough space had been available. Thus, a return value of buf_size or more means that the output was truncated. If an uneven number of strings are given, this function will return zero and errno will be set to EINVAL. |
KitString
typedef struct _KitString KitString;
String buffer that grows automatically as text is added.
kit_string_new ()
KitString* kit_string_new (const char *init,
size_t len);
Initialize a new KitString object.
init : | String to initialize with or NULL |
len : | Initial size of buffer; pass zero to use the default size |
Returns : | The new object or NULL on OOM |
kit_string_free ()
char* kit_string_free (KitString *s,
kit_bool_t free_segment,
size_t *out_segment_size);
Free resources used by a KitString object
s : | the KitString object |
free_segment : | whether to free the string data itself |
out_segment_size : | return location for size of string or NULL |
Returns : | If free_segment is TRUE, returns the segment (will always be zero terminated), must be freed with kit_free(), otherwise NULL |
kit_string_ensure_size ()
kit_bool_t kit_string_ensure_size (KitString *s,
size_t new_size);
Ensure that the given KitString object can hold at least new_size characters.
s : | String object |
new_size : | The size to check for. |
Returns : | TRUE if the given KitString object can hold at least new_size characters. FALSE if OOM. |
kit_string_append_c ()
kit_bool_t kit_string_append_c (KitString *s,
char c);
Append a character to a KitString object.
s : | the KitString object |
c : | character to append |
Returns : | TRUE unless OOM |
kit_string_append ()
kit_bool_t kit_string_append (KitString *s,
const char *str);
Append a string to a KitString object.
s : | the KitString object |
str : | string to append |
Returns : | TRUE unless OOM |
