共用方式為


FindNLSStringEx 函式 (winnls.h)

在名稱所指定地區設定的另一個 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

另請參閱

CompareStringEx

FindNLSString

處理應用程式中的排序

LCMapStringEx

國家語言支援

國家語言支援函式

安全性考慮:國際功能