Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/locale/setlocale"

From cppreference.com
< cpp‎ | locale
m (utf-8 encoding)
m (→‎External links: +)
 
(4 intermediate revisions by one user not shown)
Line 1: Line 1:
 
{{cpp/title|setlocale}}
 
{{cpp/title|setlocale}}
 
{{cpp/locale/navbar}}
 
{{cpp/locale/navbar}}
−
{{dcl begin}}
+
{{ddcl|header=clocale|
−
{{dcl header|clocale}}
+
char* setlocale( int category, const char* locale );
−
{{dcl |
+
−
char* setlocale( int category, const char* locale);
+
 
}}
 
}}
−
{{dcl end}}
 
  
 
The {{tt|setlocale}} function installs the specified system locale or its portion as the new C locale. The modifications remain in effect and influences the execution of all locale-sensitive C library functions until the next call to {{tt|setlocale}}. If {{tt|locale}} is a null pointer, {{tt|setlocale}} queries the current C locale without modifying it.
 
The {{tt|setlocale}} function installs the specified system locale or its portion as the new C locale. The modifications remain in effect and influences the execution of all locale-sensitive C library functions until the next call to {{tt|setlocale}}. If {{tt|locale}} is a null pointer, {{tt|setlocale}} queries the current C locale without modifying it.
Line 12: Line 9:
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | category | locale category identifier, one of the {{rlp|LC_categories|LC_xxx}} macros. May be 0.}}
+
{{par|category|locale category identifier, one of the {{rlpt|LC_categories|LC_xxx}} macros. May be {{c|0}}.}}
−
{{par | locale | system-specific locale identifier. Can be {{c|""}} for the user-preferred locale or {{c|"C"}} for the minimal locale }}
+
{{par|locale|system-specific locale identifier. Can be {{c|""}} for the user-preferred locale or {{c|"C"}} for the minimal locale }}
 
{{par end}}
 
{{par end}}
  
Line 26: Line 23:
 
Although the return type is {{c|char*}}, modifying the pointed-to characters is undefined behavior.
 
Although the return type is {{c|char*}}, modifying the pointed-to characters is undefined behavior.
  
−
Because {{tt|setlocale}} modifies global state which affects execution of locale-dependent functions, it is undefined behavior to call it from one thread, while another thread is executing any of the following functions: {{lc|std::fprintf}}, {{lc|std::isprint}}, {{lc|std::iswdigit}}, {{lc|std::localeconv}}, {{lc|std::tolower}}, {{lc|std::fscanf}}, {{lc|std::ispunct}}, {{lc|std::iswgraph}}, {{lc|std::mblen}}, {{lc|std::toupper}}, {{lc|std::isalnum}}, {{lc|std::isspace}}, {{lc|std::iswlower}}, {{lc|std::mbstowcs}}, {{lc|std::towlower}}, {{lc|std::isalpha}}, {{lc|std::isupper}}, {{lc|std::iswprint}}, {{lc|std::mbtowc}}, {{lc|std::towupper}}, {{lc|std::isblank}}, {{lc|std::iswalnum}}, {{lc|std::iswpunct}}, {{lc|std::setlocale}}, {{lc|std::wcscoll}}, {{lc|std::iscntrl}}, {{lc|std::iswalpha}}, {{lc|std::iswspace}}, {{lc|std::strcoll}}, {{lc|std::wcstod}}, {{lc|std::isdigit}}, {{lc|std::iswblank}}, {{lc|std::iswupper}}, {{lc|std::strerror}}, {{lc|std::wcstombs}}, {{lc|std::isgraph}}, {{lc|std::iswcntrl}}, {{lc|std::iswxdigit}}, {{lc|std::strtod}}, {{lc|std::wcsxfrm}}, {{lc|std::islower}}, {{lc|std::iswctype}}, {{lc|std::isxdigit}}.
+
Because {{tt|setlocale}} modifies global state which affects execution of locale-dependent functions, it is undefined behavior to call it from one thread, while another thread is executing any of the following functions: {{lc|std::fprintf}}, {{lc|std::isprint}}, {{lc|std::iswdigit}}, {{lc|std::localeconv}}, {{lc|std::tolower}}, {{lc|std::fscanf}}, {{lc|std::ispunct}}, {{lc|std::iswgraph}}, {{lc|std::mblen}}, {{lc|std::toupper}}, {{lc|std::isalnum}}, {{lc|std::isspace}}, {{lc|std::iswlower}}, {{lc|std::mbstowcs}}, {{lc|std::towlower}}, {{lc|std::isalpha}}, {{lc|std::isupper}}, {{lc|std::iswprint}}, {{lc|std::mbtowc}}, {{lc|std::towupper}}, {{lc|std::isblank}}, {{lc|std::iswalnum}}, {{lc|std::iswpunct}}, {{tt|std::setlocale}}, {{lc|std::wcscoll}}, {{lc|std::iscntrl}}, {{lc|std::iswalpha}}, {{lc|std::iswspace}}, {{lc|std::strcoll}}, {{lc|std::wcstod}}, {{lc|std::isdigit}}, {{lc|std::iswblank}}, {{lc|std::iswupper}}, {{lc|std::strerror}}, {{lc|std::wcstombs}}, {{lc|std::isgraph}}, {{lc|std::iswcntrl}}, {{lc|std::iswxdigit}}, {{lc|std::strtod}}, {{lc|std::wcsxfrm}}, {{lc|std::islower}}, {{lc|std::iswctype}}, {{lc|std::isxdigit}}.
  
