std::bsearch

出自cppreference.com
 
C++
 
算法庫
受約束算法及範圍上的算法 (C++20)
包含算法例如 ranges::copy, ranges::sort, ...
執行策略 (C++17)
排序和相關操作
劃分操作
排序操作
二分搜索操作（在已劃分範圍上）
集合操作（在有序範圍上）
歸併操作（在有序範圍上）
堆操作
最小/最大操作
(C++11)
(C++17)
字典序比較操作
(C++20)
排列操作
C 庫

數值運算
(C++11)                       
在未初始化內存上的操作
 
在標頭 <cstdlib> 定義 
void* bsearch( const void* key, const void* ptr, std::size_t count,
               std::size_t size, /* C 比较谓词 */* comp );
(1) 
void* bsearch( const void* key, const void* ptr, std::size_t count,
               std::size_t size, /* 比较谓词 */* comp );
(2) 
void* bsearch( void* key, const void* ptr, std::size_t count,
               std::size_t size, /* C 比较谓词 */* comp );
(3) (C++26 起) 
void* bsearch( void* key, const void* ptr, std::size_t count,
               std::size_t size, /* 比较谓词 */* comp );
(4) (C++26 起) 
extern "C" using /* C 比较谓词 */ = int(const void*, const void*);
(僅用於闡述*) 
extern "C++" using /* 比较谓词 */ = int(const void*, const void*);
(僅用於闡述*)

在 ptr 所指向的數組中尋找等於 key 所指向的元素的元素。數組含有 count 個 size 字節的元素，且必須相對於 key 所指向的對象劃分，即所有比較小於它的元素必須先出現於比較等於它的元素，而比較等於它者必須先出現於所有比較大於該關鍵對象的元素。完全排序的數組滿足這些要求。用 comp 所指的函數比較數組元素。

如果數組未以按照 comp 所用的相同原則相對於 key 升序劃分，那麼行為未定義。

如果數組含有多個元素會被 comp 指示等於被搜索元素，那麼函數返回哪個元素為其結果是未指定的。

參數

key - 指向要搜索的元素的指針
ptr - 指向要檢驗的數組的指針
count - 數組中元素的數量
size - 數組中每個元素的大小，以字節表示
comp - 比較函數。如果首個參數小於 第二個，那麼返回負整數值，如果首個參數大於 第二個，那麼返回正整數值，如果兩個參數等價，那麼返回零。作為首個實參傳遞 key，作為第二個實參傳遞來自數組的元素。

比較函數的簽名應等價於如下形式：

int cmp(const void *a, const void *b);

該函數必須不修改傳遞給它的對象，而且在調用比較相同對象時必須返回一致的結果，與它們在數組中的位置無關。

​

返回值

指向找到的元素的指針，或在找不到元素時返回空指針。

註解

無關乎名稱，C 或 POSIX 標準都不要求此函數用二分查找實現，或進行任何複雜度保證。

C++ 標準庫提供的兩個重載互不相同，因為形參 comp 的類型互不相同（語言連結是類型的一部分）。

示例

運行此代碼
#include <array>
#include <cstdlib>
#include <iostream>

template<typename T>
int compare(const void *a, const void *b)
{
    const auto &arg1 = *(static_cast<const T*>(a));
    const auto &arg2 = *(static_cast<const T*>(b));
    const auto cmp = arg1 <=> arg2;
    return cmp < 0 ? -1
        :  cmp > 0 ? +1
        :  0;
}

int main()
{
    std::array arr{1, 2, 3, 4, 5, 6, 7, 8};
    
    for (const int key : {4, 8, 9})
    {
        const int* p = static_cast<int*>(
            std::bsearch(&key,
                arr.data(),
                arr.size(),
                sizeof(decltype(arr)::value_type),
                compare<int>));
        
        std::cout << "值 " << key;
        if (p)
            std::cout << "在位置 " << (p - arr.data())<< " 找到了";
        else
            std::cout << "没有找到";
    }
}

輸出： 

在位置 3 找到了值 4
在位置 7 找到了值 8
没有找到值 9

參閱

 對未指定類型的元素範圍排序
(函數) [編輯]
返回匹配特定鍵值的元素範圍
(函數模板) [編輯]
bsearch 的 C 文檔