setlocale, _wsetlocale

Nastavte nebo načtěte národní prostředí za běhu.

Syntaxe

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

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

Parametry

category
Kategorie ovlivněná národním prostředím

locale
Specifikátor národního prostředí

Vrácená hodnota

Jsou-li zadány platné locale a category jsou zadány, vrátí funkce ukazatel na řetězec přidružený k zadanému locale a category. locale Pokud je NULLargumentem, vrátí funkce aktuální národní prostředí.

Pokud je některý z funkcí předán neplatný argument, je vrácená hodnota NULL. Chování neplatných argumentů je následující:

Function	Neplatný parametr	Neplatná obslužná rutina vyvolaná podle popisu v ověření parametru	Nastavuje errno
setlocale	category	ano	ano
setlocale	locale	ne	ne
_wsetlocale	category	ano	ano
_wsetlocale	locale	ne	ne

Volání:

setlocale( LC_ALL, "en-US" );

nastaví všechny kategorie, aby vracely pouze řetězec

en-US

Řetězec vrácený obnovením setlocale této části informací o národním prostředí programu můžete zkopírovat. Pro řetězec vrácený řetězcem setlocalese používá globální místní úložiště nebo místní úložiště vlákna . Pozdější volání k setlocale přepsání řetězce, který zruší platnost ukazatelů řetězce vrácených dřívějšími voláními.

Poznámky

setlocale Pomocí funkce můžete nastavit, změnit nebo dotazovat některé nebo všechny informace o národním prostředí aktuálního programu určené locale a category. locale označuje lokalitu (zemi/oblast a jazyk), pro kterou můžete přizpůsobit určité aspekty programu. Ke kategoriím závislým na národním prostředí patří formátování dat nebo zobrazovací formát pro peněžní hodnoty. Pokud jste nastavili locale výchozí řetězec pro jazyk, který má v počítači podporovaných více formulářů, měli byste zkontrolovat setlocale návratovou hodnotu a zjistit, který jazyk je v platnosti. Pokud například nastavíte locale "chinese" návratové hodnoty, může to být buď "chinese-simplified" nebo "chinese-traditional".

_wsetlocale je verze širokého znaku setlocale; locale argument a návratová _wsetlocale hodnota jsou řetězce širokých znaků. _wsetlocale a setlocale chovat se stejně jinak.

Ve výchozím nastavení je globální stav této funkce vymezen na aplikaci. Chcete-li toto chování změnit, přečtěte si téma Globální stav v CRT.

Mapování rutin obecného textu

TCHAR.H rutina	_UNICODE a _MBCS není definován	_MBCS definovaný	_UNICODE definovaný
_tsetlocale	setlocale	setlocale	_wsetlocale

Argument category určuje části informací národního prostředí programu, které jsou ovlivněny. Makra použitá pro category a části programu, které ovlivňují, jsou následující:

category vlajka	Ovlivňuje
LC_ALL	Všechny kategorie, jak je uvedeno níže.
LC_COLLATE	Funkce strcoll, , _stricoll, wcscoll, _wcsicoll, _strncollstrxfrm_wcsncoll_strnicoll, _wcsnicoll, a wcsxfrm funkce.
LC_CTYPE	Funkce zpracování znaků (s výjimkou isdigit, isxdigitmbstowcs, a mbtowc, které nejsou ovlivněny).
LC_MONETARY	Informace o peněžním formátování vrácené localeconv funkcí
LC_NUMERIC	Znak desetinné čárky pro formátované výstupní rutiny (například printf), pro rutiny převodu dat a informace o nemonetárním formátování vrácené localeconv. Kromě znaku LC_NUMERIC desetinné čárky nastaví oddělovač tisíců a seskupovací ovládací řetězec vrácený znakem localeconv.
LC_TIME	Funkce strftime a wcsftime funkce.

Tato funkce ověřuje parametr kategorie. Pokud parametr kategorie není jednou z hodnot uvedených v předchozí tabulce, vyvolá se neplatná obslužná rutina parametru, jak je popsáno v ověření parametru. Pokud je provádění povoleno pokračovat, funkce nastaví errno EINVAL a vrátí NULL.

Argument locale je ukazatel na řetězec, který určuje národní prostředí. Informace o formátu argumentu locale naleznete v tématu Názvy národních prostředí, Jazyky a Řetězce země/oblasti. Pokud locale odkazuje na prázdný řetězec, národní prostředí je nativní prostředí definované implementací. Hodnota C určuje minimální prostředí odpovídající ANSI pro překlad jazyka C. Národní C prostředí předpokládá, že všechny char datové typy jsou 1 bajt a že jejich hodnota je vždy menší než 256.