−
POSIX also defines a locale named "POSIX", which is always accessible and is exactly equivalent to the default minimal "C" locale.  
+
POSIX also defines a locale named {{c|"POSIX"}}, which is always accessible and is exactly equivalent to the default minimal {{c|"C"}} locale.
  
−
POSIX also specifies that the returned pointer, not just the contents of the pointed-to string, may be invalidated by subsequent calls to setlocale.
+
POSIX also specifies that the returned pointer, not just the contents of the pointed-to string, may be invalidated by subsequent calls to {{tt|setlocale}}.
  
 
===Example===
 
===Example===
 
{{example
 
{{example
−
|
+
|code=
−
| code=
+
−
#include <cstdio>
+
 
#include <clocale>
 
#include <clocale>
 +
#include <cstdio>
 
#include <ctime>
 
#include <ctime>
 
#include <cwchar>
 
#include <cwchar>
 +
#include <iterator>
 +
#include <string>
  
 
int main()
 
int main()
 
{
 
{
−
     // the C locale will be UTF-8 enabled English;
+
     // Make a "deep copy" of current locale name.
−
    // decimal dot will be German
+
     std::string prev_loc = std::setlocale(LC_ALL, nullptr);
−
    // date and time formatting will be Japanese
+
−
    std::setlocale(LC_ALL, "en_US.UTF-8");
+
−
     std::setlocale(LC_NUMERIC, "de_DE.UTF-8");
+
−
    std::setlocale(LC_TIME, "ja_JP.UTF-8");
+
  
−
     wchar_t str[100];
+
    // The C locale will be UTF-8 enabled English,
−
     std::time_t t = std::time(NULL);
+
    // decimal dot will be German,
−
     std::wcsftime(str, 100, L"%A %c", std::localtime(&t));
+
    // date and time formatting will be Japanese.
−
     std::wprintf(L"Number: %.2f\nDate: %Ls\n", 3.14, str);
+
    if (const char* loc = std::setlocale(LC_ALL, "en_US.UTF-8"))
 +
        std::wprintf(L"New LC_ALL locale: %s\n", loc);
 +
    if (const char* loc = std::setlocale(LC_NUMERIC, "de_DE.UTF-8"))
 +
        std::wprintf(L"New LC_NUMERIC locale: %s\n", loc);
 +
    if (const char* loc = std::setlocale(LC_TIME, "ja_JP.UTF-8"))
 +
        std::wprintf(L"New LC_TIME locale: %s\n", loc);
 +
 
 +
     wchar_t buf[100];
 +
     std::time_t t = std::time(nullptr);
 +
     std::wcsftime(buf, std::size(buf), L"%A %c", std::localtime(&t));
 +
     std::wprintf(L"Number: %.2f\nDate: %Ls\n", 3.14, buf);
 +
 
 +
    // Restore the previous locale.
 +
    if (const char* loc = std::setlocale(LC_ALL, prev_loc.c_str()))
 +
        std::wprintf(L"Restorred LC_ALL locale: %s\n", loc);
 
}
 
}
−
| output=
+
|p=true
 +
|output=
 +
New LC_ALL locale: en_US.UTF-8
 +
New LC_NUMERIC locale: de_DE.UTF-8
 +
New LC_TIME locale: ja_JP.UTF-8
 
Number: 3,14
 
Number: 3,14
−
Date: 月曜日 2011年12月19日 18時04分40秒
+
Date: 日曜日 2022年11月06日 20時40分59秒
 +
Restorred LC_ALL locale: C
 
}}
 
}}
  
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/locale/dsc LC_categories}}
+
{{dsc inc|cpp/locale/dsc LC_categories}}
−
{{dsc inc | cpp/locale/dsc locale}}
+
{{dsc inc|cpp/locale/dsc locale}}
−
{{dsc see c | c/locale/setlocale}}
+
{{dsc see c|c/locale/setlocale}}
 
{{dsc end}}
 
{{dsc end}}
  
