Bagikan melalui


Fungsi LCMapStringEx (winnls.h)

Untuk lokal yang ditentukan berdasarkan nama, memetakan string karakter input ke yang lain menggunakan transformasi tertentu, atau menghasilkan kunci pengurutan untuk string input.

Catatan Aplikasi harus memanggil fungsi ini di preferensi ke LCMapString jika dirancang untuk berjalan hanya pada Windows Vista dan yang lebih baru.

 

Sintaks

int LCMapStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwMapFlags,
  [in]            LPCWSTR          lpSrcStr,
  [in]            int              cchSrc,
  [out, optional] LPWSTR           lpDestStr,
  [in]            int              cchDest,
  [in, optional]  LPNLSVERSIONINFO lpVersionInformation,
  [in, optional]  LPVOID           lpReserved,
  [in, optional]  LPARAM           sortHandle
);

Parameter

[in, optional] lpLocaleName

Arahkan ke nama lokal, atau salah satu nilai yang telah ditentukan sebelumnya berikut ini.

[in] dwMapFlags

Bendera yang menentukan jenis transformasi yang akan digunakan selama pemetaan string atau jenis kunci pengurutan yang akan dihasilkan. Parameter ini dapat memiliki nilai berikut.

Bendera Makna
LCMAP_BYTEREV Gunakan pembalikan byte. Misalnya, jika aplikasi lolos 0x3450 0x4822, hasilnya 0x5034 0x2248.
LCMAP_FULLWIDTH Gunakan karakter Unicode (wide) jika berlaku. Bendera dan LCMAP_HALFWIDTH ini saling eksklusif. Dengan bendera ini, pemetaan dapat menggunakan Formulir Normalisasi C meskipun karakter input sudah lebar penuh. Misalnya, string "は ゙" (yang sudah lebar penuh) dinormalisasi menjadi "ば". Lihat formulir normalisasi Unicode.
LCMAP_HALFWIDTH Gunakan karakter sempit jika berlaku. Bendera dan LCMAP_FULLWIDTH ini saling eksklusif.
LCMAP_HIRAGANA Petakan semua karakter katakana ke hiragana. Bendera dan LCMAP_KATAKANA ini saling eksklusif.
LCMAP_KATAKANA Petakan semua karakter hiragana ke katakana. Bendera dan LCMAP_HIRAGANA ini saling eksklusif.
LCMAP_LINGUISTIC_CASING Gunakan aturan linguistik untuk casing, alih-alih aturan sistem file (default). Bendera ini valid hanya dengan LCMAP_LOWERCASE atau LCMAP_UPPERCASE.
LCMAP_LOWERCASE Untuk lokal dan skrip yang mampu menangani huruf besar dan huruf kecil, petakan semua karakter ke huruf kecil.
LCMAP_HASH Mengembalikan hash dari bobot sortir mentah dari string.

String yang muncul setara biasanya mengembalikan hash yang sama (misalnya, "hello" dan "HELLO" dengan LCMAP_IGNORECASE). Namun, beberapa kasus kompleks, seperti bahasa Asia Timur, dapat memiliki string serupa dengan bobot identik yang dibandingkan sama tetapi tidak mengembalikan hash yang sama.

LCMAP_HASH mengharuskan buffer output berukuranof(int)
LCMAP_SIMPLIFIED_CHINESE Petakan karakter tionghoa tradisional ke karakter Tionghoa yang disederhanakan. Bendera dan LCMAP_TRADITIONAL_CHINESE ini saling eksklusif.
LCMAP_SORTHANDLE
Penggunaan handel pengurutan menghasilkan peningkatan performa minimal dan tidak disarankan.
Mengembalikan token yang mewakili parameter pengurutan yang diselesaikan untuk lokal (seperti nama lokal), sehingga panggilan mendatang dapat meneruskan NULL nama pengurutan dan meneruskan handel pengurutan yang dikueri sebelumnya sebagai parameter terakhir (sortHandle) dalam panggilan berikutnya ke CompareStringEx atau LCMapStringEx.

