Improve docs about string functions taking a length. (#378727)

2006-12-17  Behdad Esfahbod  <behdad@gnome.org>

        * glib/gstring.c: Improve docs about string functions taking a
        length.  (#378727)

diff --git a/ChangeLog b/ChangeLog
index 794e469..8929243 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2006-12-17  Behdad Esfahbod  <behdad@gnome.org>
+
+       * glib/gstring.c: Improve docs about string functions taking a
+       length.  (#378727)
+
 2006-12-17  Matthias Clasen  <mclasen@redhat.com>
 
        * configure.in: Use AC_LANG_SOURCE for the clock test.

diff --git a/glib/gstring.c b/glib/gstring.c
index 7b2b974..9e0e295 100644 (file)
--- a/glib/gstring.c
+++ b/glib/gstring.c
@@ -297,8 +297,11 @@ g_string_chunk_insert_const (GStringChunk *chunk,
  * Adds a copy of the first @len bytes of @string to the #GStringChunk. The
  * copy is nul-terminated.
  * 
- * The characters in the string can be changed, if necessary, though you
- * should not change anything after the end of the string.
+ * 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.
+ *
+ * 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
  * 
@@ -421,6 +424,9 @@ g_string_new (const gchar *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.
+ *
  * Returns: a new #GString.
  */
 GString*
@@ -629,6 +635,9 @@ g_string_set_size (GString *string,
  * 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.
+ *
  * Returns: the #GString
  */
 GString*
@@ -731,6 +740,9 @@ g_string_append (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.
+ *
  * Returns: the #GString
  */
 GString*
@@ -812,6 +824,9 @@ 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.
+ *
  * Returns: the #GString passed in
  */
 GString*