Fungsi CompareStringEx (stringapiset.h)

Artikel
08/26/2023

Membandingkan dua string Unicode (karakter lebar), untuk lokal yang ditentukan berdasarkan nama.

Hati Menggunakan CompareStringEx salah dapat membahayakan keamanan aplikasi Anda. String yang tidak dibandingkan dengan benar dapat menghasilkan input yang tidak valid. Uji string untuk memastikan string tersebut valid sebelum menggunakannya, dan menyediakan penangan kesalahan. Untuk informasi selengkapnya, lihat Pertimbangan Keamanan: Fitur Internasional.

Catatan Aplikasi harus memanggil fungsi ini disukai untuk CompareString jika dirancang untuk berjalan hanya di Windows Vista dan yang lebih baru.

Sintaks

int CompareStringEx(
  [in, optional] LPCWSTR                          lpLocaleName,
  [in]           DWORD                            dwCmpFlags,
  [in]           _In_NLS_string_(cchCount1)LPCWCH lpString1,
  [in]           int                              cchCount1,
  [in]           _In_NLS_string_(cchCount2)LPCWCH lpString2,
  [in]           int                              cchCount2,
  [in, optional] LPNLSVERSIONINFO                 lpVersionInformation,
  [in, optional] LPVOID                           lpReserved,
  [in, optional] LPARAM                           lParam
);

Parameter

[in, optional] lpLocaleName

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

[in] dwCmpFlags

Bendera yang menunjukkan bagaimana fungsi membandingkan dua string. Secara default, bendera ini tidak diatur. Parameter ini dapat menentukan kombinasi salah satu nilai berikut, atau dapat diatur ke 0 untuk mendapatkan perilaku default.

Bendera	Makna
LINGUISTIC_IGNORECASE	Abaikan huruf besar/kecil, sebagaimana mestinya secara 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, apakah itu benar-benar kasus linguistik atau tidak. Misalnya, dalam skrip Arab dan Indik, ini membedakan bentuk alternatif dari karakter, tetapi perbedaannya tidak sesuai dengan kasus linguistik. LINGUISTIC_IGNORECASE menyebabkan fungsi hanya mengabaikan casing linguistik aktual, alih-alih mengabaikan bobot pengurutan ketiga. Catatan Dengan set bendera ini, fungsi mengabaikan perbedaan antara bentuk lebar dan sempit dari karakter kompatibilitas CJK.
NORM_IGNOREKANATYPE	Jangan membedakan antara karakter hiragana dan katakana. Karakter hiragana dan katakana yang sesuai dibandingkan sebagai sama.
NORM_IGNORENONSPACE	Abaikan karakter nonspacing. Untuk banyak skrip (terutama skrip Latin), NORM_IGNORENONSPACE bertepatan dengan LINGUISTIC_IGNOREDIACRITIC. Catatan NORM_IGNORENONSPACE mengabaikan perbedaan sekunder, baik itu diakritik atau tidak. Skrip untuk bahasa Korea, Jepang, Cina, dan Indic, antara lain, menggunakan perbedaan ini untuk tujuan selain diakritik. LINGUISTIC_IGNOREDIACRITIC menyebabkan fungsi hanya mengabaikan diakritik aktual, alih-alih mengabaikan bobot pengurutan kedua. Catatan NORM_IGNORENONSPACE hanya memiliki efek untuk lokal di mana karakter beraksen diurutkan dalam pass kedua dari karakter utama. Biasanya semua karakter dalam string pertama kali dibandingkan tanpa memperhatikan aksen dan, jika string sama, pass kedua atas string dilakukan untuk membandingkan aksen. Bendera ini menyebabkan pass kedua tidak dilakukan. Untuk lokal yang mengurutkan karakter beraksen di pass pertama, bendera ini tidak berpengaruh.
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 default untuk casing, bukan aturan sistem file. Perhatikan bahwa sebagian besar skenario untuk CompareStringEx menggunakan bendera ini. Bendera ini tidak harus digunakan saat aplikasi Anda memanggil CompareStringOrdinal.
SORT_DIGITSASNUMBERS	Windows 7: Perlakukan digit sebagai angka selama pengurutan, misalnya, urutkan "2" sebelum "10".
SORT_STRINGSORT	Perlakukan tanda baca sama dengan simbol.

