From: Matthias Clasen <mclasen@redhat.com>
Date: Wed, 30 Sep 2009 00:39:39 +0000 (-0400)
Subject: Improve docs for g_utf16_to_utf8
X-Git-Tag: 2.22.1~5
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=442dadf3118cf3e2e9617461eb045f61483d58fc;p=platform%2Fupstream%2Fglib.git

Improve docs for g_utf16_to_utf8

Document that g_utf16_to_utf8 does not validate the resulting
UTF-8 string. See bug 596314.
---

diff --git a/glib/gutf8.c b/glib/gutf8.c
index 8225e48..ba13d0b 100644
--- a/glib/gutf8.c
+++ b/glib/gutf8.c
@@ -1085,9 +1085,15 @@ g_ucs4_to_utf8 (const gunichar *str,
  *
  * Note that the input is expected to be already in native endianness,
  * an initial byte-order-mark character is not handled specially.
- * g_convert() can be used to convert a byte buffer of UTF-16 data of 
+ * g_convert() can be used to convert a byte buffer of UTF-16 data of
  * ambiguous endianess.
- * 
+ *
+ * Further note that this function does not validate the result
+ * string; it may e.g. include embedded NUL characters. The only
+ * validation done by this function is to ensure that the input can
+ * be correctly interpreted as UTF-16, i.e. it doesn't contain
+ * things unpaired surrogates.
+ *
  * Return value: a pointer to a newly allocated UTF-8 string.
  *               This value must be freed with g_free(). If an
  *               error occurs, %NULL will be returned and
@@ -1095,9 +1101,9 @@ g_ucs4_to_utf8 (const gunichar *str,
  **/
 gchar *
 g_utf16_to_utf8 (const gunichar2  *str,
-		 glong             len,              
-		 glong            *items_read,       
-		 glong            *items_written,    
+		 glong             len,
+		 glong            *items_read,
+		 glong            *items_written,
 		 GError          **error)
 {
   /* This function and g_utf16_to_ucs4 are almost exactly identical - The lines that differ