LCMAP_SORTHANDLE mengharuskan buffer output berukuranof (lparam)
LCMAP_SORTKEY Menghasilkan kunci pengurutan yang dinormalisasi. Jika bendera LCMAP_SORTKEY tidak ditentukan, fungsi melakukan pemetaan string. Untuk detail pengurutan pembuatan kunci dan pemetaan string, lihat bagian Keterangan.
LCMAP_TITLECASE Windows 7: Petakan semua karakter ke huruf besar/kecil, di mana huruf pertama dari setiap kata utama dikapitalisasi.
LCMAP_TRADITIONAL_CHINESE Petakan karakter Tionghoa yang disederhanakan ke karakter Tionghoa tradisional. Bendera dan LCMAP_SIMPLIFIED_CHINESE ini saling eksklusif.
LCMAP_UPPERCASE Untuk lokal dan skrip yang mampu menangani huruf besar dan huruf kecil, petakan semua karakter ke huruf besar.

Bendera berikut dapat digunakan sendiri, satu sama lain, atau dengan bendera LCMAP_SORTKEY dan/atau LCMAP_BYTEREV. Namun, mereka tidak dapat digabungkan dengan bendera lain yang tercantum di atas.

Bendera Makna
NORM_IGNORENONSPACE
Abaikan karakter yang tidak terpakai. Untuk banyak skrip (terutama skrip Latin), NORM_IGNORENONSPACE bertepatan dengan LINGUISTIC_IGNOREDIACRITIC.
Catatan NORM_IGNORENONSPACE mengabaikan perbedaan sekunder apa pun, baik itu diakritik maupun tidak. Skrip untuk bahasa Korea, Jepang, Cina, dan Indik, antara lain, menggunakan perbedaan ini untuk tujuan selain diakritik. LINGUISTIC_IGNOREDIACRITIC menyebabkan fungsi hanya mengabaikan diakritik aktual, alih-alih mengabaikan bobot pengurutan kedua.
 
NORM_IGNORESYMBOLS
Abaikan simbol dan tanda baca.
 

Bendera yang tercantum di bawah ini hanya digunakan dengan bendera LCMAP_SORTKEY.

Bendera Makna
LINGUISTIC_IGNORECASE
Abaikan kasus, sesuai linguistik.
LINGUISTIC_IGNOREDIACRITIC
Abaikan karakter nonspacing, sebagaimana mestinya secara linguistik.
Catatan Bendera ini tidak selalu menghasilkan hasil yang dapat diprediksi ketika digunakan dengan karakter yang diurai, yaitu karakter di mana karakter dasar dan satu atau beberapa karakter nonspacing masing-masing memiliki nilai titik kode yang berbeda.
 
NORM_IGNORECASE
Abaikan kasus. Untuk banyak skrip (terutama skrip Latin), NORM_IGNORECASE bertepatan dengan LINGUISTIC_IGNORECASE.
Catatan NORM_IGNORECASE mengabaikan perbedaan tersier apa pun, apakah itu benar-benar kasus linguistik atau tidak. Misalnya, dalam skrip Arab dan Indik, bendera ini membedakan bentuk karakter alternatif, tetapi perbedaannya tidak sesuai dengan kasus linguistik. LINGUISTIC_IGNORECASE menyebabkan fungsi hanya mengabaikan casing linguistik aktual, alih-alih mengabaikan bobot pengurutan ketiga.
 
Catatan Untuk lokal kumpulan karakter byte ganda (DBCS), NORM_IGNORECASE memiliki efek pada semua karakter Unicode serta karakter sempit (satu byte), termasuk karakter Yunani dan Sirilik.
 
