From: Benjamin Otte <otte@gnome.org>
Date: Tue, 27 Oct 2009 20:07:13 +0000 (+0100)
Subject: Clarify documentation about g_convert() nul-terminated returns
X-Git-Tag: 2.23.0~79
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=5a633f82dbbce067c56fba0ee372fd341b76368d;p=platform%2Fupstream%2Fglib.git

Clarify documentation about g_convert() nul-terminated returns

THere is effectively no nul-termination for multibyte characters.
---

diff --git a/glib/gconvert.c b/glib/gconvert.c
index 7a20cb5..f2141a3 100644
--- a/glib/gconvert.c
+++ b/glib/gconvert.c
@@ -566,8 +566,16 @@ close_converter (GIConv cd)
  * </footnote>. 
  *
  * Return value: If the conversion was successful, a newly allocated
- *               nul-terminated string, which must be freed with
- *               g_free(). Otherwise %NULL and @error will be set.
+ *               nul-terminated<footnote id="nul-returns">
+ *                <para>
+ *                 Nul-terminated return values from conversion functions
+ *                 are terminated by a single 0 byte only. This means that
+ *                 for multibyte character sets like UTF-16, they must be
+ *                 treated as not nul-terminated.
+ *                </para>
+ *               </footnote> 
+ *               string, which must be freed with g_free(). Otherwise %NULL 
+ *               and @error will be set.
  **/
 gchar*
 g_convert_with_iconv (const gchar *str,
@@ -719,8 +727,9 @@ g_convert_with_iconv (const gchar *str,
  * conversions<footnoteref linkend="streaming-state"/>.
  *
  * Return value: If the conversion was successful, a newly allocated
- *               nul-terminated string, which must be freed with
- *               g_free(). Otherwise %NULL and @error will be set.
+ *               nul-terminated<footnoteref linkend="nul-returns"/> string,
+ *               which must be freed with g_free(). Otherwise %NULL and
+ *               @error will be set.
  **/
 gchar*
 g_convert (const gchar *str,
@@ -794,8 +803,9 @@ g_convert (const gchar *str,
  * conversions<footnoteref linkend="streaming-state"/>.
  *
  * Return value: If the conversion was successful, a newly allocated
- *               nul-terminated string, which must be freed with
- *               g_free(). Otherwise %NULL and @error will be set.
+ *               nul-terminated<footnoteref linkend="nul-returns"/> string,
+ *               which must be freed with g_free(). Otherwise %NULL and
+ *               @error will be set.
  **/
 gchar*
 g_convert_with_fallback (const gchar *str,