−
[[de:cpp/locale/setlocale]]
+
===External links===
−
[[es:cpp/locale/setlocale]]
+
{{elink begin}}
−
[[fr:cpp/locale/setlocale]]
+
{{elink|num=1|1=[https://ss64.com/locale.html List of Windows locale names].}}
−
[[it:cpp/locale/setlocale]]
+
{{elink|num=2|1=[https://lh.2xlibre.net/locales/ List of Linux locale names].}}
−
[[ja:cpp/locale/setlocale]]
+
{{elink end}}
−
[[pt:cpp/locale/setlocale]]
+
 
−
[[ru:cpp/locale/setlocale]]
+
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
−
[[zh:cpp/locale/setlocale]]
+

Latest revision as of 08:19, 3 May 2024

 
C++
 
Localization library
 
Defined in header <clocale>
char* setlocale( int category, const char* locale );

The setlocale function installs the specified system locale or its portion as the new C locale. The modifications remain in effect and influences the execution of all locale-sensitive C library functions until the next call to setlocale. If locale is a null pointer, setlocale queries the current C locale without modifying it.

Contents

[edit] Parameters

category - locale category identifier, one of the LC_xxx macros. May be ​0​.
locale - system-specific locale identifier. Can be "" for the user-preferred locale or "C" for the minimal locale

[edit] Return value

Pointer to a narrow null-terminated string identifying the C locale after applying the changes, if any, or null pointer on failure.

A copy of the returned string along with the category used in this call to std::setlocale may be used later in the program to restore the locale back to the state at the end of this call.

[edit] Notes

During program startup, the equivalent of std::setlocale(LC_ALL, "C"); is executed before any user code is run.

Although the return type is char*, modifying the pointed-to characters is undefined behavior.

Because setlocale modifies global state which affects execution of locale-dependent functions, it is undefined behavior to call it from one thread, while another thread is executing any of the following functions: std::fprintf, std::isprint, std::iswdigit, std::localeconv, std::tolower, std::fscanf, std::ispunct, std::iswgraph, std::mblen, std::toupper, std::isalnum, std::isspace, std::iswlower, std::mbstowcs, std::towlower, std::isalpha, std::isupper, std::iswprint, std::mbtowc, std::towupper, std::isblank, std::iswalnum, std::iswpunct, std::setlocale, std::wcscoll, std::iscntrl, std::iswalpha, std::iswspace, std::strcoll, std::wcstod, std::isdigit, std::iswblank, std::iswupper, std::strerror, std::wcstombs, std::isgraph, std::iswcntrl, std::iswxdigit, std::strtod, std::wcsxfrm, std::islower, std::iswctype, std::isxdigit.

POSIX also defines a locale named "POSIX", which is always accessible and is exactly equivalent to the default minimal "C" locale.

POSIX also specifies that the returned pointer, not just the contents of the pointed-to string, may be invalidated by subsequent calls to setlocale.

[edit] Example

Run this code
#include <clocale>
#include <cstdio>
#include <ctime>
#include <cwchar>
#include <iterator>
#include <string>
 
int main()
{
    // Make a "deep copy" of current locale name.
    std::string prev_loc = std::setlocale(LC_ALL, nullptr);
 
    // The C locale will be UTF-8 enabled English,
    // decimal dot will be German,
    // date and time formatting will be Japanese.
    if (const char* loc = std::setlocale(LC_ALL, "en_US.UTF-8"))
        std::wprintf(L"New LC_ALL locale: %s\n", loc);
    if (const char* loc = std::setlocale(LC_NUMERIC, "de_DE.UTF-8"))
        std::wprintf(L"New LC_NUMERIC locale: %s\n", loc);
    if (const char* loc = std::setlocale(LC_TIME, "ja_JP.UTF-8"))
        std::wprintf(L"New LC_TIME locale: %s\n", loc);
 
    wchar_t buf[100];
    std::time_t t = std::time(nullptr);
    std::wcsftime(buf, std::size(buf), L"%A %c", std::localtime(&t));
    std::wprintf(L"Number: %.2f\nDate: %Ls\n", 3.14, buf);
 
    // Restore the previous locale.
    if (const char* loc = std::setlocale(LC_ALL, prev_loc.c_str()))
        std::wprintf(L"Restorred LC_ALL locale: %s\n", loc);
}

Possible output: 

New LC_ALL locale: en_US.UTF-8
New LC_NUMERIC locale: de_DE.UTF-8
New LC_TIME locale: ja_JP.UTF-8
Number: 3,14
Date: 日曜日 2022年11月06日 20時40分59秒
Restorred LC_ALL locale: C

[edit] See also

 locale categories for std::setlocale
(macro constant) [edit]
set of polymorphic facets that encapsulate cultural differences
(class) [edit]
C documentation for setlocale

[edit] External links

1.  List of Windows locale names.
2.  List of Linux locale names.
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/locale/setlocale&oldid=171498"