Changes between Version 4 and Version 5 of rfc23_ogr_unicode

Timestamp:

Apr 25, 2008, 12:39:17 PM (16 years ago)

Author:

warmerdam

Comment:

replace CPLString stuff with a C API.

rfc23_ogr_unicode

@@ -13 +13 @@
 GDAL should be modified in a way to support three following main ideas:
 
- 1. The CPLString class will be upgraded to support a variety of encoding conversions, including conversion between representations (ie. UTF-8 to UCS-16/wchar_t). 
+ 1. C Functions will be provided to support a variety of encoding conversions, including conversion between representations (ie. UTF-8 to UCS-16/wchar_t). 
  2. Character encodings will be identified by iconv() style strings. 
  3. OFTString/OFTStringList feature attributes in OGR will be treated as being in UTF-8.
@@ -19 +19 @@
 This RFC specifically does not attempt to address issues of using non-ascii filenames.  It also does not attempt to make definitions about the encoding of other strings used in GDAL/OGR (such as field names, metadata, etc).  These would presumably be addressed in a later RFC building on this one.
 
-== CPLString ==
+== CPLRecode API ==
 
-The CPLString class will now be assumed to be a potentially multi-byte 
-encoded string, but with no effect within the CPLString to keep track of
-the encoding it is in.  This is left to the higher level code for now. 
-
-However, the CPLString is extended with some convenient mechanisms for 
-recoding, and for conversion of UTF-8 to/from "wchar_t" (aka UCS-2).
-
-It is stressed that normal initialization of a CPLString from "const char *"
-does not attempt to do any conversions to/from UTF-8.  This rule is kept, 
-in part to minimize string processing costs for the common case.  When encoding
-is believed to be an issue the calling code must keep track. 
+The following three C callable functions will be introduced for recoding strings, and for converting between wchar_t (wide character) and char (multi-byte) formats:
 
 {{{
+char *CPLRecode( const char *pszSource, 
+                 const char *pszSrcEncoding, const char *pszDstEncoding );
 
-// Convert the internal string to a new encoding.
-char* CPLString::recode( const char *pszSrcEncoding, const char *pszDstEncoding );
-
-// Set value based on input encoded string with CPLString set to UTF-8. 
-// This is equivelent to normal setting, and then a recode() with a destination
-// encoding of "UTF-8" and thus is just for convenience.
-
-CPLString &CPLString::SetAsUTF8( const char *pszInput, const char *pszEncoding = "" );
-
-// Set value based on input encoded string with CPLString set to UTF-8. 
-// This is equivelent to normal setting, and then a recode() with a destination
-// encoding of "UTF-8" and thus is just for convenience.
-
-CPLString &CPLString::SetAsUTF8( const wchar_t *pszInput, const char *pszEncoding = "UCS-2" );
-
-// Construct UTF-8 string object from array of wchar_t elements. 
-CPLString::CPLString( const wchar_t*pszInput, const char *pszEncoding = "UCS-2" );
-
-// Returns a wchar_t string which becomes the ownership responsibility of
-// the caller (free with CPLFree()).  It is assumed the CPLString is UTF-8. 
-wchar_t *CPLString::GetAsWChar( const char *pszDstEncoding = "UCS-2" );
+char *CPLRecodeFromWChar( const wchar_t *pwszSource, 
+                          const char *pszSrcEncoding, 
+                          const char *pszDstEncoding );
+wchar_t *CPLRecodeToWChar( const char *pszSource,
+                           const char *pszSrcEncoding, 
+                           const char *pszDstEncoding );
 }}}
 
-I have specifically avoided additional constructors or casting operators to 
-to avoid any possible overloading ambiguities or complication in maintaining
-extra state in the CPLString.  Such services can be added in the future based
-on the above methods if desired. 
+In each case the returned string is zero terminated, as is the input string, and the returned string should be deallocated with CPLFree().
+In case of error the returned string will be NULL, and the function will issue a CPLError().  The functions will be marked with CPL_DLL and considered part of the public GDAL/OGR API for use of applications as well as internal use. 
 
 == Encoding Names ==