Fungsi FindNLSStringEx (winnls.h)

Artikel
08/27/2023

Menemukan string Unicode (karakter lebar) atau yang setara dalam string Unicode lain untuk lokal yang ditentukan berdasarkan nama.

Hati Karena string dengan representasi biner yang sangat berbeda dapat dibandingkan sebagai identik, fungsi ini dapat meningkatkan masalah keamanan tertentu. Untuk informasi selengkapnya, lihat diskusi fungsi perbandingan dalam Pertimbangan Keamanan: Fitur Internasional.

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.

Nilai	Makna
FIND_FROMSTART	Cari string, dimulai dengan karakter pertama string.
FIND_FROMEND	Cari string ke arah terbalik, dimulai dengan karakter terakhir string.
FIND_STARTSWITH	Uji untuk mengetahui apakah nilai yang ditentukan oleh lpStringValue adalah nilai pertama dalam string sumber yang ditunjukkan oleh lpStringSource.
FIND_ENDSWITH	Uji untuk mengetahui apakah nilai yang ditentukan oleh lpStringValue adalah nilai terakhir dalam string sumber yang ditunjukkan oleh lpStringSource.

Aplikasi dapat menggunakan bendera pemfilteran yang ditentukan di bawah ini dalam kombinasi dengan bendera temukan.

Nilai	Makna
LINGUISTIC_IGNORECASE	Abaikan kasus dalam pencarian, sebagaimana mestinya secara linguistik. Untuk informasi lebih lanjut, lihat bagian Keterangan.
LINGUISTIC_IGNOREDIACRITIC	Abaikan diakritik, sebagaimana mestinya secara linguistik. Untuk informasi lebih lanjut, lihat bagian Keterangan. 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 dalam pencarian. Untuk informasi lebih lanjut, lihat bagian Keterangan.
NORM_IGNOREKANATYPE	Jangan membedakan antara karakter hiragana dan katakana. Karakter hiragana dan katakana yang sesuai dibandingkan sebagai sama.
NORM_IGNORENONSPACE	Abaikan karakter nonspacing. Untuk informasi lebih lanjut, lihat bagian Keterangan.
NORM_IGNORESYMBOLS	Abaikan simbol dan tanda baca.
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 Cina dan Jepang.
NORM_LINGUISTIC_CASING	Gunakan aturan linguistik untuk casing, alih-alih aturan sistem file (default). Untuk informasi lebih lanjut, lihat bagian Keterangan.

[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.

Berbeda dengan fungsi NLS API lainnya, yang mengembalikan 0 untuk kegagalan, fungsi ini mengembalikan -1 jika gagal. Setelah berhasil, ia mengembalikan indeks berbasis 0. Penggunaan indeks ini membantu fungsi menghindari kesalahan off-by-one dan overrun buffer satu karakter.

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