[in] lpString1

Arahkan ke string pertama untuk dibandingkan.

[in] cchCount1

Panjang string yang ditunjukkan oleh lpString1, tidak termasuk karakter null yang mengakhiri. Aplikasi dapat memberikan nilai negatif jika string dihentikan null. Dalam hal ini, fungsi menentukan panjang secara otomatis.

[in] lpString2

Arahkan ke string kedua untuk dibandingkan.

[in] cchCount2

Panjang string yang ditunjukkan oleh lpString2, tidak termasuk karakter null yang mengakhiri. Aplikasi dapat memberikan nilai negatif jika string dihentikan null. Dalam hal ini, fungsi menentukan panjang secara otomatis.

[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 diatur ke NULL.

[in, optional] lParam

Dipesan; harus diatur ke 0.

Mengembalikan nilai

Mengembalikan salah satu nilai berikut jika berhasil. Untuk mempertahankan konvensi runtime C membandingkan string, nilai 2 dapat dikurangi dari nilai pengembalian bukan nol. Kemudian, arti <0, ==0, dan >0 konsisten dengan runtime C.

CSTR_LESS_THAN. String yang ditunjukkan oleh lpString1 kurang dalam nilai leksikal daripada string yang ditunjukkan oleh lpString2.
CSTR_EQUAL. String yang ditunjukkan oleh lpString1 setara dengan nilai leksikal dengan string yang ditunjukkan oleh lpString2. Kedua string tersebut setara untuk tujuan pengurutan, meskipun belum tentu identik.
CSTR_GREATER_THAN. String yang ditunjukkan oleh lpString1 lebih besar dalam nilai leksikal daripada string yang ditunjukkan oleh lpString2.

Fungsi mengembalikan 0 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 disediakan untuk bendera tidak valid.
ERROR_INVALID_PARAMETER. Salah satu nilai parameter tidak valid.

Keterangan

Baik CompareString dan CompareStringEx dioptimalkan untuk berjalan pada kecepatan tertinggi ketika dwCmpFlags diatur ke 0 atau NORM_IGNORECASE, cchCount1 dan cchCount2 diatur ke -1, dan lokal tidak mendukung kompresi linguistik apa pun, seperti ketika pengurutan tradisional Spanyol memperlakukan "ch" sebagai karakter tunggal.

Baik CompareString maupun CompareStringEx mengabaikan kashida Arab selama perbandingan. Dengan demikian, jika dua string identik kecuali untuk keberadaan kashida, fungsi mengembalikan CSTR_EQUAL.

Saat aplikasi menggunakan bendera NORM_IGNORENONSPACE dan NORM_IGNORECASE dengan fungsi pengurutan, bendera terkadang dapat mengganggu perbandingan string. Situasi ini dapat mengakibatkan lokal yang tidak mendukung karakter atau kasus non-spasi, tetapi menggunakan tingkat berat yang setara untuk menangani operasi penting lainnya. Dalam kasus seperti itu, aplikasi Anda harus menggunakan bendera LINGUISTIC_IGNOREDIACRITIC dan LINGUISTIC_IGNORECASE. Bendera ini memberikan hasil yang sesuai secara linguistik untuk mengurutkan titik kode yang menggunakan huruf besar/kecil dan tanda diakritik, dan tidak berdampak pada titik kode lainnya.

Dimulai di Windows Vista: CompareString dan CompareStringEx dapat mengambil 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.

Mulai Windows 8: CompareStringEx dideklarasikan dalam Stringapiset.h. Sebelum Windows 8, itu dinyatakan di Winnls.h.

Catatan Perilaku pengurutan dapat berubah di antara rilis Windows. Misalnya, mungkin ada titik kode Unicode baru yang dibuat. Gunakan GetNlsVersionEx untuk menemukan apakah versi pengurutan telah berubah.

Contoh

Contoh yang menunjukkan penggunaan fungsi ini dapat ditemukan di NLS: Sampel API berbasis nama.

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	stringapiset.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll