Add C comments for recent to_char('L') fix for Win32.

diff --git a/src/backend/utils/adt/pg_locale.c b/src/backend/utils/adt/pg_locale.c
index 171431fbd4453f4a482f482fefb1d143e12ae6e1..33297accab67597b8b108cba264ffc5df9f366f4 100644 (file)
--- a/src/backend/utils/adt/pg_locale.c
+++ b/src/backend/utils/adt/pg_locale.c
@@ -4,7 +4,7 @@
  *
  * Portions Copyright (c) 2002-2010, PostgreSQL Global Development Group
  *
- * $PostgreSQL: pgsql/src/backend/utils/adt/pg_locale.c,v 1.54 2010/04/22 01:55:52 itagaki Exp $
+ * $PostgreSQL: pgsql/src/backend/utils/adt/pg_locale.c,v 1.55 2010/04/24 22:54:56 momjian Exp $
  *
  *-----------------------------------------------------------------------
  */
@@ -41,6 +41,10 @@
  * DOES NOT WORK RELIABLY: on some platforms the second setlocale() call
  * will change the memory save is pointing at. To do this sort of thing
  * safely, you *must* pstrdup what setlocale returns the first time.
+ *
+ * FYI, The Open Group locale standard is defined here:
+ *
+ *  http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap07.html
  *----------
  */
 
@@ -424,7 +428,6 @@ PGLC_localeconv(void)
        char       *grouping;
        char       *thousands_sep;
        int                     encoding;
-
 #ifdef WIN32
        char       *save_lc_ctype;
 #endif
@@ -435,25 +438,48 @@ PGLC_localeconv(void)
 
        free_struct_lconv(&CurrentLocaleConv);
 
-       /* Set user's values of monetary and numeric locales */
+       /* Save user's values of monetary and numeric locales */
        save_lc_monetary = setlocale(LC_MONETARY, NULL);
        if (save_lc_monetary)
                save_lc_monetary = pstrdup(save_lc_monetary);
+
        save_lc_numeric = setlocale(LC_NUMERIC, NULL);
        if (save_lc_numeric)
                save_lc_numeric = pstrdup(save_lc_numeric);
 
 #ifdef WIN32
-       /* set user's value of ctype locale */
+   /*
+       *  Ideally, monetary and numeric local symbols could be returned in
+       *  any server encoding.  Unfortunately, the WIN32 API does not allow
+       *  setlocale() to return values in a codepage/CTYPE that uses more
+       *  than two bytes per character, like UTF-8:
+       *
+       *      http://msdn.microsoft.com/en-us/library/x99tb11d.aspx
+       *
+       *  Evidently, LC_CTYPE allows us to control the encoding used
+       *  for strings returned by localeconv().  The Open Group
+       *  standard, mentioned at the top of this C file, doesn't
+       *  explicitly state this.
+       *
+       *  Therefore, we set LC_CTYPE to match LC_NUMERIC or LC_MONETARY
+       *  (which cannot be UTF8), call localeconv(), and then convert from
+       *  the numeric/monitary LC_CTYPE to the server encoding.  One
+       *  example use of this is for the Euro symbol.
+       *
+       *  Perhaps someday we will use GetLocaleInfoW() which returns values
+       *  in UTF16 and convert from that.
+       */
+
+       /* save user's value of ctype locale */
        save_lc_ctype = setlocale(LC_CTYPE, NULL);
        if (save_lc_ctype)
                save_lc_ctype = pstrdup(save_lc_ctype);
-#endif
 
-       /* Get formatting information for numeric */
-#ifdef WIN32
+       /* use numeric to set the ctype */
        setlocale(LC_CTYPE, locale_numeric);
 #endif
+
+       /* Get formatting information for numeric */
        setlocale(LC_NUMERIC, locale_numeric);
        extlconv = localeconv();
        encoding = pg_get_encoding_from_locale(locale_numeric);
@@ -462,10 +488,12 @@ PGLC_localeconv(void)
        thousands_sep = db_encoding_strdup(encoding, extlconv->thousands_sep);
        grouping = strdup(extlconv->grouping);
 
-       /* Get formatting information for monetary */
 #ifdef WIN32
+       /* use monetary to set the ctype */
        setlocale(LC_CTYPE, locale_monetary);
 #endif
+
+       /* Get formatting information for monetary */
        setlocale(LC_MONETARY, locale_monetary);
        extlconv = localeconv();
        encoding = pg_get_encoding_from_locale(locale_monetary);
@@ -500,7 +528,7 @@ PGLC_localeconv(void)
        }
 
 #ifdef WIN32
-       /* try to restore internal ctype settings */
+       /* Try to restore internal ctype settings */
        if (save_lc_ctype)
        {
                setlocale(LC_CTYPE, save_lc_ctype);
@@ -514,13 +542,15 @@ PGLC_localeconv(void)
 
 #ifdef WIN32
 /*
- * On win32, strftime() returns the encoding in CP_ACP, which is likely
- * different from SERVER_ENCODING. This is especially important in Japanese
- * versions of Windows which will use SJIS encoding, which we don't support
- * as a server encoding.
+ * On WIN32, strftime() returns the encoding in CP_ACP (the default
+ * operating system codpage for that computer), which is likely different
+ * from SERVER_ENCODING.  This is especially important in Japanese versions
+ * of Windows which will use SJIS encoding, which we don't support as a
+ * server encoding.
  *
- * Replace strftime() with a version that gets the string in UTF16 and then
- * converts it to the appropriate encoding as necessary.
+ * So, instead of using strftime(), use wcsftime() to return the value in
+ * wide characters (internally UTF16) and then convert it to the appropriate
+ * database encoding.
  *
  * Note that this only affects the calls to strftime() in this file, which are
  * used to get the locale-aware strings. Other parts of the backend use
@@ -537,7 +567,6 @@ strftime_win32(char *dst, size_t dstlen, const wchar_t *format, const struct tm
 
        len = wcsftime(wbuf, MAX_L10N_DATA, format, tm);
        if (len == 0)
-
                /*
                 * strftime call failed - return 0 with the contents of dst
                 * unspecified
@@ -564,7 +593,9 @@ strftime_win32(char *dst, size_t dstlen, const wchar_t *format, const struct tm
        return len;
 }
 
+/* redefine strftime() */
 #define strftime(a,b,c,d) strftime_win32(a,b,L##c,d)
+
 #endif   /* WIN32 */
 
 
@@ -580,7 +611,6 @@ cache_locale_time(void)
        char            buf[MAX_L10N_DATA];
        char       *ptr;
        int                     i;
-
 #ifdef WIN32
        char       *save_lc_ctype;
 #endif
@@ -591,20 +621,22 @@ cache_locale_time(void)
 
        elog(DEBUG3, "cache_locale_time() executed; locale: \"%s\"", locale_time);
 
+       /* save user's value of time locale */
+       save_lc_time = setlocale(LC_TIME, NULL);
+       if (save_lc_time)
+               save_lc_time = pstrdup(save_lc_time);
+
 #ifdef WIN32
-       /* set user's value of ctype locale */
+       /* See the WIN32 comment near the top of PGLC_localeconv() */
+       /* save user's value of ctype locale */
        save_lc_ctype = setlocale(LC_CTYPE, NULL);
        if (save_lc_ctype)
                save_lc_ctype = pstrdup(save_lc_ctype);
 
+       /* use lc_time to set the ctype */
        setlocale(LC_CTYPE, locale_time);
 #endif
 
-       /* set user's value of time locale */
-       save_lc_time = setlocale(LC_TIME, NULL);
-       if (save_lc_time)
-               save_lc_time = pstrdup(save_lc_time);
-
        setlocale(LC_TIME, locale_time);
 
        timenow = time(NULL);