From: John Darrington <john@darrington.wattle.id.au>
Date: Sun, 16 May 2010 10:48:57 +0000 (+0200)
Subject: Expanded comments to src/libpspp/i18n.[ch]
X-Git-Tag: v0.7.5~25^2~5
X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=26c0db0a90c83201a90583e2b9afa3c11f08ec2d;p=pspp-builds.git

Expanded comments to src/libpspp/i18n.[ch]
---

diff --git a/src/libpspp/i18n.c b/src/libpspp/i18n.c
index 80a0ed35..8e99aa04 100644
--- a/src/libpspp/i18n.c
+++ b/src/libpspp/i18n.c
@@ -86,6 +86,9 @@ create_iconv (const char* tocode, const char* fromcode)
   return converter->conv;
 }
 
+
+/* Similar to recode_string_pool, but allocates the returned value on the heap instead of 
+   in a pool.  It is the caller's responsibility to free the returned value. */
 char *
 recode_string (const char *to, const char *from,
 	       const char *text, int length)
@@ -94,10 +97,19 @@ recode_string (const char *to, const char *from,
 }
 
 
-/* Return a string based on TEXT which must be encoded using FROM.
-   The returned string will be encoded in TO.
-   If length is not -1, then it must be the number of bytes in TEXT.
-   The returned string must be freed when no longer required.
+/* 
+Converts the string TEXT, which should be encoded in FROM-encoding, to a
+dynamically allocated string in TO-encoding.   Any characters which cannot
+be converted will be represented by '?'.
+
+LENGTH should be the length of the string or -1, if null terminated.
+
+The returned string will be allocated on POOL.
+
+This function's behaviour differs from that of g_convert_with_fallback provided
+by GLib.  The GLib function will fail (returns NULL) if any part of the input
+string is not valid in the declared input encoding.  This function however perseveres
+even in the presence of badly encoded input.
 */
 char *
 recode_string_pool (const char *to, const char *from,
diff --git a/src/libpspp/i18n.h b/src/libpspp/i18n.h
index 9c8f7c14..e2663a02 100644
--- a/src/libpspp/i18n.h
+++ b/src/libpspp/i18n.h
@@ -26,9 +26,28 @@ void  i18n_init (void);
 
 struct pool;
 
+
+/* 
+Converts the string TEXT, which should be encoded in FROM-encoding, to a
+dynamically allocated string in TO-encoding.   Any characters which cannot
+be converted will be represented by '?'.
+
+LENGTH should be the length of the string or -1, if null terminated.
+
+The returned string will be allocated on POOL.
+
+This function's behaviour differs from that of g_convert_with_fallback provided
+by GLib.  The GLib function will fail (returns NULL) if any part of the input
+string is not valid in the declared input encoding.  This function however perseveres
+even in the presence of badly encoded input.
+*/
 char *recode_string_pool (const char *to, const char *from,
 			  const char *text, int length, struct pool *pool);
 
+
+
+/* Similar to recode_string_pool, but allocates the returned value on the heap instead of 
+   in a pool.  It is the caller's responsibility to free the returned value. */
 char *recode_string (const char *to, const char *from,
 		      const char *text, int len);