As promised earlier, here's a patch with some new functions for GString.
I'll split them up with related changes, so this is just the first of a
sequence.
There's 3 functions added here, g_string_clone, g_string_new_lenz, and
g_string_slice. Each is a constructor, to return a new GString object.
* g_string_clone() is a convenient wrapper to take a copy of an
existing GString;
g_string_clone(s) == g_string_new(s->str)
Except it returns NULL if s == NULL.
* g_string_new_lenz() is similar to g_string_new_len(), only it appends
a terminating nul byte to the string buffer, making it safe to
printf() or use as a normal gchar* string.
* g_string_slice() returns a new GString containing just a portion of
the given string.
I wasn't quite sure how to implement these, in terms of writing new
code, or just calling one of the other functions. And also I'm rather
new to the documentation system, so I hope I've done those right.
Comments / suggestions / corrections would be most appreciated.
---
Some other ideas
================
I have planned at least two other patches.
The first to add two new constructors that I find quite useful in my
code:
GString* g_string_new_sprintf(const gchar *fmt, ...);
GString* g_string_new_vsprintf(const gchar *fmt, va_list args);
These are a little more convenient than the g_string_new() /
g_string_sprintf() pair, especially if the contructed string is being
return'd from a function.
The other has some other useful functions:
gboolean g_string_caseequal(GString *s1, GString *s2);
gint g_string_indexof(GString *str, gchar c);
void g_string_destroy(GString *str);
The latter is a function which would simply wrap
g_string_free(str, TRUE);
but whose type makes it usable as a GDestroyNotify callback.
I also have some slightly more special-purpose functions which I find
useful, but I'm not sure of their place in such a general-purpose
library as GLib. These are:
GString* g_string_pull_token(GString *str);
// Deletes a token from the beginning of str, and returns it
GString* g_string_pull_line(GString *str);
// Deletes a line from the beginning of str, and returns it
Finally, I have some which I find useful for dealing with lists of
strings. A trivial
typedef GList GStringList;
and some functions
GStringList* g_string_split(GString *str, gchar c);
GString* g_string_list_fold(GStringList *list, const char *sep);
void g_string_list_free(GStringList *list, gboolean free_str, gboolean free_data);
I'd be interested to hear opinions on these ideas; especially the later
ones. It's quite possible that these are too special-purpose to warrant
inclusion in GLib. Though I have found them quite useful in my programs,
so I though I'd at least suggest inclusion, and see what the general
opinion is.
--
Paul "LeoNerd" Evans
leonerd leonerd org uk
ICQ# 4135350 | Registered Linux# 179460
http://www.leonerd.org.uk/
Index: docs/reference/glib/glib-sections.txt
===================================================================
RCS file: /cvs/gnome/glib/docs/reference/glib/glib-sections.txt,v
retrieving revision 1.134
diff -u -r1.134 glib-sections.txt
--- docs/reference/glib/glib-sections.txt 19 Dec 2005 21:22:29 -0000 1.134
+++ docs/reference/glib/glib-sections.txt 20 Dec 2005 22:14:52 -0000
@@ -1794,8 +1794,11 @@
<FILE>strings</FILE>
GString
g_string_new
+g_string_clone
g_string_new_len
+g_string_new_lenz
g_string_sized_new
+g_string_slice
g_string_assign
g_string_sprintf
g_string_sprintfa
Index: docs/reference/glib/tmpl/strings.sgml
===================================================================
RCS file: /cvs/gnome/glib/docs/reference/glib/tmpl/strings.sgml,v
retrieving revision 1.28
diff -u -r1.28 strings.sgml
--- docs/reference/glib/tmpl/strings.sgml 20 Dec 2005 04:44:25 -0000 1.28
+++ docs/reference/glib/tmpl/strings.sgml 20 Dec 2005 22:14:52 -0000
@@ -46,6 +46,15 @@
@Returns: the new #GString.
+<!-- ##### FUNCTION g_string_clone ##### -->
+<para>
+
+</para>
+
+ orig:
+ Returns:
+
+
<!-- ##### FUNCTION g_string_new_len ##### -->
<para>
Creates a new #GString with @len bytes of the @init buffer. Because a length is
@@ -57,6 +66,16 @@
@Returns: a new #GString.
+<!-- ##### FUNCTION g_string_new_lenz ##### -->
+<para>
+
+</para>
+
+ init:
+ len:
+ Returns:
+
+
<!-- ##### FUNCTION g_string_sized_new ##### -->
<para>
Creates a new #GString, with enough space for @dfl_size bytes.
@@ -68,6 +87,17 @@
@Returns: the new #GString.
+<!-- ##### FUNCTION g_string_slice ##### -->
+<para>
+
+</para>
+
+ string:
+ pos:
+ len:
+ Returns:
+
+
<!-- ##### FUNCTION g_string_assign ##### -->
<para>
Copies the bytes from a string into a #GString, destroying any previous
@@ -91,6 +121,7 @@
</para>
@Deprecated: This function has been renamed to g_string_printf().
+<!-- # Unused Parameters # -->
@string: a #GString.
@format: the string format. See the sprintf() documentation.
@Varargs: the parameters to insert into the format string.
@@ -104,6 +135,7 @@
</para>
@Deprecated: This function has been renamed to g_string_append_printf().
+<!-- # Unused Parameters # -->
@string: a #GString.
@format: the string format. See the sprintf() documentation.
@Varargs: the parameters to insert into the format string.
Index: glib/gstring.c
===================================================================
RCS file: /cvs/gnome/glib/glib/gstring.c,v
retrieving revision 1.49
diff -u -r1.49 gstring.c
--- glib/gstring.c 5 Dec 2005 15:38:52 -0000 1.49
+++ glib/gstring.c 20 Dec 2005 22:14:53 -0000
@@ -297,6 +297,26 @@
return string;
}
+/**
+ * g_string_clone:
+ * @orig: a #GString object to copy
+ *
+ * Creates a new #GString, initialised to contain the same data as @orig. If
+ * @orig is %NULL then no new string is allocated and %NULL is returned
+ * instead.
+ *
+ * Return value: a new #GString or %NULL
+ */
+
+GString*
+g_string_clone (const GString *orig)
+{
+ if (orig)
+ return g_string_new(orig->str);
+ else
+ return NULL;
+}
+
GString*
g_string_new_len (const gchar *init,
gssize len)
@@ -315,6 +335,38 @@
return string;
}
}
+/**
+ * g_string_new_lenz:
+ * @init: initial contents of string.
+ * @len: length of @init to use.
+ *
+ * Creates a new #GString with @len bytes of the @init buffer, followed by a
+ * nul-termination. Because a length is provided, @init need not be
+ * nul-terminated.
+ *
+ * Return value: a new #GString
+ */
+
+GString*
+g_string_new_lenz (const gchar *init,
+ gssize len)
+{
+ GString *string;
+
+ if (len < 0)
+ return g_string_new (init);
+ else
+ {
+ string = g_string_sized_new (len + 1);
+
+ if (init)
+ g_string_append_len (string, init, len);
+
+ g_string_append_c (string, '\0');
+
+ return string;
+ }
+}
gchar*
g_string_free (GString *string,
@@ -924,6 +976,38 @@
va_start (args, fmt);
g_string_append_printf_internal (string, fmt, args);
va_end (args);
+}
+
+/**
+ * g_string_slice:
+ * @string: a #GString.
+ * @pos: The zero-based index of the start of the section to copy
+ * @len: The number of bytes to copy
+ *
+ * Creates a new #GString by taking a slice of the given string. The slice
+ * will begin at the @pos character, and contain at most @len bytes. The
+ * returned string will be nul-terminated.
+ *
+ * Return value: a new #GString
+ */
+
+GString*
+g_string_slice (GString* string,
+ guint pos,
+ guint len)
+{
+ GString *ret = g_string_new("");
+
+ if (pos > string->len || len < 1)
+ return ret;
+
+ if (pos + len > string->len)
+ len = string->len - pos;
+
+ g_string_append_len (ret, string->str, len);
+ g_string_append_c (ret, '\0');
+
+ return ret;
}
#define __G_STRING_C__
Index: glib/gstring.h
===================================================================
RCS file: /cvs/gnome/glib/glib/gstring.h,v
retrieving revision 1.15
diff -u -r1.15 gstring.h
--- glib/gstring.h 2 Dec 2004 01:06:17 -0000 1.15
+++ glib/gstring.h 20 Dec 2005 22:14:53 -0000
@@ -59,8 +59,11 @@
/* Strings
*/
GString* g_string_new (const gchar *init);
+GString* g_string_clone (const GString *orig);
GString* g_string_new_len (const gchar *init,
gssize len);
+GString* g_string_new_lenz (const gchar *init,
+ gssize len);
GString* g_string_sized_new (gsize dfl_size);
gchar* g_string_free (GString *string,
gboolean free_segment);
@@ -115,6 +118,9 @@
void g_string_append_printf (GString *string,
const gchar *format,
...) G_GNUC_PRINTF (2, 3);
+GString* g_string_slice (GString *string,
+ guint pos,
+ guint len);
/* -- optimize g_strig_append_c --- */
#ifdef G_CAN_INLINE
Attachment:
signature.asc
Description: Digital signature