* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
*/
/*
#include "config.h"
-#ifdef HAVE_UNISTD_H
-#include <unistd.h>
-#endif
#include <stdarg.h>
#include <stdlib.h>
#include <stdio.h>
#include "gprintf.h"
-/* Hash Functions.
- */
-
/**
- * 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
- * @key_equal_func parameter, when using strings as keys in a #GHashTable.
- *
- * 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().
+ * SECTION:strings
+ * @title: Strings
+ * @short_description: text buffers which grow automatically
+ * as text is added
*
- * Returns: %TRUE if the two keys match
+ * A #GString is an object that handles the memory management of a C
+ * string for you. The emphasis of #GString is on text, typically
+ * UTF-8. Crucially, the "str" member of a #GString is guaranteed to
+ * have a trailing nul character, and it is therefore always safe to
+ * call functions such as strchr() or g_strdup() on it.
+ *
+ * However, a #GString can also hold arbitrary binary data, because it
+ * has a "len" member, which includes any possible embedded nul
+ * characters in the data. Conceptually then, #GString is like a
+ * #GByteArray with the addition of many convenience methods for text,
+ * and a guaranteed nul terminator.
*/
-gboolean
-g_str_equal (gconstpointer v1,
- gconstpointer v2)
-{
- const gchar *string1 = v1;
- const gchar *string2 = v2;
-
- return strcmp (string1, string2) == 0;
-}
/**
- * g_str_hash:
- * @v: a string key
- *
- * Converts a string to a hash value.
- *
- * This function implements the widely used "djb" hash apparently posted
- * by Daniel Bernstein to comp.lang.c some time ago. The 32 bit
- * unsigned hash value starts at 5381 and for each byte 'c' in the
- * string, is updated: <literal>hash = hash * 33 + c</literal>. This
- * function uses the signed value of each byte.
- *
- * It can be passed to g_hash_table_new() as the @hash_func parameter,
- * when using strings as keys in a #GHashTable.
+ * GString:
+ * @str: points to the character data. It may move as text is added.
+ * The @str field is null-terminated and so
+ * can be used as an ordinary C string.
+ * @len: contains the length of the string, not including the
+ * terminating nul byte.
+ * @allocated_len: the number of bytes that can be stored in the
+ * string before it needs to be reallocated. May be larger than @len.
*
- * Returns: a hash value corresponding to the key
+ * The GString struct contains the public fields of a GString.
*/
-guint
-g_str_hash (gconstpointer v)
-{
- const signed char *p;
- guint32 h = 5381;
-
- for (p = v; *p != '\0'; p++)
- h = (h << 5) + h + *p;
- return h;
-}
#define MY_MAXSIZE ((gsize)-1)
}
}
-/**
- * SECTION:strings
- * @title: Strings
- * @short_description: text buffers which grow automatically
- * as text is added
- *
- * A #GString is an object that handles the memory management
- * of a C string for you. You can think of it as similar to a
- * Java StringBuffer. In addition to the string itself, GString
- * stores the length of the string, so can be used for binary
- * data with embedded nul bytes. To access the C string managed
- * by the GString @string, simply use @string->str.
- */
-
-/**
- * GString:
- * @str: points to the character data. It may move as text is added.
- * The @str field is null-terminated and so
- * can be used as an ordinary C string.
- * @len: contains the length of the string, not including the
- * terminating nul byte.
- * @allocated_len: the number of bytes that can be stored in the
- * string before it needs to be reallocated. May be larger than @len.
- *
- * The GString struct contains the public fields of a GString.
- */
-
-
static void
g_string_maybe_expand (GString *string,
gsize len)
/**
* g_string_new:
- * @init: the initial text to copy into the string
+ * @init: (allow-none): the initial text to copy into the string, or %NULL to
+ * start with an empty string.
*
* Creates a new #GString, initialized with the given string.
*
}
/**
+ * g_string_free_to_bytes:
+ * @string: (transfer full): a #GString
+ *
+ * Transfers ownership of the contents of @string to a newly allocated
+ * #GBytes. The #GString structure itself is deallocated, and it is
+ * therefore invalid to use @string after invoking this function.
+ *
+ * Note that while #GString ensures that its buffer always has a
+ * trailing nul character (not reflected in its "len"), the returned
+ * #GBytes does not include this extra nul; i.e. it has length exactly
+ * equal to the "len" member.
+ *
+ * Returns: A newly allocated #GBytes containing contents of @string; @string itself is freed
+ * Since: 2.34
+ */
+GBytes*
+g_string_free_to_bytes (GString *string)
+{
+ gsize len;
+ gchar *buf;
+
+ g_return_val_if_fail (string != NULL, NULL);
+
+ len = string->len;
+
+ buf = g_string_free (string, FALSE);
+
+ return g_bytes_new_take (buf, len);
+}
+
+/**
* g_string_equal:
* @v: a #GString
* @v2: another #GString
* 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
+ * Returns: %TRUE if the strings are the same length and contain the
* same bytes
*/
gboolean
* of the newly added area are undefined. (However, as
* always, string->str[string->len] will be a nul byte.)
*
- * Return value: @string
+ * Returns: @string
*/
GString *
g_string_set_size (GString *string,
/* 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);
+ memmove (string->str + pos + len, string->str + pos, string->len - pos);
/* Move the source part before the gap, if any. */
if (offset < pos)
* 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);
+ memmove (string->str + pos + len, string->str + pos, string->len - pos);
/* insert the new string */
if (len == 1)
* Converts a Unicode character into UTF-8, and appends it
* to the string.
*
- * Return value: @string
+ * Returns: @string
*/
GString *
g_string_append_unichar (GString *string,
* Converts a Unicode character into UTF-8, and prepends it
* to the string.
*
- * Return value: @string
+ * Returns: @string
*/
GString *
g_string_prepend_unichar (GString *string,
/* If not just an append, move the old stuff */
if (pos < string->len)
- g_memmove (string->str + pos + 1, string->str + pos, string->len - pos);
+ memmove (string->str + pos + 1, string->str + pos, string->len - pos);
string->str[pos] = c;
* Converts a Unicode character into UTF-8, and insert it
* into the string at the given position.
*
- * Return value: @string
+ * Returns: @string
*/
GString *
g_string_insert_unichar (GString *string,
/* If not just an append, move the old stuff */
if (pos < string->len)
- g_memmove (string->str + pos + charlen, string->str + pos, string->len - pos);
+ memmove (string->str + pos + charlen, string->str + pos, string->len - pos);
dest = string->str + pos;
/* Code copied from g_unichar_to_utf() */
*
* Overwrites part of a string, lengthening it if necessary.
*
- * Return value: @string
+ * Returns: @string
*
* Since: 2.14
*/
* Overwrites part of a string, lengthening it if necessary.
* This function will work with embedded nuls.
*
- * Return value: @string
+ * Returns: @string
*
* Since: 2.14
*/
g_return_val_if_fail (pos + len <= string->len, string);
if (pos + len < string->len)
- g_memmove (string->str + pos, string->str + pos + len, string->len - (pos + len));
+ memmove (string->str + pos, string->str + pos + len, string->len - (pos + len));
}
string->len -= len;
*
* Converts all uppercase ASCII letters to lowercase ASCII letters.
*
- * Return value: passed-in @string pointer, with all the
+ * Returns: passed-in @string pointer, with all the
* uppercase characters converted to lowercase in place,
* with semantics that exactly match g_ascii_tolower().
*/
*
* Converts all lowercase ASCII letters to uppercase ASCII letters.
*
- * Return value: passed-in @string pointer, with all the
+ * Returns: passed-in @string pointer, with all the
* lowercase characters converted to uppercase in place,
* with semantics that exactly match g_ascii_toupper().
*/
*
* Converts a #GString to uppercase.
*
- * Return value: @string
+ * Returns: @string
*
* Deprecated:2.2: This function uses the locale-specific
* toupper() function, which is almost never the right thing.
projects / platform / upstream / glib.git / blobdiff