Fungsi CompareStringW (stringapiset.h)

Artikel
03/08/2023

Membandingkan dua string karakter, untuk lokal yang ditentukan oleh pengidentifikasi.

Hati Menggunakan CompareString salah dapat membahayakan keamanan aplikasi Anda. String yang tidak dibandingkan dengan benar dapat menghasilkan input yang tidak valid. Misalnya, fungsi dapat meningkatkan masalah keamanan ketika digunakan untuk perbandingan non-linguistik, karena dua string yang berbeda dalam representasi biner mereka dapat setara secara linguistik. Aplikasi harus menguji string untuk validitas sebelum menggunakannya, dan harus menyediakan penangan kesalahan. Untuk informasi selengkapnya, lihat Pertimbangan Keamanan: Fitur Internasional.

Catatan Untuk kompatibilitas dengan Unicode, aplikasi Anda harus lebih memilih CompareStringEx atau compareString versi Unicode. Alasan lain untuk lebih memilih CompareStringEx adalah bahwa Microsoft bermigrasi ke penggunaan nama lokal alih-alih pengidentifikasi lokal untuk lokal baru, karena alasan interoperabilitas. Aplikasi apa pun yang hanya akan dijalankan di Windows Vista dan nantinya harus menggunakan CompareStringEx.

Sintaks

int CompareStringW(
  [in] LCID                              Locale,
  [in] DWORD                             dwCmpFlags,
  [in] _In_NLS_string_(cchCount1)PCNZWCH lpString1,
  [in] int                               cchCount1,
  [in] _In_NLS_string_(cchCount2)PCNZWCH lpString2,
  [in] int                               cchCount2
);

Parameter

[in] Locale

Pengidentifikasi lokal lokal yang digunakan untuk perbandingan. Anda bisa menggunakan makro MAKELCID untuk membuat pengidentifikasi lokal atau menggunakan salah satu nilai yang telah ditentukan sebelumnya berikut ini.

[in] dwCmpFlags

Bendera yang menunjukkan bagaimana fungsi membandingkan dua string. Untuk definisi terperinci, lihat parameter dwCmpFlags dari CompareStringEx.

[in] lpString1

Arahkan ke string pertama untuk dibandingkan.

[in] cchCount1

Panjang string yang ditunjukkan oleh lpString1, tidak termasuk karakter null yang mengakhiri. Nilai ini mewakili byte untuk versi ANSI dari fungsi dan karakter lebar untuk versi Unicode. 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. Nilai ini mewakili byte untuk versi ANSI dari fungsi dan karakter lebar untuk versi Unicode. Aplikasi dapat memberikan nilai negatif jika string dihentikan null. Dalam hal ini, fungsi menentukan panjang secara otomatis.

Nilai kembali

Mengembalikan nilai yang dijelaskan untuk CompareStringEx.

Keterangan

Lihat Keterangan untuk CompareStringEx.

Jika aplikasi Anda memanggil versi ANSI dari CompareString, fungsi mengonversi parameter melalui halaman kode default lokal yang disediakan. Dengan demikian, aplikasi tidak pernah dapat menggunakan CompareString untuk menangani teks UTF-8.

Biasanya, untuk perbandingan yang tidak peka huruf besar/kecil, CompareString memetakan huruf kecil "i" ke huruf besar "I", bahkan ketika lokalnya adalah Bahasa Turki atau Azerbaijan. Bendera NORM_LINGUISTIC_CASING mengambil alih perilaku ini untuk Bahasa Turki atau Azerbaijan. Jika bendera ini ditentukan bersama dengan bahasa Turki atau Azerbaijani, LATIN SMALL LETTER DOTLESS I (U+0131) adalah bentuk huruf kecil LATIN CAPITAL LETTER I (U+0049) dan LATIN SMALL LETTER I (U+0069) adalah bentuk huruf kecil LATIN CAPITAL LETTER I WITH DOT ABOVE (U+0130).

Dimulai dengan Windows 8: Versi ANSI dari fungsi dideklarasikan dalam Winnls.h, dan versi Unicode dideklarasikan dalam Stringapiset.h. Sebelum Windows 8, kedua versi dideklarasikan dalam Winnls.h.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	stringapiset.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll