FindNLSStringEx 函式 (winnls.h)

發行項
08/27/2023

在名稱所指定地區設定的另一個 Unicode 字串中，找出 (寬字元的 Unicode 字串) 或其對等專案。

謹慎由於具有非常不同二進位標記法的字串可以做為相同的比較，因此此函式可能會引發特定的安全性考慮。如需詳細資訊，請參閱安全性考慮：國際功能中的比較函式討論。

語法

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為預設值。應用程式只能指定其中一個尋找旗標，其中任何一個篩選旗標定義于下一個資料表中。如果應用程式未指定旗標，函式會使用指定地區設定的預設比較。如在應用程式中處理排序中所述，沒有二進位比較模式。

值	意義
FIND_FROMSTART	搜尋字串，從字串的第一個字元開始。
FIND_FROMEND	以反向方向搜尋字串，從字串的最後一個字元開始。
FIND_STARTSWITH	測試以找出 lpStringValue 所指定的值是否為 lpStringSource所指示之來源字串中的第一個值。
FIND_ENDSWITH	測試以找出 lpStringValue 所指定的值是否為 lpStringSource所指出來源字串中的最後一個值。

應用程式可以使用下面定義的篩選旗標搭配尋找旗標。

值	意義
LINGUISTIC_IGNORECASE	請忽略搜尋中的大小寫，以語言方式適當。如需詳細資訊，請參閱＜備註＞一節。
LINGUISTIC_IGNOREDIACRITIC	請視語言適當地忽略讀音符號。如需詳細資訊，請參閱＜備註＞一節。注意當搭配分解字元使用時，這個旗標不一定會產生可預測的結果，也就是說，基底字元和一或多個非步調字元各有相異代碼點值的字元。
NORM_IGNORECASE	忽略搜尋中的大小寫。如需詳細資訊，請參閱＜備註＞一節。
NORM_IGNOREKANATYPE	請勿區分平假名和片假名字元。對應的平假名和片假名字元會比較為相等。
NORM_IGNORENONSPACE	忽略非步調字元。如需詳細資訊，請參閱＜備註＞一節。
NORM_IGNORESYMBOLS	忽略符號和標點符號。
NORM_IGNOREWIDTH	忽略半形和全形字元之間的差異，例如 C a t == cat。全形表單是中文和日文腳本中使用的格式區別。
NORM_LINGUISTIC_CASING	使用語言規則進行大小寫，而不是檔案系統規則， (預設) 。如需詳細資訊，請參閱＜備註＞一節。

[in] lpStringSource

來源字串的指標，函式會在其中搜尋 lpStringValue所指定的字串。

[in] cchSource

大小，以字元為單位，不包括 lpStringSource所指示之字串的終止 Null 字元。應用程式無法為此參數指定 -1 以外的 0 或任何負數。如果來源字串為 Null 終止，且函式應該自動計算大小，則應用程式會指定 -1。

[in] lpStringValue

搜尋字串的指標，函式會在來源字串中搜尋。

[in] cchValue

大小，以字元為單位，不包括終止 Null 字元的 lpStringValue所指示的字串。應用程式無法為此參數指定 -1 以外的 0 或任何負數。如果搜尋字串為 Null 終止，且函式應該自動計算大小，則應用程式會指定 -1。

[out, optional] pcchFound

緩衝區的指標，其中包含函式所尋找之字串的長度。字串可以比搜尋字串長或短。如果函式找不到搜尋字串，則不會修改此參數。

函式可以在此參數中擷取 Null 。在此情況下，函式不會指出找到字串的長度是否與來源字串的長度不同。

請注意， pcchFound 的值通常與 cchValue中提供的值相同，但在下列情況下可能會有所不同：

cchValue中提供的值是負數。
字串相等，但長度不同。例如，「A」加上「Combining Ring」 (U+0041 U+030A) 相當於「A Ring」 (U+00c5) 。

[in, optional] lpVersionInformation

保留;必須是 Null。

[in, optional] lpReserved

保留;必須是 Null。

[in, optional] sortHandle

保留;必須是 0。

傳回值

如果成功，會將以 0 為基礎的索引傳回 至 lpStringSource 所指示的來源字串。結合 pcchFound中的值，此索引會提供來源字串中整個找到字串的確切位置。傳回值為 0 是來源字串中無錯誤索引，比對字串位於位移 0 的來源字串中。

如果函式不成功，則傳回 -1。若要取得延伸的錯誤資訊，應用程式可以呼叫 GetLastError，這可以傳回下列其中一個錯誤碼：

ERROR_INVALID_FLAGS。為旗標提供的值無效。
ERROR_INVALID_PARAMETER。任何參數值都無效。
ERROR_SUCCESS。動作已順利完成，但不會產生任何結果。

備註

此函式提供各種搜尋選項，包括搜尋方向、字元等價篩選，以及地區設定特定的篩選。請注意，等價取決於函式呼叫中指定的地區設定和旗標。篩選旗標可以改變搜尋的結果。例如，當函式在執行搜尋時忽略大小寫或讀音符號時，可能會增加可能的相符專案。

根據預設，此函式會將小寫「i」對應至大寫「I」，即使 Locale 參數指定土耳其文 (土耳其文) 或亞塞亞塞亞 (亞塞塞亞) 也一樣。若要覆寫土耳其文或亞塞亞塞亞文的這個行為，應用程式應該指定NORM_LINGUISTIC_CASING。如果為正確的地區設定指定此旗標，「ı」 (小寫無點 I) 是「I」 (大寫無點 I) 和「i」 (小寫虛線 I) 是「ı」 (大寫虛線 I) 小寫形式。

對於許多腳本 (特別是拉丁腳本) ，NORM_IGNORENONSPACE會與LINGUISTIC_IGNOREDIACRITIC一致，而NORM_IGNORECASE與LINGUISTIC_IGNORECASE一致，但下列例外狀況如下：

NORM_IGNORENONSPACE忽略任何次要區別，不論其是否為聽音符號。韓文、日文、中文、索引語言和其他專案的腳本會針對讀音符號以外的用途使用此區別。 LINGUISTIC_IGNOREDIACRITIC只會忽略實際的讀音符號，而不只是忽略第二個排序權數。
NORM_IGNORECASE會忽略任何第三個區別，不論是否實際是語言案例。例如，在阿拉伯文和索引腳本中，此旗標會區分字元的替代形式。不過，差異不會對應至語言案例。 LINGUISTIC_IGNORECASE只會忽略實際的語言大小寫，而不是忽略第三個排序權數。

相較于其他 NLS API 函式，傳回 0 表示失敗，如果失敗，此函式會傳回 -1。成功時，它會傳回以 0 為基礎的索引。使用此索引可協助函式避免跨一個錯誤和一個字元緩衝區溢位。

此函式是數個 NLS 函式之一，即使在成功時仍會呼叫 SetLastError 。它會線上程無法比對搜尋字串時，進行此呼叫以清除執行緒中的最後一個錯誤。這會清除 GetLastError傳回的值。

從 Windows 8 開始： 如果您的 app 會從 Windows.Globalization 命名空間將語言標記傳遞至此函式，則必須先呼叫 ResolveLocaleName來轉換標記。

規格需求


最低支援的用戶端	Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2008 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	winnls.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll