Header File 

locale.h  

Category 

Miscellaneous Routines 

Prototype 

char *setlocale(int category, const char *locale); 

wchar_t * _wsetlocale( int category, const wchar_t *locale); 

Description 

Use the setlocale to select or query a locale. 

C++ Builder supports all locales supported in Win95/98/2000 operating systems. See your system documentation for details. 

The possible values for the category argument are as follows:

The locale argument is a pointer to the name of the locale or named locale category. Passing a NULL pointer returns the current locale in effect. Passing a pointer that points to a null string requests setlocale to look for environment variables to determine which locale to set. The locale names are not case sensitive. 

When setlocale is unable to honor a locale request, the preexisting locale in effect is unchanged and a null pointer is returned. 

If the locale argument is a NULL pointer, the locale string for the category is returned. If category is LC_ALL, a complete locale string is returned. The structure of the complete locale string consists of the names of all the categories in the current locale concatenated and separated by semicolons. This string can be used as the locale parameter when calling setlocale with any of the LC_xxx values. This will reinstate all the locale categories that are named in the complete locale string, and allows saving and restoring of locale states. If the complete locale string is used with a single category, for example, LC_TIME, only that category will be restored from the locale string. 

If an empty string "" is used as the locale parameter an implementation-defined locale is used. This is the ANSI C specified behavior. 

To take advantage of dynamically loadable locales in your application, define _ _USELOCALES_ _ for each module. If _ _USELOCALES_ _ is not defined, all locale-sensitive functions and macros will work only with the default C locale. 

If a NULL pointer is used as the argument for the locale parameter, setlocale returns a string that specifies the current locale in effect. If the category parameter specifies a single category, such as LC_COLLATE, the string pointed to will be the name of that category. If LC_ALL is used as the category parameter then the string pointed to will be a full locale string that will indicate the name of each category in effect. 

. 

. 

. 

localenameptr = setlocale( LC_COLLATE, NULL ); 

if (localenameptr) 

printf( "%s\n", localenameptr ); 

. 

. 

. 

The output here will be one of the module names together with the specified code page. For example, the output could be LC_COLLATE = English_United States.437. 

. 

. 

. 

localenameptr = setlocale( LC_ALL, NULL ); 

if (localenameptr) 

printf( "%s\n", localenameptr ); 

. 

. 

. 

An example of the output here could be the following: 

LC_COLLATE=English_United States.437; 

LC_TIME=English_United States.437; 

LC_CTYPE=English_United States.437; 

Each category in this full string is delimited by a semicolon. This string can be copied and saved by an application and then used again to restore the same locale categories at another time. Each delimited name corresponds to the locale category constants defined in locale.h. Therefore, the first name is the name of the LC_COLLATE category, the second is the LC_CTYPE category, and so on. Any other categories named in the locale.h header file are reserved for future implementation. 

To set all default categories for the specified French locale: 

setlocale( LC_ALL, "French_France.850" ); 

To find out which code page is currently being used: 

localenameptr = setlocale( LC_ALL, NULL ); 

Return value 

If selection is successful, setlocale returns a pointer to a string that is associated with the selected category (or possibly all categories) for the new locale. 

If UNICODE is defined, _wsetlocale returns a wchar_t string. 

On failure, a NULL pointer is returned and the locale is unchanged. All other possible returns are discussed in the Remarks section above. 

Example  

#include <locale.h>
#include <stdio.h>
int main(void)
{
   char *old_locale;
   /* The only locale supported in CodeGear C++ is "C" */
   old_locale = setlocale(LC_ALL,"C");
   printf("Old locale was %s\n",old_locale);
   return 0;
}

Portability