* 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>
* @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.
+ * 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.
*/
/**
/**
* 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