NORM_IGNOREKANATYPE
Jangan membedakan antara karakter hiragana dan katakana. Karakter hiragana dan katakana yang sesuai dibandingkan sebagai sama.
NORM_IGNOREWIDTH
Abaikan perbedaan antara karakter lebar setengah dan lebar penuh, misalnya, C a t == cat. Bentuk lebar penuh adalah perbedaan pemformatan yang digunakan dalam skrip Tionghoa dan Jepang.
NORM_LINGUISTIC_CASING
Gunakan aturan linguistik untuk casing, alih-alih aturan sistem file (default).
SORT_DIGITSASNUMBERS
Windows 7: Perlakukan digit sebagai angka selama pengurutan, misalnya, urutkan "2" sebelum "10".
SORT_STRINGSORT
Perlakukan tanda baca sama dengan simbol.

[in] lpSrcStr

Penunjuk ke string sumber yang dipetakan atau digunakan fungsi untuk mengurutkan pembuatan kunci. String ini tidak boleh memiliki ukuran 0.

[in] cchSrc

Ukuran, dalam karakter, dari string sumber yang ditunjukkan oleh lpSrcStr. Ukuran string sumber dapat mencakup karakter null yang mengakhiri, tetapi tidak harus. Jika karakter null yang mengakhiri disertakan, perilaku pemetaan fungsi tidak sangat terpengaruh karena karakter null yang mengakhiri dianggap tidak dapat diurutkan dan selalu memetakan ke dirinya sendiri.

Aplikasi dapat mengatur parameter ini ke nilai negatif apa pun untuk menentukan bahwa string sumber dihentikan null. Dalam hal ini, jika LCMapStringEx digunakan dalam mode pemetaan string-nya, fungsi menghitung panjang string itu sendiri, dan null-mengakhiri string yang dipetakan yang ditunjukkan oleh lpDestStr.

Aplikasi tidak dapat mengatur parameter ini ke 0.

[out, optional] lpDestStr

Penunjuk ke buffer tempat fungsi ini mengambil string yang dipetakan atau kunci pengurutan.

Jika aplikasi menggunakan fungsi untuk menghasilkan kunci pengurutan (LCMAP_SORTKEY):

  • Kunci sortir disimpan dalam buffer dan diperlakukan sebagai array byte buram. Nilai yang disimpan dapat mencakup 0 byte yang disematkan di posisi mana pun.
  • String tujuan dapat berisi jumlah byte ganjil. Bendera LCMAP_BYTEREV hanya membalikkan jumlah byte yang merata. Byte terakhir (posisi ganjil) dalam kunci pengurutan tidak dibalik.

Jika penelepon secara eksplisit meminta subset string, string tujuan tidak menyertakan karakter null yang mengakhiri kecuali pemanggil menentukannya di cchDest.

Jika fungsi ini gagal, buffer tujuan mungkin berisi hasil parsial atau tidak ada hasil sama sekali. Dalam hal ini, semua hasil harus dianggap tidak valid.

Catatan

Saat mengatur LCMAP_UPPERCASE atau LCMAP_LOWERCASE, string tujuan dapat menggunakan buffer yang sama dengan string sumber. Namun, ini sangat tidak disarankan, karena beberapa kondisi dapat menyebabkan string kasus yang dikembalikan memiliki panjang yang berbeda.

[in] cchDest

Ukuran, dalam karakter, dari string tujuan yang ditunjukkan oleh lpDestStr. Jika aplikasi menggunakan fungsi untuk pemetaan string, aplikasi memasok jumlah karakter untuk parameter ini. Jika spasi untuk karakter null yang mengakhiri disertakan dalam cchSrc, cchDest juga harus menyertakan spasi untuk karakter null yang mengakhiri.

Jika aplikasi menggunakan fungsi untuk menghasilkan kunci pengurutan, aplikasi memasok jumlah byte untuk ukuran tersebut. Jumlah byte ini harus menyertakan ruang untuk kunci pengurutan 0x00 terminator.

Aplikasi dapat mengatur cchDest ke 0. Dalam hal ini, fungsi tidak menggunakan parameter lpDestStr dan mengembalikan ukuran buffer yang diperlukan untuk string yang dipetakan atau kunci sortir.