Při spuštění programu se spustí ekvivalent následujícího příkazu:

setlocale( LC_ALL, "C" );

Argument locale může mít název národního prostředí, řetězec jazyka, řetězec jazyka a kód země/oblasti, znakovou stránku nebo řetězec jazyka, kód země/oblasti a znakovou stránku. Dostupné názvy národních prostředí, jazyky, kódy zemí/oblastí a kódové stránky zahrnují všechny jazyky podporované rozhraním API služby Windows NLS. Sada názvů národních prostředí podporovaných jazykem setlocale je popsaná v názvech národního prostředí, jazycích a řetězcích země/oblasti. Sada řetězců jazyka a země/oblasti, které setlocale jsou podporovány, jsou uvedeny v řetězcích jazyků a řetězců země/oblasti. Doporučujeme, abyste s ohledem na výkon a údržbu řetězců národního prostředí formu národního prostředí integrovali do kódu nebo serializovali do úložiště. U řetězců názvu národního prostředí je méně pravděpodobné, že aktualizací operačního systému dojde k jejich změně, než v případě formy pro název jazyka a země či oblasti.

Ukazatel null, který se předává jako locale argument, říká setlocale dotaz místo nastavení mezinárodního prostředí. locale Pokud je argument ukazatelem null, aktuální nastavení národního prostředí programu se nezmění. setlocale Místo toho vrátí ukazatel na řetězec přidružený k aktuálnímu národnímu category prostředí vlákna. category Pokud argument je LC_ALL, vrátí funkce řetězec, který označuje aktuální nastavení každé kategorie oddělené středníky. Například sekvence volání

// Set all categories and return "en-US"
setlocale(LC_ALL, "en-US");
// Set only the LC_MONETARY category and return "fr-FR"
setlocale(LC_MONETARY, "fr-FR");
printf("%s\n", setlocale(LC_ALL, NULL));

vrací

LC_COLLATE=en-US;LC_CTYPE=en-US;LC_MONETARY=fr-FR;LC_NUMERIC=en-US;LC_TIME=en-US

což je řetězec, který je přidružený k LC_ALL kategorii.

Následující příklady se týkají LC_ALL kategorie. Jeden z řetězců ". OCP a ". Akt" lze použít místo čísla znakové stránky k určení použití výchozí znakové stránky OEM a výchozí znakové stránky ANSI pro daný název národního prostředí.

• setlocale( LC_ALL, "" );

  Nastaví národní prostředí na výchozí hodnotu, což je výchozí znaková stránka ANSI pro uživatele získaná z operačního systému. Název národního prostředí je nastaven na hodnotu vrácenou GetUserDefaultLocaleNamehodnotou . Znaková stránka je nastavena na hodnotu vrácenou znakem GetACP.

• setlocale( LC_ALL, ".OCP" );

  Nastaví národní prostředí na aktuální znakovou stránku OEM získanou z operačního systému. Název národního prostředí je nastaven na hodnotu vrácenou GetUserDefaultLocaleNamehodnotou . Znaková stránka je nastavena na LOCALE_IDEFAULTCODEPAGE hodnotu výchozího názvu národního prostředí uživatelem .GetLocaleInfoEx

• setlocale( LC_ALL, ".ACP" );

  Nastaví národní prostředí na znakovou stránku ANSI získanou z operačního systému. Název národního prostředí je nastaven na hodnotu vrácenou GetUserDefaultLocaleNamehodnotou . Znaková stránka je nastavena na LOCALE_IDEFAULTANSICODEPAGE hodnotu výchozího názvu národního prostředí uživatelem .GetLocaleInfoEx

• setlocale( LC_ALL, "<localename>" );

  Nastaví národní prostředí na název národního prostředí, který je označený <localename>. Znaková stránka je nastavena na LOCALE_IDEFAULTANSICODEPAGE hodnotu pro zadaný název národního prostředí podle GetLocaleInfoEx.

• setlocale( LC_ALL, "<language>_<country>" );

  Nastaví národní prostředí na jazyk a zemi/oblast označenou <language> a <country>společně s výchozí znakovou stránkou získanou z hostitelského operačního systému. Znaková stránka je nastavena na LOCALE_IDEFAULTANSICODEPAGE hodnotu pro zadaný název národního prostředí podle GetLocaleInfoEx.

