Fungsi CompareStringA (winnls.h)

Artikel
08/27/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 CompareStringA(
  [in] LCID   Locale,
  [in] DWORD  dwCmpFlags,
  [in] PCNZCH lpString1,
  [in] int    cchCount1,
  [in] PCNZCH 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.

Mengembalikan nilai

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 ini dideklarasikan dalam Winnls.h, dan versi Unicode dideklarasikan dalam Stringapiset.h. Sebelum Windows 8, kedua versi dideklarasikan dalam Winnls.h.

Catatan

Header winnls.h mendefinisikan CompareString sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan


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