`setlocale`, `_wsetlocale`

Artikel
01/04/2024

Atur atau ambil lokal run-time.

Sintaks

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

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

Parameter

category
Kategori yang terpengaruh oleh lokal.

locale
Penentu lokal.

Nilai hasil

Jika valid locale dan category diberikan, fungsi mengembalikan penunjuk ke string yang terkait dengan yang ditentukan locale dan category. locale Jika argumen adalah NULL, fungsi mengembalikan lokal saat ini.

Jika argumen yang tidak valid diteruskan ke salah satu fungsi, nilai yang dikembalikan adalah NULL. Perilaku untuk argumen yang tidak valid adalah sebagai berikut:

Function	Parameter tidak valid	Handler tidak valid dipanggil seperti yang dijelaskan dalam Validasi parameter	Set `errno`
`setlocale`	`category`	yes	yes
`setlocale`	`locale`	no	no
`_wsetlocale`	`category`	yes	yes
`_wsetlocale`	`locale`	no	no

Panggilan:

setlocale( LC_ALL, "en-US" );

mengatur semua kategori, hanya mengembalikan string

en-US

Anda dapat menyalin string yang dikembalikan oleh setlocale untuk memulihkan bagian informasi lokal program tersebut. Penyimpanan lokal global atau utas digunakan untuk string yang dikembalikan oleh setlocale. Kemudian memanggil untuk setlocale menimpa string, yang membatalkan penunjuk string yang dikembalikan oleh panggilan sebelumnya.

Keterangan

setlocale Gunakan fungsi untuk mengatur, mengubah, atau mengkueri beberapa atau semua informasi lokal program saat ini yang ditentukan oleh locale dan category. locale mengacu pada lokalitas (negara/wilayah dan bahasa) yang dapat Anda sesuaikan aspek tertentu dari program Anda. Beberapa kategori yang bergantung pada lokal mencakup pemformatan tanggal dan format tampilan untuk nilai moneter. Jika Anda mengatur locale ke string default untuk bahasa yang memiliki beberapa formulir yang didukung di komputer Anda, Anda harus memeriksa setlocale nilai pengembalian untuk melihat bahasa mana yang berlaku. Misalnya, jika Anda mengatur locale ke "chinese" nilai yang dikembalikan bisa berupa "chinese-simplified" atau "chinese-traditional".

_wsetlocale adalah versi karakter yang luas dari setlocale; locale argumen dan nilai yang dikembalikan adalah _wsetlocale string karakter lebar. _wsetlocale dan setlocale berulah secara identik jika tidak.

Secara default, status global fungsi ini dicakup ke aplikasi. Untuk mengubah perilaku ini, lihat Status global di CRT.

Pemetaan rutin teks generik

`TCHAR.H` Rutin	`_UNICODE` dan `_MBCS` tidak ditentukan	`_MBCS` Didefinisikan	`_UNICODE` Didefinisikan
`_tsetlocale`	`setlocale`	`setlocale`	`_wsetlocale`

Argumen category menentukan bagian informasi lokal program yang terpengaruh. Makro yang digunakan untuk category dan bagian program yang mereka pengaruhi adalah sebagai berikut:

`category` Bendera	Mempengaruhi
`LC_ALL`	Semua kategori, seperti yang tercantum di bawah ini.
`LC_COLLATE`	Fungsi `strcoll`, , `wcscoll_stricoll`, `_wcsicoll`, `strxfrm_strncoll`, `_strnicoll`, , `_wcsncoll`, `_wcsnicoll`, dan `wcsxfrm` .
`LC_CTYPE`	Fungsi penanganan karakter (kecuali `isdigit`, , `isxdigit`, `mbstowcs`dan `mbtowc`, yang tidak terpengaruh).
`LC_MONETARY`	Informasi pemformatan moneter yang dikembalikan oleh `localeconv` fungsi .
`LC_NUMERIC`	Karakter titik desimal untuk rutinitas output yang diformat (seperti `printf`), untuk rutinitas konversi data, dan untuk informasi pemformatan nonmonetary yang dikembalikan oleh `localeconv`. Selain karakter titik desimal, `LC_NUMERIC` mengatur pemisah ribuan dan string kontrol pengelompokan yang dikembalikan oleh `localeconv`.
`LC_TIME`	Fungsi `strftime` dan `wcsftime` .

Fungsi ini memvalidasi parameter kategori. Jika parameter kategori bukan salah satu nilai yang diberikan dalam tabel sebelumnya, handler parameter yang tidak valid dipanggil, seperti yang dijelaskan dalam Validasi parameter. Jika eksekusi diizinkan untuk melanjutkan, fungsi diatur errno ke EINVAL dan mengembalikan NULL.

Argumen locale adalah penunjuk ke string yang menentukan lokal. Untuk informasi tentang format locale argumen, lihat Nama lokal, Bahasa, dan string Negara/Wilayah. Jika locale menunjuk ke string kosong, lokal adalah lingkungan asli yang ditentukan implementasi. Nilai C menentukan lingkungan yang sesuai dengan ANSI minimal untuk terjemahan C. Lokal C mengasumsikan bahwa semua char jenis data adalah 1 byte dan bahwa nilainya selalu kurang dari 256.

