Fungsi CompareString (winnls.h)

Artikel
03/04/2024

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

Hati Menggunakan CompareString secara tidak benar 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 versi Unicode dari CompareString. 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 pada Windows Vista dan nantinya harus menggunakan CompareStringEx.

Sintaks

int CompareString(
  [in] LCID    Locale,
  [in] DWORD   dwCmpFlags,
  [in] LPCTSTR lpString1,
  [in] int     cchCount1,
  [in] LPCTSTR lpString2,
  [in] int     cchCount2
);

Parameter

[in] Locale

Pengidentifikasi lokal lokal yang digunakan untuk perbandingan. Anda dapat 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 compareString versi ANSI, fungsi akan 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 Turki atau Azerbaijani. Bendera NORM_LINGUISTIC_CASING mengambil alih perilaku ini untuk Turki atau Azerbaijani. Jika bendera ini ditentukan bersama dengan bahasa Turki atau Azerbaijani, LATIN SMALL LETTER DOTLESS I (U+0131) adalah bentuk huruf kecil DARI HURUF LATIN KAPITAL I (U+0049) dan HURUF KECIL LATIN I (U+0069) adalah bentuk huruf kecil HURUF LATIN I DENGAN TITIK DI ATAS (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	winnls.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll