std::basic_string<CharT,Traits,Allocator>::find

出自cppreference.com
 
C++
 
字符串庫
 
std::basic_string
 
size_type find( const basic_string& str, size_type pos = 0 ) const;
(1) (C++11 起為 noexcept)
(C++20 起為 constexpr)		 
size_type find( const CharT* s, size_type pos, size_type count ) const;
(2) (C++20 起為 constexpr) 
size_type find( const CharT* s, size_type pos = 0 ) const;
(3) (C++20 起為 constexpr) 
size_type find( CharT ch, size_type pos = 0 ) const;
(4) (C++11 起為 noexcept)
(C++20 起為 constexpr)		 
template< class StringViewLike >
size_type find( const StringViewLike& t,
                size_type pos = 0 ) const noexcept(/* 见下文 */);
(5) (C++17 起)
(C++20 起為 constexpr)

尋找首個等於給定字符序列的子串。搜索從 pos 開始，也就是說找到的子串不會從 pos 之前的位置開始。

1) 尋找等於 str 的首個子串。
2) 尋找首個等於範圍 [s, s + count) 的子串。此範圍可以包含空字符。
如果 [s, s + count) 不是有效範圍，那麼行為未定義。
3) 尋找首個等於 s 所指向的字符串的子串。該字符串的長度由首個空字符，通過 Traits::length(s) 確定。
如果 [s, s + Traits::length(s)) 不是有效範圍，那麼行為未定義。
4) 尋找首個字符 ch（由後述規則當作單字符子串）。
5) 如同用 std::basic_string_view<CharT, Traits> sv = t; 將 t 隱式轉換到字符串視圖 sv ，然後尋找首個等於字符串視圖 sv 的子串。
此重載只有在 std::is_convertible_v<const StringViewLike&,
std::basic_string_view<CharT, Traits>> 是 true 且 std::is_convertible_v<const StringViewLike&, const CharT*> 是 false 時才會參與重載決議。

正式而言，如果以下表達式都是 true，那麼在位置 xpos 找到 子串 str：

  • xpos >= pos
  • xpos + str.size() <= size()
  • 對於 str 中所有位置 n，Traits::eq(at(xpos + n), str.at(n))

特別是，這意味著

  • 只有在 pos <= size() - str.size() 時才能找到子串。
  • 在且僅在 pos <= size() 時才能在 pos 找到空子串。
  • 對於非空子串，如果 pos >= size()，那麼函數始終返回 npos。

參數

str - 要搜索的字符串
pos - 開始搜索的位置
count - 要搜索的子串長度
s - 指向要搜索的字符串的指針
ch - 要搜索的字符
t - 要搜索的對象（可轉換到 std::basic_string_view）

返回值

找到的子串的首字符位置，或在找不到這種子串時返回 npos。

異常

1,4) 不拋出。
5)
noexcept 說明：  
noexcept(std::is_nothrow_convertible_v<const T&, std::basic_string_view<CharT, Traits>>)

如果因為任何原因拋出了異常，那麼此函數無效果（強異常安全保證）。

示例

運行此代碼
#include <iomanip>
#include <iostream>
#include <string>

void print(int id, std::string::size_type n, std::string const& s)
{
    std::cout << id << ") ";
    if (std::string::npos == n)
        std::cout << "没有找到！n == npos\n";
    else
        std::cout << "在位置 n = " << n << " 找到，substr(" << n << ") = "
                  << std::quoted(s.substr(n)) << '\n';
}

int main()
{
    std::string::size_type n;
    std::string const s = "This is a string";  /*
                             ^  ^  ^
                             1  2  3           */
    
    // 从首个位置开始搜索
    n = s.find("is");
    print(1, n, s);
    
    // 从位置 5 开始搜索
    n = s.find("is", 5);
    print(2, n, s);
    
    // 寻找单个字符
    n = s.find('a');
    print(3, n, s);
    
    // 寻找单个字符
    n = s.find('q');
    print(4, n, s);
}

輸出： 

1) 在位置 n = 2 找到，substr(2) = "is is a string"
2) 在位置 n = 5 找到，substr(5) = "is a string"
3) 在位置 n = 8 找到，substr(8) = "a string"
4) 没有找到！n == npos

缺陷報告

下列更改行為的缺陷報告追溯地應用於以前出版的 C++ 標準。

缺陷報告 應用於 出版時的行為 正確行為
LWG 847 C++98 沒有異常安全保證 添加強異常安全保證
LWG 2064 C++11 重載 (3,4) 是 noexcept 的 移除
LWG 2946 C++17 重載 (5) 在某些情況下會導致歧義 通過使之為模板來避免
P1148R0 C++11
C++17 		重載 (4,5) 的 noexcept 意外地被 LWG2064/LWG2946 丟棄 恢復

參閱

 尋找字符子串的首次出現
(函數) [編輯]
在另一寬字符串中尋找寬字符串的首次出現
(函數) [編輯]
尋找字符的首次出現
(函數) [編輯]
尋找寬字符串中寬字符的首次出現
(函數) [編輯]
尋找子串的最後一次出現
(公開成員函數) [編輯]
尋找字符的首次出現
(公開成員函數) [編輯]
尋找字符的首次缺失
(公開成員函數) [編輯]
尋找字符的最後一次出現
(公開成員函數) [編輯]
尋找字符的最後一次缺失
(公開成員函數) [編輯]
在視圖中查找字符
(std::basic_string_view<CharT,Traits> 的公開成員函數) [編輯]
搜索元素範圍的首次出現
(函數模板) [編輯]