CompareStringEx 함수(stringapiset.h)

아티클
08/26/2023

이름으로 지정된 로 캘 에 대해 두 개의 유니코드(와이드 문자) 문자열을 비교합니다.

주의CompareStringEx를 잘못 사용하면 애플리케이션의 보안이 손상됩니다. 올바르게 비교되지 않은 문자열은 잘못된 입력을 생성할 수 있습니다. 문자열을 테스트하여 문자열을 사용하기 전에 유효한지 확인하고 오류 처리기를 제공합니다. 자세한 내용은 보안 고려 사항: 국가별 기능을 참조하세요.

참고 애플리케이션은 Windows Vista 이상에서만 실행되도록 설계된 경우 CompareString 에 대한 기본 설정으로 이 함수를 호출해야 합니다.

구문

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
);

매개 변수

[in, optional] lpLocaleName

로캘 이름 또는 다음 미리 정의된 값 중 하나에 대한 포인터입니다.

[in] dwCmpFlags

함수가 두 문자열을 비교하는 방법을 나타내는 플래그입니다. 기본적으로 이러한 플래그는 설정되지 않습니다. 이 매개 변수는 다음 값의 조합을 지정하거나 0으로 설정하여 기본 동작을 가져올 수 있습니다.

플래그	의미
LINGUISTIC_IGNORECASE	대/소문자를 언어적으로 적절하게 무시합니다.
LINGUISTIC_IGNOREDIACRITIC	비스페이싱 문자를 언어적으로 적절한 문자로 무시합니다. 참고 이 플래그는 분해된 문자와 함께 사용될 때 항상 예측 가능한 결과를 생성하지는 않습니다. 즉, 기본 문자와 하나 이상의 비스페이스 문자가 각각 고유한 코드 포인트 값을 갖는 문자입니다.
NORM_IGNORECASE	대/소문자를 무시합니다. 많은 스크립트(특히 라틴어 스크립트)의 경우 NORM_IGNORECASE LINGUISTIC_IGNORECASE 일치합니다. 참고 NORM_IGNORECASE 실제로 언어적 사례인지 여부에 관계없이 3차 구분을 무시합니다. 예를 들어 아랍어 및 인딕 스크립트에서는 다른 형식의 문자를 구분하지만 차이점은 언어적 사례에 해당하지 않습니다. LINGUISTIC_IGNORECASE 함수는 세 번째 정렬 가중치를 무시하는 대신 실제 언어 대/소문자만 무시합니다. 참고 이 플래그를 설정하면 함수는 CJK 호환성 문자의 넓고 좁은 형식을 구분하지 않습니다.
NORM_IGNOREKANATYPE	히라가나와 가타카나 문자를 구분하지 마십시오. 해당 히라가나와 가타카나 문자는 동일하게 비교합니다.
NORM_IGNORENONSPACE	간격이 없는 문자를 무시합니다. 많은 스크립트(특히 라틴어 스크립트)의 경우 NORM_IGNORENONSPACE LINGUISTIC_IGNOREDIACRITIC 일치합니다. 참고 NORM_IGNORENONSPACE 분음 부호인지 여부에 관계없이 보조 구분을 무시합니다. 한국어, 일본어, 중국어 및 인덱스 언어에 대한 스크립트는 분음 부호 이외의 용도로 이 구분을 사용합니다. LINGUISTIC_IGNOREDIACRITIC 두 번째 정렬 가중치를 무시하는 대신 함수가 실제 분음 부호만 무시하도록 합니다. 참고 NORM_IGNORENONSPACE 악센트 문자가 기본 문자에서 두 번째 패스로 정렬되는 로캘에만 영향을 미칩니다. 일반적으로 문자열의 모든 문자는 악센트에 관계없이 먼저 비교되며 문자열이 같으면 두 번째 문자열 전달을 수행하여 악센트를 비교합니다. 이 플래그를 사용하면 두 번째 패스가 수행되지 않습니다. 첫 번째 패스에서 악센트가 있는 문자를 정렬하는 로캘의 경우 이 플래그는 영향을 주지 않습니다.
NORM_IGNORESYMBOLS	기호 및 문장 부호를 무시합니다.
NORM_IGNOREWIDTH	반자 문자와 전체 너비 문자의 차이를 무시합니다(예: C a t == cat). 전체 너비 형식은 중국어 및 일본어 스크립트에서 사용되는 서식 구분입니다.
NORM_LINGUISTIC_CASING	파일 시스템 규칙 대신 대/소문자 구분에 기본 언어 규칙을 사용합니다. CompareStringEx에 대한 대부분의 시나리오는 이 플래그를 사용합니다. 애플리케이션에서 CompareStringOrdinal을 호출할 때 이 플래그를 사용할 필요가 없습니다.
SORT_DIGITSASNUMBERS	Windows 7: 정렬하는 동안 숫자를 숫자로 처리합니다( 예: "10" 앞에 "2"를 정렬).
SORT_STRINGSORT	문장 부호를 기호와 동일하게 처리합니다.

[in] lpString1

비교할 첫 번째 문자열에 대한 포인터입니다.

