From 26c0db0a90c83201a90583e2b9afa3c11f08ec2d Mon Sep 17 00:00:00 2001 From: John Darrington Date: Sun, 16 May 2010 12:48:57 +0200 Subject: [PATCH] Expanded comments to src/libpspp/i18n.[ch] --- src/libpspp/i18n.c | 20 ++++++++++++++++---- src/libpspp/i18n.h | 19 +++++++++++++++++++ 2 files changed, 35 insertions(+), 4 deletions(-) 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); -- 2.30.2