Pada startup program, setara dengan pernyataan berikut dijalankan:

setlocale( LC_ALL, "C" );

Argumen locale dapat mengambil nama lokal, string bahasa, string bahasa dan kode negara/wilayah, halaman kode, atau string bahasa, kode negara/wilayah, dan halaman kode. Nama lokal, bahasa, kode negara/wilayah, dan halaman kode yang tersedia mencakup semua yang didukung oleh Windows NLS API. Kumpulan nama lokal yang didukung oleh setlocale dijelaskan dalam string Nama lokal, Bahasa, dan Negara/Wilayah. Kumpulan string bahasa dan negara/wilayah yang didukung oleh setlocale tercantum dalam String bahasa dan string Negara/Wilayah. Kami merekomendasikan formulir nama lokal untuk performa dan untuk pemeliharaan string lokal yang disematkan dalam kode atau diserialisasikan ke penyimpanan. String nama lokal cenderung tidak diubah oleh pembaruan sistem operasi daripada bahasa dan formulir nama negara/wilayah.

Pointer null yang diteruskan sebagai locale argumen memberi tahu setlocale untuk mengkueri alih-alih mengatur lingkungan internasional. locale Jika argumen adalah penunjuk null, pengaturan lokal program saat ini tidak diubah. Sebagai gantinya, setlocale mengembalikan penunjuk ke string yang terkait dengan category lokal utas saat ini. category Jika argumen adalah LC_ALL, fungsi mengembalikan string yang menunjukkan pengaturan saat ini dari setiap kategori, dipisahkan oleh titik koma. Misalnya, urutan panggilan

// 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));

pengembalian

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

yang merupakan string yang terkait dengan LC_ALL kategori.

Contoh berikut berkaitan dengan LC_ALL kategori. Salah satu string ". OCP" dan ". ACP" dapat digunakan alih-alih nomor halaman kode untuk menentukan penggunaan halaman kode OEM default pengguna dan halaman kode ANSI default pengguna untuk nama lokal tersebut.

setlocale( LC_ALL, "" );

Mengatur lokal ke default, yang merupakan halaman kode ANSI default pengguna yang diperoleh dari sistem operasi. Nama lokal diatur ke nilai yang dikembalikan oleh GetUserDefaultLocaleName. Halaman kode diatur ke nilai yang dikembalikan oleh GetACP.
setlocale( LC_ALL, ".OCP" );

Mengatur lokal ke halaman kode OEM saat ini yang diperoleh dari sistem operasi. Nama lokal diatur ke nilai yang dikembalikan oleh GetUserDefaultLocaleName. Halaman kode diatur ke LOCALE_IDEFAULTCODEPAGE nilai untuk nama lokal default pengguna dengan GetLocaleInfoEx.
setlocale( LC_ALL, ".ACP" );

Mengatur lokal ke halaman kode ANSI yang diperoleh dari sistem operasi. Nama lokal diatur ke nilai yang dikembalikan oleh GetUserDefaultLocaleName. Halaman kode diatur ke LOCALE_IDEFAULTANSICODEPAGE nilai untuk nama lokal default pengguna dengan GetLocaleInfoEx.
setlocale( LC_ALL, "<localename>" );

Mengatur lokal ke nama lokal yang ditunjukkan oleh <localename>. Halaman kode diatur ke LOCALE_IDEFAULTANSICODEPAGE nilai untuk nama lokal yang ditentukan dengan GetLocaleInfoEx.
setlocale( LC_ALL, "<language>_<country>" );

Mengatur lokal ke bahasa dan negara/wilayah yang ditunjukkan oleh <language> dan <country>, bersama dengan halaman kode default yang diperoleh dari sistem operasi host. Halaman kode diatur ke LOCALE_IDEFAULTANSICODEPAGE nilai untuk nama lokal yang ditentukan dengan GetLocaleInfoEx.
setlocale( LC_ALL, "<language>_<country>.<code_page>" );

Mengatur lokal ke bahasa, negara/wilayah, dan halaman kode yang <language>ditunjukkan oleh string , , <country>dan <code_page> . Anda dapat menggunakan berbagai kombinasi bahasa, negara/wilayah, dan halaman kode. Misalnya, panggilan ini mengatur lokal ke Kanada Prancis dengan halaman kode 1252:

setlocale( LC_ALL, "French_Canada.1252" );

Panggilan ini mengatur lokal ke Kanada Prancis dengan halaman kode ANSI default:

setlocale( LC_ALL, "French_Canada.ACP" );

Panggilan ini mengatur lokal ke Kanada Prancis dengan halaman kode OEM default:

setlocale( LC_ALL, "French_Canada.OCP" );
setlocale( LC_ALL, "<language>" );

Mengatur lokal ke bahasa yang ditunjukkan oleh <language>, dan menggunakan negara/wilayah default untuk bahasa yang ditentukan dan halaman kode ANSI default pengguna untuk negara/wilayah tersebut seperti yang diperoleh dari sistem operasi host. Misalnya, panggilan berikut untuk setlocale secara fungsional setara:

