Fungsi FindNLSStringEx (winnls.h)
Menemukan string Unicode (karakter lebar) atau yang setara dalam string Unicode lain untuk lokal yang ditentukan berdasarkan nama.
Sintaks
int FindNLSStringEx(
[in, optional] LPCWSTR lpLocaleName,
[in] DWORD dwFindNLSStringFlags,
[in] LPCWSTR lpStringSource,
[in] int cchSource,
[in] LPCWSTR lpStringValue,
[in] int cchValue,
[out, optional] LPINT pcchFound,
[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] dwFindNLSStringFlags
Bendera yang menentukan detail operasi temukan. Bendera ini saling eksklusif, dengan FIND_FROMSTART menjadi default. Aplikasi hanya dapat menentukan salah satu bendera temukan dengan salah satu bendera pemfilteran yang ditentukan dalam tabel berikutnya. Jika aplikasi tidak menentukan bendera, fungsi menggunakan perbandingan default untuk lokal yang ditentukan. Seperti yang dibahas dalam Menangani Pengurutan di Aplikasi Anda, tidak ada mode perbandingan biner.
Aplikasi dapat menggunakan bendera pemfilteran yang ditentukan di bawah ini dalam kombinasi dengan bendera temukan.
[in] lpStringSource
Penunjuk ke string sumber, di mana fungsi mencari string yang ditentukan oleh lpStringValue.
[in] cchSource
Ukuran, dalam karakter tidak termasuk karakter null yang mengakhiri, dari string yang ditunjukkan oleh lpStringSource. Aplikasi tidak dapat menentukan 0 atau angka negatif selain -1 untuk parameter ini. Aplikasi menentukan -1 jika string sumber dihentikan null dan fungsi harus menghitung ukuran secara otomatis.
[in] lpStringValue
Arahkan ke string pencarian, yang fungsinya dicari dalam string sumber.
[in] cchValue
Ukuran, dalam karakter tidak termasuk karakter null yang mengakhiri, dari string yang ditunjukkan oleh lpStringValue. Aplikasi tidak dapat menentukan 0 atau angka negatif selain -1 untuk parameter ini. Aplikasi menentukan -1 jika string pencarian dihentikan null dan fungsi harus menghitung ukuran secara otomatis.
[out, optional] pcchFound
Penunjuk ke buffer yang berisi panjang string yang ditemukan fungsi. String dapat lebih panjang atau lebih pendek dari string pencarian. Jika fungsi gagal menemukan string pencarian, parameter ini tidak dimodifikasi.
Fungsi dapat mengambil NULL dalam parameter ini. Dalam hal ini, fungsi tidak membuat indikasi jika panjang string yang ditemukan berbeda dari panjang string sumber.
Perhatikan bahwa nilai pcchFound sering identik dengan nilai yang disediakan dalam cchValue, tetapi dapat berbeda dalam kasus berikut:
- Nilai yang disediakan dalam cchValue negatif.
- String setara, tetapi memiliki panjang yang berbeda. Misalnya, "A" plus "Combining Ring" (U+0041 U+030A) setara dengan "A Ring" (U+00c5).
[in, optional] lpVersionInformation
Dipesan; harus NULL.
[in, optional] lpReserved
Dipesan; harus NULL.
[in, optional] sortHandle
Dipesan; harus 0.
Mengembalikan nilai
Mengembalikan indeks berbasis 0 ke dalam string sumber yang ditunjukkan oleh lpStringSource jika berhasil. Dalam kombinasi dengan nilai di pcchFound, indeks ini menyediakan lokasi yang tepat dari seluruh string yang ditemukan dalam string sumber. Nilai pengembalian 0 adalah indeks bebas kesalahan ke dalam string sumber, dan string yang cocok berada dalam string sumber pada offset 0.
Fungsi mengembalikan -1 jika tidak berhasil. Untuk mendapatkan informasi kesalahan yang diperluas, aplikasi dapat memanggil GetLastError, yang dapat mengembalikan salah satu kode kesalahan berikut:
- ERROR_INVALID_FLAGS. Nilai yang diberikan untuk bendera tidak valid.
- ERROR_INVALID_PARAMETER. Salah satu nilai parameter tidak valid.
- ERROR_SUCCESS. Tindakan berhasil diselesaikan tetapi tidak menghasilkan hasil.
Keterangan
Fungsi ini menyediakan berbagai opsi pencarian, termasuk arah pencarian, pemfilteran kesetaraan karakter, dan pemfilteran khusus lokal. Perhatikan bahwa kesetaraan tergantung pada lokal dan bendera yang ditentukan dalam panggilan ke fungsi. Bendera pemfilteran dapat mengubah hasil pencarian. Misalnya, potensi kecocokan meningkat ketika fungsi mengabaikan kasus atau tanda diakritik saat melakukan pencarian.
Secara default, fungsi ini memetakan huruf kecil "i" ke huruf besar "I", bahkan ketika parameter Lokal menentukan Turki (Turki) atau Azerbaijan (Azerbaijan). Untuk mengambil alih perilaku ini untuk Bahasa Turki atau Azerbaijan, aplikasi harus menentukan NORM_LINGUISTIC_CASING. Jika bendera ini ditentukan untuk lokal yang benar, "ı" (huruf kecil tanpa titik I) adalah bentuk huruf kecil "I" (huruf besar tanpa titik I) dan "i" (huruf kecil bertitik I) adalah bentuk huruf kecil "ı" (huruf besar bertitik I).
Untuk banyak skrip (terutama skrip Latin), NORM_IGNORENONSPACE bertepatan dengan LINGUISTIC_IGNOREDIACRITIC dan NORM_IGNORECASE bertepatan dengan LINGUISTIC_IGNORECASE, dengan pengecualian berikut:
- NORM_IGNORENONSPACE mengabaikan perbedaan sekunder, apakah itu diakritik atau tidak. Skrip untuk bahasa Korea, Jepang, Cina, Indic, dan lainnya menggunakan perbedaan ini untuk tujuan selain diakritik. LINGUISTIC_IGNOREDIACRITIC hanya mengabaikan diakritik aktual, alih-alih hanya mengabaikan bobot pengurutan kedua.
- NORM_IGNORECASE mengabaikan perbedaan tersier, apakah itu benar-benar kasus linguistik atau tidak. Misalnya, dalam skrip Arab dan Indic, bendera ini membedakan bentuk alternatif dari karakter. Namun, perbedaannya tidak sesuai dengan kasus linguistik. LINGUISTIC_IGNORECASE hanya mengabaikan casing linguistik aktual, alih-alih mengabaikan bobot pengurutan ketiga.
Fungsi ini adalah salah satu dari beberapa fungsi NLS yang memanggil SetLastError bahkan ketika berhasil. Ini membuat panggilan ini untuk menghapus kesalahan terakhir dalam utas ketika gagal mencocokkan string pencarian. Ini menghapus nilai yang dikembalikan oleh GetLastError.
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
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
Menangani Penyortiran di Aplikasi Anda