• setlocale( LC_ALL, "<language>_<country>.<code_page>" );

  Nastaví národní prostředí na jazyk, zemi/oblast a znakovou stránku označenou znakem <language>, <country>a <code_page> řetězce. Můžete použít různé kombinace jazyka, země/oblasti a znakové stránky. Například toto volání nastaví národní prostředí na hodnotu francouzština, Kanada se znakovou stránkou 1252:

  setlocale( LC_ALL, "French_Canada.1252" );

  Toto volání nastaví národní prostředí na hodnotu francouzština, Kanada s výchozí znakovou stránkou ANSI:

  setlocale( LC_ALL, "French_Canada.ACP" );

  Toto volání nastaví národní prostředí na hodnotu francouzština, Kanada s výchozí znakovou stránkou OEM:

  setlocale( LC_ALL, "French_Canada.OCP" );

• setlocale( LC_ALL, "<language>" );

  Nastaví národní prostředí na jazyk, který je označený <language>, a používá výchozí zemi/oblast pro zadaný jazyk a výchozí znakovou stránku ANSI pro danou zemi nebo oblast, jak je získáno z hostitelského operačního systému. Například následující volání setlocale jsou funkčně ekvivalentní:

  setlocale( LC_ALL, "en-US" );

  setlocale( LC_ALL, "English" );

  setlocale( LC_ALL, "English_United States.1252" );

  S ohledem na výkon a údržbu doporučujeme použít první z uvedených forem.

• setlocale( LC_ALL, ".<code_page>" );

  Nastaví znakovou stránku na hodnotu určenou znakem <code_page>, společně s výchozí zemí/oblastí a jazykem (definovaným hostitelským operačním systémem) pro zadanou znakovou stránku.

Kategorie musí být buď nebo LC_ALL LC_CTYPE aby se projevila změna znakové stránky. Pokud jsou například výchozí země/oblast a jazyk hostitelského operačního systému "United States" a "English", jsou následující dvě volání setlocale funkčně ekvivalentní:

setlocale( LC_ALL, ".1252" );

setlocale( LC_ALL, "English_United States.1252");

Další informace naleznete v direktivě direktivy setlocale pragma v referenčních informacích preprocesoru C/C++.

Funkce _configthreadlocale slouží k řízení, zda setlocale ovlivňuje národní prostředí všech vláken v programu nebo pouze národní prostředí volajícího vlákna.

Podpora UTF-8

Počínaje Windows 10 verze 1803 (10.0.17134.0) podporuje Univerzální modul C Runtime použití znakové stránky UTF-8. Změna znamená, že char řetězce předané funkcím modulu runtime jazyka C mohou očekávat řetězce v kódování UTF-8. Chcete-li povolit režim UTF-8, použijte ".UTF8" jako znakovou stránku při použití setlocale. setlocale(LC_ALL, ".UTF8") Například používá aktuální výchozí znakovou stránku SYSTÉMU Windows ANSI (ACP) pro národní prostředí a UTF-8 pro znakovou stránku.

Řetězec pro určení režimu UTF-8 je:

• Nerozlišuje velká a malá písmena
• pomlčka (-) je volitelná.
• Musí být v části názvu národního prostředí v části znakové stránky, takže musí mít úvodní tečku (.) jako v těchto příkladech: "en_US.UTF8" nebo ".utf8"

Následující příklady ukazují, jak zadat řetězec UTF-8:

".UTF8"
".UTF-8"
".utf8"
".utf-8"
"en_us.utf8"
"ja_JP.Utf-8"

Po volání setlocale(LC_ALL, ".UTF8")můžete předat "😊" mbtowcs a bude správně přeložen na wchar_t řetězec. Dříve nebylo k dispozici nastavení národního prostředí pro tento překlad.

Režim UTF-8 je také povolený pro funkce, které mají historicky přeložené char řetězce pomocí výchozí znakové stránky WINDOWS ANSI (ACP). Například volání _mkdir("😊") při použití znakové stránky UTF-8 správně vytvoří adresář s tímto emoji jako název složky, místo aby bylo nutné změnit AKT na UTF-8 před spuštěním programu. Podobně volání _getcwd() v této složce vrátí řetězec s kódováním UTF-8. Kvůli kompatibilitě se stále používá, pokud není znaková stránka národního prostředí C nastavená na UTF-8.

Následující aspekty modulu runtime jazyka C nemůžou používat UTF-8, protože jsou nastavené během spouštění programu a musí používat výchozí znakovou stránku SYSTÉMU Windows ANSI (ACP): __argv, _acmdlna _pgmptr.

Předchozí k této podpoře , , c16rtombmbrtoc32mbrtoc16, a c32rtomb existovaly k překladu mezi UTF-8 úzké řetězce, UTF-16 (stejné kódování jako wchar_t na platformě Windows) a UTF-32. Z důvodů kompatibility se tato rozhraní API stále překládají pouze do A z UTF-8 a ne z znakové stránky nastavené prostřednictvím setlocale.

Pokud chcete tuto funkci použít v operačním systému před Windows 10, musíte použít místní nasazení aplikace nebo propojit staticky pomocí verze 1803 (10.0.17134.0) sady Windows SDK nebo novější. Pro operační systémy Windows 10 starší než 1803 (10.0.17134.0) se podporuje pouze statické propojení.

Požadavky

Rutina	Požadovaný hlavičkový soubor
setlocale	<locale.h>
_wsetlocale	<locale.h> nebo <wchar.h>

Další informace o kompatibilitě najdete v tématu Kompatibilita.

Příklad

// crt_setlocale.c
//
// This program demonstrates the use of setlocale when
// using two independent threads.
//

#include <locale.h>
#include <process.h>
#include <windows.h>
#include <stdio.h>
#include <time.h>

#define BUFF_SIZE 100

// Retrieve the date in the current
// locale's format.
int get_date(unsigned char* str)
{
    __time64_t ltime;
    struct tm  thetime;

    // Retrieve the current time
    _time64(&ltime);
    _gmtime64_s(&thetime, &ltime);

    // Format the current time structure into a string
    // "%#x" is the long date representation in the
    // current locale
    if (!strftime((char *)str, BUFF_SIZE, "%#x",
                  (const struct tm *)&thetime))
    {
        printf("strftime failed!\n");
        return -1;
    }
    return 0;
}

// This thread sets its locale to the argument and prints the date.
unsigned __stdcall SecondThreadFunc(void* pArguments)
{
    unsigned char str[BUFF_SIZE];
    char * locale = (char *)pArguments;

    // Set the thread locale
    printf("The thread locale is now set to %s.\n",
           setlocale(LC_ALL, locale));

    // Retrieve the date string from the helper function
    if (get_date(str) == 0)
    {
        printf("The date in %s locale is: '%s'\n", locale, str);
    }

    _endthreadex( 0 );
    return 0;
}

// The main thread sets the locale to English
// and then spawns a second thread (above) and prints the date.
int main()
{
    HANDLE          hThread;
    unsigned        threadID;
    unsigned char   str[BUFF_SIZE];

    // Enable per-thread locale causes all subsequent locale
    // setting changes in this thread to only affect this thread.
    _configthreadlocale(_ENABLE_PER_THREAD_LOCALE);

    // Set the locale of the main thread to US English.
    printf("The thread locale is now set to %s.\n",
           setlocale(LC_ALL, "en-US"));

    // Create the second thread with a German locale.
    // Our thread function takes an argument of the locale to use.
    hThread = (HANDLE)_beginthreadex( NULL, 0, &SecondThreadFunc,
                                      (void*)"de-DE", 0, &threadID );

    if (get_date(str) == 0)
    {
        // Retrieve the date string from the helper function
        printf("The date in en-US locale is: '%s'\n\n", str);
    }

    // Wait for the created thread to finish.
    WaitForSingleObject( hThread, INFINITE );

    // Destroy the thread object.
    CloseHandle( hThread );
}

The thread locale is now set to en-US.
The date in en-US locale is: 'Thursday, January 4, 2024'

The thread locale is now set to de-DE.
The date in de-DE locale is: 'Donnerstag, 4. Januar 2024'

Viz také

Názvy národních prostředí, jazyky a řetězce země/oblasti
_configthreadlocale
_create_locale, _wcreate_locale
Národní prostředí
localeconv
_mbclen, , mblen_mblen_l
strlen, wcslen, _mbslen, _mbslen_l, , _mbstrlen_mbstrlen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
_setmbcp
strcoll – funkce
strftime, wcsftime, , _strftime_l_wcsftime_l
strxfrm, wcsxfrm, , _strxfrm_l_wcsxfrm_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l