setlocale( LC_ALL, "en-US" );

setlocale( LC_ALL, "English" );

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

Kami merekomendasikan bentuk pertama untuk performa dan pemeliharaan.
setlocale( LC_ALL, ".<code_page>" );

Mengatur halaman kode ke nilai yang ditunjukkan oleh <code_page>, bersama dengan negara/wilayah dan bahasa default (seperti yang ditentukan oleh sistem operasi host) untuk halaman kode yang ditentukan.

Kategori harus berupa LC_ALL atau LC_CTYPE untuk mempengaruhi perubahan halaman kode. Misalnya, jika negara/wilayah default dan bahasa sistem operasi host adalah "United States" dan "English", dua panggilan berikut untuk setlocale secara fungsional setara:

setlocale( LC_ALL, ".1252" );

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

Untuk informasi selengkapnya, lihat setlocale direktif pragma di Referensi Praproscesor C/C++.

Fungsi _configthreadlocale ini digunakan untuk mengontrol apakah setlocale memengaruhi lokal semua utas dalam program atau hanya lokal utas panggilan.

Dukungan UTF-8

Mulai Windows 10 versi 1803 (10.0.17134.0), Universal C Runtime mendukung penggunaan halaman kode UTF-8. Perubahan berarti bahwa string yang char diteruskan ke fungsi runtime C dapat mengharapkan string dalam pengodean UTF-8. Untuk mengaktifkan mode UTF-8, gunakan ".UTF8" sebagai halaman kode saat menggunakan setlocale. Misalnya, setlocale(LC_ALL, ".UTF8") menggunakan halaman kode Ansi Windows (ACP) default saat ini untuk lokal dan UTF-8 untuk halaman kode.

String untuk menentukan mode UTF-8 adalah:

tidak peka huruf besar/kecil
tanda hubung (-) bersifat opsional
Ini harus berada di bagian halaman kode dari nama lokal, jadi harus memiliki periode awal (.) seperti dalam contoh-contoh ini: "en_US.UTF8" atau ".utf8"

Contoh berikut menunjukkan cara menentukan string UTF-8:

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

Setelah memanggil setlocale(LC_ALL, ".UTF8"), Anda dapat meneruskan "😊" ke mbtowcs dan itu akan diterjemahkan dengan benar ke wchar_t string. Sebelumnya, tidak ada pengaturan lokal yang tersedia untuk melakukan terjemahan ini.

Mode UTF-8 juga diaktifkan untuk fungsi yang memiliki string yang diterjemahkan char secara historis menggunakan halaman kode ANSI Windows (ACP) default. Misalnya, panggilan _mkdir("😊") saat menggunakan halaman kode UTF-8 akan menghasilkan direktori dengan benar dengan emoji tersebut sebagai nama folder, alih-alih mengharuskan ACP diubah ke UTF-8 sebelum menjalankan program Anda. Demikian juga, panggilan _getcwd() di folder tersebut mengembalikan string yang dikodekan UTF-8. Untuk kompatibilitas, ACP masih digunakan jika halaman kode lokal C tidak diatur ke UTF-8.

Aspek berikut dari C Runtime tidak dapat menggunakan UTF-8 karena diatur selama startup program dan harus menggunakan halaman kode Ansi Windows default (ACP): __argv, , _acmdlndan _pgmptr.

Sebelumnya untuk dukungan ini, mbrtoc16, mbrtoc32, c16rtomb, dan c32rtomb ada untuk menerjemahkan antara string sempit UTF-8, UTF-16 (pengodean yang sama seperti wchar_t pada platform Windows) dan UTF-32. Untuk alasan kompatibilitas, API ini masih hanya menerjemahkan ke dan dari UTF-8 dan bukan halaman kode yang ditetapkan melalui setlocale.

Untuk menggunakan fitur ini pada OS sebelum Windows 10, Anda harus menggunakan penyebaran atau tautan lokal aplikasi secara statis menggunakan versi 1803 (10.0.17134.0) dari Windows SDK atau yang lebih baru. Untuk sistem operasi Windows 10 sebelum 1803 (10.0.17134.0), hanya penautan statis yang didukung.

Persyaratan

Rutin	Header yang diperlukan
`setlocale`	`<locale.h>`
`_wsetlocale`	`<locale.h>` atau `<wchar.h>`

Untuk informasi kompatibilitas selengkapnya, lihat Kompatibilitas.

Contoh

// 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'

Bagikan melalui

`setlocale`, `_wsetlocale`

Sintaks

Parameter

Nilai hasil

Keterangan

Pemetaan rutin teks generik

Dukungan UTF-8

Persyaratan

Contoh

Baca juga

Saran dan Komentar

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

setlocale, _wsetlocale

Sintaks

Parameter

Nilai hasil

Keterangan

Pemetaan rutin teks generik

Dukungan UTF-8

Persyaratan

Contoh

Baca juga

Saran dan Komentar

Saran dan Komentar

Sumber Daya Tambahan:

`setlocale`, `_wsetlocale`