[in] cchCount1

종료 null 문자를 제외하고 lpString1로 표시된 문자열의 길이입니다. 문자열이 null로 끝나는 경우 애플리케이션에서 음수 값을 제공할 수 있습니다. 이 경우 함수는 길이를 자동으로 결정합니다.

[in] lpString2

비교할 두 번째 문자열에 대한 포인터입니다.

[in] cchCount2

종료 null 문자를 제외하고 lpString2로 표시된 문자열의 길이입니다. 문자열이 null로 끝나는 경우 애플리케이션에서 음수 값을 제공할 수 있습니다. 이 경우 함수는 길이를 자동으로 결정합니다.

[in, optional] lpVersionInformation

관련 NLS 기능에 대한 버전 정보를 포함하는 NLSVERSIONINFOEX 구조체에 대한 포인터입니다. 일반적으로 GetNLSVersionEx에서 검색됩니다.

Windows Vista, Windows 7: 예약; 은 NULL로 설정해야 합니다.

[in, optional] lpReserved

예약; 은 NULL로 설정해야 합니다.

[in, optional] lParam

예약; 은 0으로 설정해야 합니다.

반환 값

성공하면 다음 값 중 하나를 반환합니다. 문자열 비교의 C 런타임 규칙을 유지하기 위해 값 2를 0이 아닌 반환 값에서 빼면 됩니다. 그런 다음, 0, ==0 및 >0의 <의미는 C 런타임과 일치합니다.

CSTR_LESS_THAN. lpString1로 표시된 문자열은 lpString2로 표시된 문자열보다 어휘 값이 적습니다.
CSTR_EQUAL. lpString1로 표시된 문자열은 lpString2로 표시된 문자열과 어휘 값에 해당합니다. 두 문자열은 정렬 목적으로 동일하지만 반드시 동일하지는 않습니다.
CSTR_GREATER_THAN. lpString1로 표시된 문자열은 lpString2로 표시된 문자열보다 어휘 값이 큽니다.

함수가 성공하지 못하면 0을 반환합니다. 확장된 오류 정보를 가져오기 위해 애플리케이션은 다음 오류 코드 중 하나를 반환할 수 있는 GetLastError를 호출할 수 있습니다.

ERROR_INVALID_FLAGS. 플래그에 제공된 값이 잘못되었습니다.
ERROR_INVALID_PARAMETER. 매개 변수 값이 잘못되었습니다.

설명

CompareString 및 CompareStringEx는 dwCmpFlags가 0 또는 NORM_IGNORECASE, cchCount1 및 cchCount2가 -1로 설정되고, 기존 스페인어 정렬에서 "ch"를 단일 문자로 처리할 때처럼 로캘이 언어 압축을 지원하지 않는 경우 가장 빠른 속도로 실행되도록 최적화됩니다.

비교하는 동안 CompareString 및 CompareStringEx 는 모두 아랍어 카시다를 무시합니다. 따라서 kashidas가 있는 경우를 제외하고 두 문자열이 동일하면 함수는 CSTR_EQUAL 반환합니다.

애플리케이션에서 정렬 함수와 함께 NORM_IGNORENONSPACE 및 NORM_IGNORECASE 플래그를 사용하는 경우 플래그가 문자열 비교를 방해할 수 있습니다. 이 경우 공백이 아닌 문자 또는 대/소문자를 지원하지 않지만 동일한 가중치 수준을 사용하여 다른 중요한 작업을 처리하는 로캘이 발생할 수 있습니다. 이러한 경우 애플리케이션은 LINGUISTIC_IGNOREDIACRITIC 및 LINGUISTIC_IGNORECASE 플래그를 사용해야 합니다. 이러한 플래그는 대/소문자 및 분음 부호를 사용하는 코드 포인트를 정렬하기 위한 언어적으로 적절한 결과를 제공하며 다른 코드 포인트에는 영향을 주지 않습니다.

Windows Vista에서 시작: CompareString 및 CompareStringEx 는 모두 사용자 지정 로캘에서 데이터를 검색할 수 있습니다. 데이터가 컴퓨터에서 컴퓨터로 또는 애플리케이션 실행 간에 동일하지는 않습니다. 애플리케이션이 데이터를 유지하거나 전송해야 하는 경우 영구 로캘 데이터 사용을 참조하세요.

Windows 8 시작: 앱이Windows.Globalization 네임스페이스에서 이 함수에 언어 태그를 전달하는 경우 먼저 ResolveLocaleName을 호출하여 태그를 변환해야 합니다.

Windows 8 시작: CompareStringEx는 Stringapiset.h에서 선언됩니다. Windows 8 전에 Winnls.h에서 선언되었습니다.

참고 정렬 동작은 Windows 릴리스 간에 변경될 수 있습니다. 예를 들어 새 유니코드 코드 포인트가 만들어질 수 있습니다. GetNlsVersionEx를 사용하여 정렬 버전이 변경되었는지 검색합니다.

예제

이 함수의 사용을 보여 주는 예제는 NLS: 이름 기반 API 샘플에서 찾을 수 있습니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	stringapiset.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll