#include "glib.h"
#include "gprintf.h"
-#include "galias.h"
+/**
+ * SECTION: string_chunks
+ * @title: String Chunks
+ * @short_description: efficient storage of groups of strings
+ *
+ * String chunks are used to store groups of strings. Memory is
+ * allocated in blocks, and as strings are added to the #GStringChunk
+ * they are copied into the next free position in a block. When a block
+ * is full a new block is allocated.
+ *
+ * When storing a large number of strings, string chunks are more
+ * efficient than using g_strdup() since fewer calls to malloc() are
+ * needed, and less memory is wasted in memory allocation overheads.
+ *
+ * By adding strings with g_string_chunk_insert_const() it is also
+ * possible to remove duplicates.
+ *
+ * To create a new #GStringChunk use g_string_chunk_new().
+ *
+ * To add strings to a #GStringChunk use g_string_chunk_insert().
+ *
+ * To add strings to a #GStringChunk, but without duplicating strings
+ * which are already in the #GStringChunk, use
+ * g_string_chunk_insert_const().
+ *
+ * To free the entire #GStringChunk use g_string_chunk_free(). It is
+ * not possible to free individual strings.
+ **/
+
+/**
+ * GStringChunk:
+ *
+ * An opaque data structure representing String Chunks. It should only
+ * be accessed by using the following functions.
+ **/
struct _GStringChunk
{
GHashTable *const_table;
/**
* g_str_equal:
- * @v1: a key.
- * @v2: a key to compare with @v1.
- *
- * Compares two strings for byte-by-byte equality and returns %TRUE
- * if they are equal. It can be passed to g_hash_table_new() as the
+ * @v1: a key
+ * @v2: a key to compare with @v1
+ *
+ * Compares two strings for byte-by-byte equality and returns %TRUE
+ * if they are equal. It can be passed to g_hash_table_new() as the
* @key_equal_func parameter, when using strings as keys in a #GHashTable.
*
- * Returns: %TRUE if the two keys match.
+ * Note that this function is primarily meant as a hash table comparison
+ * function. For a general-purpose, %NULL-safe string comparison function,
+ * see g_strcmp0().
+ *
+ * Returns: %TRUE if the two keys match
*/
gboolean
g_str_equal (gconstpointer v1,
/**
* g_str_hash:
- * @v: a string key.
+ * @v: a string key
*
* Converts a string to a hash value.
- * It can be passed to g_hash_table_new() as the @hash_func parameter,
- * when using strings as keys in a #GHashTable.
+ * It can be passed to g_hash_table_new() as the @hash_func
+ * parameter, when using strings as keys in a #GHashTable.
*
- * Returns: a hash value corresponding to the key.
+ * Returns: a hash value corresponding to the key
*/
guint
g_str_hash (gconstpointer v)
* duplicates.
*
* Returns: a pointer to the copy of @string within
- * the #GStringChunk.
+ * the #GStringChunk
*/
gchar*
g_string_chunk_insert (GStringChunk *chunk,
/**
* g_string_chunk_insert_const:
- * @chunk: a #GStringChunk
+ * @chunk: a #GStringChunk
* @string: the string to add
- *
- * Adds a copy of @string to the #GStringChunk, unless
- * the same string has already been added to the #GStringChunk
- * with g_string_chunk_insert_const().
- *
- * This function is useful if you need to copy a large number
- * of strings but do not want to waste space storing duplicates.
- * But you must remember that there may be several pointers to
- * the same string, and so any changes made to the strings
+ *
+ * Adds a copy of @string to the #GStringChunk, unless the same
+ * string has already been added to the #GStringChunk with
+ * g_string_chunk_insert_const().
+ *
+ * This function is useful if you need to copy a large number
+ * of strings but do not want to waste space storing duplicates.
+ * But you must remember that there may be several pointers to
+ * the same string, and so any changes made to the strings
* should be done very carefully.
- *
- * Note that g_string_chunk_insert_const() will not return a
- * pointer to a string added with g_string_chunk_insert(), even
+ *
+ * Note that g_string_chunk_insert_const() will not return a
+ * pointer to a string added with g_string_chunk_insert(), even
* if they do match.
- *
- * Returns: a pointer to the new or existing copy of @string
+ *
+ * Returns: a pointer to the new or existing copy of @string
* within the #GStringChunk
*/
gchar*
* g_string_chunk_insert_len:
* @chunk: a #GStringChunk
* @string: bytes to insert
- * @len: number of bytes of @string to insert, or -1 to insert a
- * nul-terminated string.
- *
- * Adds a copy of the first @len bytes of @string to the #GStringChunk. The
- * copy is nul-terminated.
- *
+ * @len: number of bytes of @string to insert, or -1 to insert a
+ * nul-terminated string
+ *
+ * Adds a copy of the first @len bytes of @string to the #GStringChunk.
+ * The copy is nul-terminated.
+ *
* Since this function does not stop at nul bytes, it is the caller's
- * responsibility to ensure that @string has at least @len addressable bytes.
+ * responsibility to ensure that @string has at least @len addressable
+ * bytes.
+ *
+ * The characters in the returned string can be changed, if necessary,
+ * though you should not change anything after the end of the string.
*
- * The characters in the returned string can be changed, if necessary, though
- * you should not change anything after the end of the string.
- *
* Return value: a pointer to the copy of @string within the #GStringChunk
- *
+ *
* Since: 2.4
- **/
+ */
gchar*
g_string_chunk_insert_len (GStringChunk *chunk,
- const gchar *string,
+ const gchar *string,
gssize len)
{
gssize size;
size = strlen (string);
else
size = len;
-
+
if ((chunk->storage_next + size + 1) > chunk->this_size)
{
gsize new_size = nearest_power (chunk->default_size, size + 1);
*(pos + size) = '\0';
- strncpy (pos, string, size);
- if (len > 0)
- size = strlen (pos);
+ memcpy (pos, string, size);
chunk->storage_next += size + 1;
/**
* g_string_sized_new:
* @dfl_size: the default size of the space allocated to
- * hold the string.
+ * hold the string
*
* Creates a new #GString, with enough space for @dfl_size
* bytes. This is useful if you are going to add a lot of
* text to the string and don't want it to be reallocated
* too often.
*
- * Returns: the new #GString.
+ * Returns: the new #GString
*/
GString*
g_string_sized_new (gsize dfl_size)
/**
* g_string_new:
- * @init: the initial text to copy into the string.
+ * @init: the initial text to copy into the string
*
* Creates a new #GString, initialized with the given string.
*
- * Returns: the new #GString.
+ * Returns: the new #GString
*/
GString*
g_string_new (const gchar *init)
/**
* g_string_new_len:
- * @init: initial contents of string.
- * @len: length of @init to use.
+ * @init: initial contents of the string
+ * @len: length of @init to use
*
- * Creates a new #GString with @len bytes of the
- * @init buffer. Because a length is provided, @init
- * need not be nul-terminated, and can contain embedded
- * nul bytes.
+ * Creates a new #GString with @len bytes of the @init buffer.
+ * Because a length is provided, @init need not be nul-terminated,
+ * and can contain embedded nul bytes.
*
* Since this function does not stop at nul bytes, it is the caller's
- * responsibility to ensure that @init has at least @len addressable bytes.
+ * responsibility to ensure that @init has at least @len addressable
+ * bytes.
*
- * Returns: a new #GString.
+ * Returns: a new #GString
*/
GString*
g_string_new_len (const gchar *init,
* Compares two strings for equality, returning %TRUE if they are equal.
* For use with #GHashTable.
*
- * Returns: %TRUE if they strings are the same
- * length and contain the same bytes.
+ * Returns: %TRUE if they strings are the same length and contain the
+ * same bytes
*/
gboolean
g_string_equal (const GString *v,
* the standard strcpy() function, except that you do not
* have to worry about having enough space to copy the string.
*
- * Returns: the destination #GString.
+ * Returns: @string
*/
GString*
g_string_assign (GString *string,
/**
* g_string_truncate:
* @string: a #GString
- * @len: the new size of the #GString
+ * @len: the new size of @string
*
* Cuts off the end of the GString, leaving the first @len bytes.
*
- * Returns: the #GString
+ * Returns: @string
*/
GString*
g_string_truncate (GString *string,
/**
* g_string_insert_len:
* @string: a #GString
- * @pos: position in @string where insertion should
+ * @pos: position in @string where insertion should
* happen, or -1 for at the end
* @val: bytes to insert
* @len: number of bytes of @val to insert
- *
- * Inserts @len bytes of @val into @string at @pos.
- * Because @len is provided, @val may contain embedded
- * nuls and need not be nul-terminated. If @pos is -1,
+ *
+ * Inserts @len bytes of @val into @string at @pos.
+ * Because @len is provided, @val may contain embedded
+ * nuls and need not be nul-terminated. If @pos is -1,
* bytes are inserted at the end of the string.
*
- * Since this function does not stop at nul bytes, it is the caller's
- * responsibility to ensure that @val has at least @len addressable bytes.
+ * Since this function does not stop at nul bytes, it is
+ * the caller's responsibility to ensure that @val has at
+ * least @len addressable bytes.
*
- * Returns: the #GString
+ * Returns: @string
*/
GString*
g_string_insert_len (GString *string,
- gssize pos,
+ gssize pos,
const gchar *val,
- gssize len)
+ gssize len)
{
g_return_val_if_fail (string != NULL, NULL);
- g_return_val_if_fail (val != NULL, string);
+ g_return_val_if_fail (len == 0 || val != NULL, string);
+
+ if (len == 0)
+ return string;
if (len < 0)
len = strlen (val);
/* Open up space where we are going to insert. */
if (pos < string->len)
- g_memmove (string->str + pos + len, string->str + pos, string->len - pos);
+ g_memmove (string->str + pos + len, string->str + pos, string->len - pos);
/* Move the source part before the gap, if any. */
if (offset < pos)
- {
- precount = MIN (len, pos - offset);
- memcpy (string->str + pos, val, precount);
- }
+ {
+ precount = MIN (len, pos - offset);
+ memcpy (string->str + pos, val, precount);
+ }
/* Move the source part after the gap, if any. */
if (len > precount)
- memcpy (string->str + pos + precount,
- val + /* Already moved: */ precount + /* Space opened up: */ len,
- len - precount);
+ memcpy (string->str + pos + precount,
+ val + /* Already moved: */ precount + /* Space opened up: */ len,
+ len - precount);
}
else
{
* of the old string to the end, opening up space
*/
if (pos < string->len)
- g_memmove (string->str + pos + len, string->str + pos, string->len - pos);
+ g_memmove (string->str + pos + len, string->str + pos, string->len - pos);
/* insert the new string */
if (len == 1)
return string;
}
+#define SUB_DELIM_CHARS "!$&'()*+,;="
+
+static gboolean
+is_valid (char c, const char *reserved_chars_allowed)
+{
+ if (g_ascii_isalnum (c) ||
+ c == '-' ||
+ c == '.' ||
+ c == '_' ||
+ c == '~')
+ return TRUE;
+
+ if (reserved_chars_allowed &&
+ strchr (reserved_chars_allowed, c) != NULL)
+ return TRUE;
+
+ return FALSE;
+}
+
+static gboolean
+gunichar_ok (gunichar c)
+{
+ return
+ (c != (gunichar) -2) &&
+ (c != (gunichar) -1);
+}
+
+/**
+ * g_string_append_uri_escaped:
+ * @string: a #GString
+ * @unescaped: a string
+ * @reserved_chars_allowed: a string of reserved characters allowed to be used, or %NULL
+ * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters
+ *
+ * Appends @unescaped to @string, escaped any characters that
+ * are reserved in URIs using URI-style escape sequences.
+ *
+ * Returns: @string
+ *
+ * Since: 2.16
+ **/
+GString *
+g_string_append_uri_escaped (GString *string,
+ const char *unescaped,
+ const char *reserved_chars_allowed,
+ gboolean allow_utf8)
+{
+ unsigned char c;
+ const char *end;
+ static const gchar hex[16] = "0123456789ABCDEF";
+
+ g_return_val_if_fail (string != NULL, NULL);
+ g_return_val_if_fail (unescaped != NULL, NULL);
+
+ end = unescaped + strlen (unescaped);
+
+ while ((c = *unescaped) != 0)
+ {
+ if (c >= 0x80 && allow_utf8 &&
+ gunichar_ok (g_utf8_get_char_validated (unescaped, end - unescaped)))
+ {
+ int len = g_utf8_skip [c];
+ g_string_append_len (string, unescaped, len);
+ unescaped += len;
+ }
+ else if (is_valid (c, reserved_chars_allowed))
+ {
+ g_string_append_c (string, c);
+ unescaped++;
+ }
+ else
+ {
+ g_string_append_c (string, '%');
+ g_string_append_c (string, hex[((guchar)c) >> 4]);
+ g_string_append_c (string, hex[((guchar)c) & 0xf]);
+ unescaped++;
+ }
+ }
+
+ return string;
+}
+
/**
* g_string_append:
- * @string: a #GString.
- * @val: the string to append onto the end of the #GString.
+ * @string: a #GString
+ * @val: the string to append onto the end of @string
*
- * Adds a string onto the end of a #GString, expanding it if necessary.
+ * Adds a string onto the end of a #GString, expanding
+ * it if necessary.
*
- * Returns: the #GString.
+ * Returns: @string
*/
GString*
g_string_append (GString *string,
* g_string_append_len:
* @string: a #GString
* @val: bytes to append
- * @len: number of bytes of @val to use.
+ * @len: number of bytes of @val to use
*
- * Appends @len bytes of @val to @string.
- * Because @len is provided, @val may contain
- * embedded nuls and need not be nul-terminated.
+ * Appends @len bytes of @val to @string. Because @len is
+ * provided, @val may contain embedded nuls and need not
+ * be nul-terminated.
*
- * Since this function does not stop at nul bytes, it is the caller's
- * responsibility to ensure that @val has at least @len addressable bytes.
+ * Since this function does not stop at nul bytes, it is
+ * the caller's responsibility to ensure that @val has at
+ * least @len addressable bytes.
*
- * Returns: the #GString
+ * Returns: @string
*/
GString*
g_string_append_len (GString *string,
gssize len)
{
g_return_val_if_fail (string != NULL, NULL);
- g_return_val_if_fail (val != NULL, string);
+ g_return_val_if_fail (len == 0 || val != NULL, string);
return g_string_insert_len (string, -1, val, len);
}
/**
* g_string_append_c:
- * @string: a #GString.
- * @c: the byte to append onto the end of the #GString.
+ * @string: a #GString
+ * @c: the byte to append onto the end of @string
*
- * Adds a byte onto the end of a #GString, expanding it if necessary.
+ * Adds a byte onto the end of a #GString, expanding
+ * it if necessary.
*
- * Returns: the #GString.
+ * Returns: @string
*/
#undef g_string_append_c
GString*
/**
* g_string_prepend:
* @string: a #GString
- * @val: the string to prepend on the start of the #GString
+ * @val: the string to prepend on the start of @string
*
* Adds a string on to the start of a #GString,
* expanding it if necessary.
*
- * Returns: the #GString
+ * Returns: @string
*/
GString*
g_string_prepend (GString *string,
* Because @len is provided, @val may contain
* embedded nuls and need not be nul-terminated.
*
- * Since this function does not stop at nul bytes, it is the caller's
- * responsibility to ensure that @val has at least @len addressable bytes.
+ * Since this function does not stop at nul bytes,
+ * it is the caller's responsibility to ensure that
+ * @val has at least @len addressable bytes.
*
- * Returns: the #GString passed in
+ * Returns: @string
*/
GString*
g_string_prepend_len (GString *string,
* Adds a byte onto the start of a #GString,
* expanding it if necessary.
*
- * Returns: the #GString
+ * Returns: @string
*/
GString*
g_string_prepend_c (GString *string,
/**
* g_string_prepend_unichar:
- * @string: a #GString.
- * @wc: a Unicode character.
+ * @string: a #GString
+ * @wc: a Unicode character
*
* Converts a Unicode character into UTF-8, and prepends it
* to the string.
*
- * Return value: @string.
+ * Return value: @string
**/
GString*
g_string_prepend_unichar (GString *string,
* Inserts a copy of a string into a #GString,
* expanding it if necessary.
*
- * Returns: the #GString
+ * Returns: @string
*/
GString*
g_string_insert (GString *string,
*
* Inserts a byte into a #GString, expanding it if necessary.
*
- * Returns: the #GString
+ * Returns: @string
*/
GString*
g_string_insert_c (GString *string,
* g_string_insert_unichar:
* @string: a #GString
* @pos: the position at which to insert character, or -1 to
- * append at the end of the string.
+ * append at the end of the string
* @wc: a Unicode character
*
* Converts a Unicode character into UTF-8, and insert it
* @val: the string that will overwrite the @string starting at @pos
* @len: the number of bytes to write from @val
*
- * Overwrites part of a string, lengthening it if necessary. This function
- * will work with embedded NULLs.
+ * Overwrites part of a string, lengthening it if necessary.
+ * This function will work with embedded nuls.
*
* Return value: @string
*
* Since: 2.14
**/
GString *
-g_string_overwrite_len (GString *string,
- gsize pos,
- const gchar *val,
- gssize len)
+g_string_overwrite_len (GString *string,
+ gsize pos,
+ const gchar *val,
+ gssize len)
{
gsize end;
* Removes @len bytes from a #GString, starting at position @pos.
* The rest of the #GString is shifted down to fill the gap.
*
- * Returns: the #GString
+ * Returns: @string
*/
GString*
g_string_erase (GString *string,
*
* Return value: passed-in @string pointer, with all the upper case
* characters converted to lower case in place, with
- * semantics that exactly match g_ascii_tolower.
+ * semantics that exactly match g_ascii_tolower().
**/
GString*
g_string_ascii_down (GString *string)
*
* Return value: passed-in @string pointer, with all the lower case
* characters converted to upper case in place, with
- * semantics that exactly match g_ascii_toupper.
+ * semantics that exactly match g_ascii_toupper().
**/
GString*
g_string_ascii_up (GString *string)
*
* Returns: the #GString.
*
- * Deprecated:2.2: This function uses the locale-specific tolower() function,
- * which is almost never the right thing. Use g_string_ascii_down() or
- * g_utf8_strdown() instead.
+ * Deprecated:2.2: This function uses the locale-specific
+ * tolower() function, which is almost never the right thing.
+ * Use g_string_ascii_down() or g_utf8_strdown() instead.
*/
GString*
g_string_down (GString *string)
*
* Converts a #GString to uppercase.
*
- * Return value: the #GString
+ * Return value: @string
*
- * Deprecated:2.2: This function uses the locale-specific toupper() function,
- * which is almost never the right thing. Use g_string_ascii_up() or
- * g_utf8_strup() instead.
+ * Deprecated:2.2: This function uses the locale-specific
+ * toupper() function, which is almost never the right thing.
+ * Use g_string_ascii_up() or g_utf8_strup() instead.
**/
GString*
g_string_up (GString *string)
/**
* g_string_append_vprintf:
- * @string: a #GString.
- * @format: the string format. See the printf() documentation.
- * @args: the list of arguments to insert in the output.
+ * @string: a #GString
+ * @format: the string format. See the printf() documentation
+ * @args: the list of arguments to insert in the output
*
* Appends a formatted string onto the end of a #GString.
- * This function is is similar to g_string_append_printf()
+ * This function is similar to g_string_append_printf()
* except that the arguments to the format string are passed
* as a va_list.
*
*/
void
g_string_append_vprintf (GString *string,
- const gchar *fmt,
+ const gchar *format,
va_list args)
{
- gsize length;
-
+ gchar *buf;
+ gint len;
+
g_return_if_fail (string != NULL);
- g_return_if_fail (fmt != NULL);
+ g_return_if_fail (format != NULL);
+
+ len = g_vasprintf (&buf, format, args);
- length = g_printf_string_upper_bound (fmt, args);
- g_string_maybe_expand (string, length);
- length = g_vsnprintf (string->str + string->len, length, fmt, args);
- string->len += length;
+ if (len >= 0)
+ {
+ g_string_maybe_expand (string, len);
+ memcpy (string->str + string->len, buf, len + 1);
+ string->len += len;
+ g_free (buf);
+ }
}
/**
* g_string_vprintf:
- * @string: a #GString.
- * @format: the string format. See the printf() documentation.
- * @Varargs: the parameters to insert into the format string.
+ * @string: a #GString
+ * @format: the string format. See the printf() documentation
+ * @args: the parameters to insert into the format string
*
- * Writes a formatted string into a #GString. This function
- * is similar to g_string_printf() except that the arguments to
- * the format string are passed as a va_list.
+ * Writes a formatted string into a #GString.
+ * This function is similar to g_string_printf() except that
+ * the arguments to the format string are passed as a va_list.
*
* Since: 2.14
*/
void
g_string_vprintf (GString *string,
- const gchar *fmt,
+ const gchar *format,
va_list args)
{
g_string_truncate (string, 0);
- g_string_append_vprintf (string, fmt, args);
+ g_string_append_vprintf (string, format, args);
}
/**
* g_string_sprintf:
- * @string: a #GString.
- * @format: the string format. See the sprintf() documentation.
- * @Varargs: the parameters to insert into the format string.
+ * @string: a #GString
+ * @format: the string format. See the sprintf() documentation
+ * @Varargs: the parameters to insert into the format string
*
* Writes a formatted string into a #GString.
* This is similar to the standard sprintf() function,
/**
* g_string_printf:
- * @string: a #GString.
- * @format: the string format. See the printf() documentation.
- * @Varargs: the parameters to insert into the format string.
+ * @string: a #GString
+ * @format: the string format. See the printf() documentation
+ * @Varargs: the parameters to insert into the format string
*
* Writes a formatted string into a #GString.
* This is similar to the standard sprintf() function,
* #GString are destroyed.
*/
void
-g_string_printf (GString *string,
- const gchar *fmt,
+g_string_printf (GString *string,
+ const gchar *format,
...)
{
va_list args;
g_string_truncate (string, 0);
- va_start (args, fmt);
- g_string_append_vprintf (string, fmt, args);
+ va_start (args, format);
+ g_string_append_vprintf (string, format, args);
va_end (args);
}
/**
* g_string_sprintfa:
- * @string: a #GString.
- * @format: the string format. See the sprintf() documentation.
- * @Varargs: the parameters to insert into the format string.
+ * @string: a #GString
+ * @format: the string format. See the sprintf() documentation
+ * @Varargs: the parameters to insert into the format string
*
* Appends a formatted string onto the end of a #GString.
- * This function is is similar to g_string_sprintf() except that
+ * This function is similar to g_string_sprintf() except that
* the text is appended to the #GString.
*
- * Deprecated: This function has been renamed to
- * g_string_append_printf().
+ * Deprecated: This function has been renamed to g_string_append_printf()
*/
/**
* g_string_append_printf:
- * @string: a #GString.
- * @format: the string format. See the printf() documentation.
- * @Varargs: the parameters to insert into the format string.
+ * @string: a #GString
+ * @format: the string format. See the printf() documentation
+ * @Varargs: the parameters to insert into the format string
*
* Appends a formatted string onto the end of a #GString.
- * This function is is similar to g_string_printf() except
+ * This function is similar to g_string_printf() except
* that the text is appended to the #GString.
*/
void
-g_string_append_printf (GString *string,
- const gchar *fmt,
+g_string_append_printf (GString *string,
+ const gchar *format,
...)
{
va_list args;
- va_start (args, fmt);
- g_string_append_vprintf (string, fmt, args);
+ va_start (args, format);
+ g_string_append_vprintf (string, format, args);
va_end (args);
}
-
-#define __G_STRING_C__
-#include "galiasdef.c"
projects / platform / upstream / glib.git / blobdiff