FindNLSStringEx 함수(winnls.h)
이름으로 지정된 로캘의 다른 유니코드 문자열에서 유니코드 문자열(와이드 문자) 또는 해당 문자열을 찾습니다.
구문
int FindNLSStringEx(
[in, optional] LPCWSTR lpLocaleName,
[in] DWORD dwFindNLSStringFlags,
[in] LPCWSTR lpStringSource,
[in] int cchSource,
[in] LPCWSTR lpStringValue,
[in] int cchValue,
[out, optional] LPINT pcchFound,
[in, optional] LPNLSVERSIONINFO lpVersionInformation,
[in, optional] LPVOID lpReserved,
[in, optional] LPARAM sortHandle
);
매개 변수
[in, optional] lpLocaleName
로캘 이름 또는 다음 미리 정의된 값 중 하나에 대한 포인터입니다.
[in] dwFindNLSStringFlags
찾기 작업의 세부 정보를 지정하는 플래그입니다. 이러한 플래그는 상호 배타적이며 FIND_FROMSTART 기본값입니다. 애플리케이션은 다음 표에 정의된 필터링 플래그를 사용하여 찾기 플래그 중 하나만 지정할 수 있습니다. 애플리케이션에서 플래그를 지정하지 않으면 함수는 지정된 로캘에 대한 기본 비교를 사용합니다. 애플리케이션에서 정렬 처리에서 설명한 대로 이진 비교 모드는 없습니다.
애플리케이션은 찾기 플래그와 함께 아래에 정의된 필터링 플래그를 사용할 수 있습니다.
[in] lpStringSource
함수가 lpStringValue로 지정된 문자열을 검색하는 원본 문자열에 대한 포인터입니다.
[in] cchSource
lpStringSource로 표시된 문자열의 종료 null 문자를 제외한 문자의 크기입니다. 애플리케이션은 이 매개 변수에 대해 0 또는 -1 이외의 음수를 지정할 수 없습니다. 애플리케이션은 소스 문자열이 null로 종료되고 함수가 크기를 자동으로 계산해야 하는 경우 -1을 지정합니다.
[in] lpStringValue
함수가 원본 문자열에서 검색하는 검색 문자열에 대한 포인터입니다.
[in] cchValue
lpStringValue로 표시된 문자열의 종료 null 문자를 제외한 문자의 크기입니다. 애플리케이션은 이 매개 변수에 대해 0 또는 -1 이외의 음수를 지정할 수 없습니다. 검색 문자열이 null로 종료되고 함수가 크기를 자동으로 계산해야 하는 경우 애플리케이션은 -1을 지정합니다.
[out, optional] pcchFound
함수가 찾은 문자열의 길이를 포함하는 버퍼에 대한 포인터입니다. 문자열은 검색 문자열보다 길거나 짧을 수 있습니다. 함수가 검색 문자열을 찾지 못하면 이 매개 변수는 수정되지 않습니다.
함수는 이 매개 변수에서 NULL 을 검색할 수 있습니다. 이 경우 함수는 찾은 문자열의 길이가 원본 문자열의 길이와 다른지 표시하지 않습니다.
pcchFound의 값은 cchValue에 제공된 값과 동일한 경우가 많지만 다음과 같은 경우에 다를 수 있습니다.
- cchValue에 제공된 값은 음수입니다.
- 문자열은 동일하지만 길이가 다릅니다. 예를 들어 "A" 및 "결합 링"(U+0041 U+030A)은 "A 링"(U+00c5)과 동일합니다.
[in, optional] lpVersionInformation
예약; 은 NULL이어야 합니다.
[in, optional] lpReserved
예약; 은 NULL이어야 합니다.
[in, optional] sortHandle
예약되었습니다. 0이어야 합니다.
반환 값
성공하면 lpStringSource 가 나타내는 원본 문자열에 0 기반 인덱스 를 반환합니다. pcchFound의 값과 함께 이 인덱스 는 원본 문자열에서 찾은 전체 문자열의 정확한 위치를 제공합니다. 반환 값 0은 원본 문자열에 대한 오류 없는 인덱스이며 일치하는 문자열은 오프셋 0의 원본 문자열에 있습니다.
함수가 성공하지 못하면 -1을 반환합니다. 확장된 오류 정보를 가져오기 위해 애플리케이션은 다음 오류 코드 중 하나를 반환할 수 있는 GetLastError를 호출할 수 있습니다.
- ERROR_INVALID_FLAGS. 플래그에 제공된 값이 잘못되었습니다.
- ERROR_INVALID_PARAMETER. 매개 변수 값이 잘못되었습니다.
- ERROR_SUCCESS. 작업이 성공적으로 완료되었지만 결과가 생성되지 않았습니다.
설명
이 함수는 검색 방향, 문자 동등성 필터링 및 로캘별 필터링을 비롯한 다양한 검색 옵션을 제공합니다. 동등성은 함수 호출에 지정된 로캘 및 플래그에 따라 달라집니다. 필터링 플래그는 검색 결과를 변경할 수 있습니다. 예를 들어 검색을 수행할 때 함수가 대/소문자 또는 분음 부호를 무시하면 잠재적 일치 항목이 증가합니다.
기본적으로 이 함수는 로 캘 매개 변수가 터키어(터키) 또는 아제르바이잔어(아제르바이잔)를 지정하는 경우에도 소문자 "i"를 대문자 "I"에 매핑합니다. 터키어 또는 아제르바이잔어에 대해 이 동작을 재정의하려면 애플리케이션에서 NORM_LINGUISTIC_CASING 지정해야 합니다. 이 플래그가 올바른 로캘에 대해 지정된 경우 "ı"(소문자 점 없는 I)는 "I"(대문자 점 없는 I)의 소문자 형식이고 "i"(소문자 점선 I)는 소문자 형식인 "ı"(대문자 점선 I)입니다.
많은 스크립트(특히 라틴어 스크립트)의 경우 NORM_IGNORENONSPACE LINGUISTIC_IGNOREDIACRITIC 일치하고 NORM_IGNORECASE 다음과 같은 예외를 제외하고 LINGUISTIC_IGNORECASE 일치합니다.
- NORM_IGNORENONSPACE 분음 부호인지 여부에 관계없이 보조 구분을 무시합니다. 한국어, 일본어, 중국어, 인덱스 언어 등에 대한 스크립트는 분음 부호 이외의 목적으로 이러한 구분을 사용합니다. LINGUISTIC_IGNOREDIACRITIC 단순히 두 번째 정렬 가중치를 무시하는 대신 실제 분음 부호만 무시합니다.
- NORM_IGNORECASE 실제로 언어적 사례인지 여부에 관계없이 3차 구분을 무시합니다. 예를 들어 아랍어 및 인딕 스크립트에서 이 플래그는 문자의 대체 형식을 구분합니다. 그러나 차이점은 언어 사례에 해당하지 않습니다. LINGUISTIC_IGNORECASE 세 번째 정렬 가중치를 무시하는 대신 실제 언어 대/소문자만 무시합니다.
이 함수는 성공한 경우에도 SetLastError 를 호출하는 몇 안 되는 NLS 함수 중 하나입니다. 검색 문자열과 일치하지 않을 때 스레드의 마지막 오류를 지우기 위해 이 호출을 수행합니다. 그러면 GetLastError에서 반환된 값이 지워지게 됩니다.
Windows 8부터: 앱이 Windows.Globalization 네임스페이스에서 이 함수에 언어 태그를 전달하는 경우 먼저 ResolveLocaleName을 호출하여 태그를 변환해야 합니다.
요구 사항
| 지원되는 최소 클라이언트 | Windows Vista [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2008 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | winnls.h(Windows.h 포함) |
| 라이브러리 | Kernel32.lib |
| DLL | Kernel32.dll |