Defined in header <stdlib.h> | ||
| (1) | ||
void* bsearch_s(constvoid*key,constvoid*ptr, rsize_t count, rsize_t size, int(*comp)(constvoid*,constvoid*,void*), | (2) | (since C11) |
| (3) | (since C23) | |
/*QVoid*/* bsearch_s(constvoid*key,/*QVoid*/*ptr, rsize_t count, rsize_t size, int(*comp)(constvoid*,constvoid*,void*), | (4) | (since C23) |
key in an array pointed to byptr. The array containscount elements ofsize bytes and must be partitioned with respect tokey, that is, all the elements that compare less than must appear before all the elements that compare equal to, and those must appear before all the elements that compare greater than the key object. A fully sorted array satisfies these requirements. The elements are compared using function pointed to bycomp. The behavior is undefined if the array is not already partitioned with respect to*key in ascending order according to the same criterion thatcomp uses.context is passed tocomp and that the following errors are detected at runtime and call the currently installedconstraint handler function:count orsize is greater thanRSIZE_MAXkey,ptr orcomp is a null pointer (unlesscount is zero)bsearch_s (and the corresponding type-generic macro)(since C23) is only guaranteed to be available if__STDC_LIB_EXT1__ is defined by the implementation and if the user defines__STDC_WANT_LIB_EXT1__ to the integer constant1 before including<stdlib.h>.T be a unqualified object type (includingvoid).ptr is of typeconst T*, the return type isconstvoid*.ptr is of typeT*, the return type isvoid*.If the array contains several elements thatcomp would indicate as equal to the element searched for, then it is unspecified which element the function will return as the result.
Direct usages of actual functions(1) and(2) are deprecated. | (since C23) |
Contents |
| key | - | pointer to the element to search for |
| ptr | - | pointer to the array to examine |
| count | - | number of element in the array |
| size | - | size of each element in the array in bytes |
| comp | - | comparison function which returns a negative integer value if the first argument isless than the second, a positive integer value if the first argument isgreater than the second and zero if the arguments are equivalent.key is passed as the first argument, an element from the array as the second.The signature of the comparison function should be equivalent to the following: int cmp(constvoid*a,constvoid*b); The function must not modify the objects passed to it and must return consistent results when called for the same objects, regardless of their positions in the array. |
| context | - | state of the comparator (e.g., collating sequence), passed tocomp as the third argument |
Despite the name, neither C nor POSIX standards require this function to be implemented using binary search or make any complexity guarantees.
Unlike other bounds-checked functions,bsearch_s does not treat arrays of zero size as a runtime constraint violation and instead indicates element not found (the other function that accepts arrays of zero size isqsort_s).
Untilbsearch_s, users ofbsearch often used global variables to represent the state of the comparator.
#include <stdlib.h>#include <stdio.h> struct data{int nr;charconst*value;} dat[]={{1,"Foo"},{2,"Bar"},{3,"Hello"},{4,"World"}}; int data_cmp(voidconst*lhs,voidconst*rhs){struct dataconst*const l= lhs;struct dataconst*const r= rhs; if(l->nr< r->nr)return-1;elseif(l->nr> r->nr)return1;elsereturn0; // return (l->nr > r->nr) - (l->nr < r->nr); // possible shortcut// return l->nr - r->nr; // erroneous shortcut (fails if INT_MIN is present)} int main(void){struct data key={ .nr=3};struct dataconst*res= bsearch(&key, dat,sizeof dat/sizeof dat[0],sizeof dat[0], data_cmp);if(res){printf("No %d: %s\n", res->nr, res->value);}else{printf("No %d not found\n", key.nr);}}
Output:
No 3: Hello
(C11) | sorts a range of elements with unspecified type (function)[edit] |
C++ documentation forbsearch | |