[in, optional] lpVersionInformation

Penunjuk ke struktur NLSVERSIONINFOEX yang berisi informasi versi tentang kemampuan NLS yang relevan; biasanya diambil dari GetNLSVersionEx.

Windows Vista, Windows 7: Dipesan; harus diatur ke NULL.

[in, optional] lpReserved

Dipesan; harus NULL.

[in, optional] sortHandle

Dipesan; harus 0.

Catatan

CompareStringEx dan LCMapStringEx dapat menentukan handel pengurutan (jika nama lokal null). Penggunaan ini tidak disarankan untuk sebagian besar aplikasi.

Nilai kembali

Jika fungsi berhasil saat digunakan untuk pemetaan string, fungsi mengembalikan jumlah karakter dalam string yang diterjemahkan (lihat cchSrc dan cchDest untuk detail selengkapnya).

Jika fungsi berhasil saat digunakan untuk menghasilkan kunci pengurutan, fungsi mengembalikan jumlah byte dalam kunci pengurutan.

Fungsi ini mengembalikan 0 jika tidak berhasil. Untuk mendapatkan informasi kesalahan yang diperluas, aplikasi dapat memanggil GetLastError, yang dapat mengembalikan salah satu kode kesalahan berikut:

  • ERROR_INSUFFICIENT_BUFFER. Ukuran buffer yang disediakan tidak cukup besar, atau salah diatur ke NULL.
  • ERROR_INVALID_FLAGS. Nilai yang diberikan untuk bendera tidak valid.
  • ERROR_INVALID_PARAMETER. Salah satu nilai parameter tidak valid.

Keterangan

Aplikasi dapat menggunakan LCMapString atau LCMapStringEx untuk menghasilkan kunci pengurutan. Untuk melakukan ini, aplikasi menentukan LCMAP_SORTKEY untuk parameter dwMapFlags . Untuk informasi selengkapnya, lihat Menangani Pengurutan di Aplikasi Anda.

Catatan

Kunci sortir adalah aliran byte buram. Penelepon harus memperlakukannya sebagai array byte dengan panjang yang dikembalikan oleh API dan tidak bergantung pada struktur internal apa pun yang mungkin tampak ada. Nol, satu atau beberapa byte dalam kunci pengurutan yang dikembalikan bisa 0. Ketidakhadiran atau kehadiran byte nol seharusnya tidak diharapkan.

Cara lain bagi aplikasi Anda untuk menggunakan LCMapString atau LCMapStringEx adalah dalam string pemetaan. Dalam hal ini, aplikasi tidak menentukan LCMAP_SORTKEY untuk parameter dwMapFlags , tetapi memasok beberapa kombinasi bendera lainnya. Untuk informasi selengkapnya, lihat Menangani Pengurutan di Aplikasi Anda.

Dimulai di Windows Vista: Fungsi ini dapat menangani data dari lokal kustom. Data tidak dijamin sama dari komputer ke komputer atau antara eksekusi aplikasi. Jika aplikasi Anda harus mempertahankan atau mengirimkan data, lihat Menggunakan Data Lokal Persisten.

Dimulai di Windows 8: Jika aplikasi Anda meneruskan tag bahasa ke fungsi ini dari namespace Windows.Globalization, aplikasi harus terlebih dahulu mengonversi tag dengan memanggil ResolveLocaleName.

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows Vista [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung Windows Server 2008 [aplikasi desktop | Aplikasi UWP]
Target Platform Windows
Header winnls.h (termasuk Windows.h)
Pustaka Kernel32.lib
DLL Kernel32.dll

Lihat juga

CompareString

FindNLSStringEx

GetNLSVersionEx

Menangani Penyortiran di Aplikasi Anda

LCMapString

Dukungan Bahasa Nasional

Fungsi Dukungan Bahasa Nasional