bbsseeaarrcchh() -- General Function (libc)

Search an array
#iinncclluuddee <ssttddlliibb.hh>
cchhaarr *bbsseeaarrcchh(_k_e_y, _a_r_r_a_y, _n_u_m_b_e_r, _s_i_z_e, _c_o_m_p_a_r_i_s_o_n)
cchhaarr *_k_e_y, *_a_r_r_a_y;
ssiizzee_tt _n_u_m_b_e_r, _s_i_z_e;
iinntt (*_c_o_m_p_a_r_i_s_o_n)();

bbsseeaarrcchh() searches  a sorted array  for a given  item.  _i_t_e_m points  to the
object  sought.  _a_r_r_a_y  points to  the  base of  the array;  it has  _n_u_m_b_e_r
elements, each  of which is _s_i_z_e  bytes long.  Its elements  must be sorted
into ascending order before it is searched by bbsseeaarrcchh().

_c_o_m_p_a_r_i_s_o_n points to the function that compares array elements.  _c_o_m_p_a_r_i_s_o_n
must return zero if its arguments  match, a number greater than zero if the
element pointed to by _a_r_g_1 is  greater than the element pointed to by _a_r_g_2,
and a number less than zero  if the element pointed to by _a_r_g_1 is less than
the element pointed to by _a_r_g_2.

bbsseeaarrcchh() returns a  pointer to the array element that  matches _i_t_e_m. If no
element  matches  _i_t_e_m, then  bbsseeaarrcchh()  returns NULL.   If  more than  one
element within _a_r_r_a_y matches _i_t_e_m, which element is matched is unspecified.

_E_x_a_m_p_l_e
This example uses bbsseeaarrcchh() to translate English into ``bureaucrat-ese''.

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

struct syntab {
    char *english, *bureaucratic;
} cdtab[] = {
/* The left column is in alphabetical order */

    "affect",  "impact",
    "after",   "subsequent to",
    "broke",   "revenue shortfall",
    "building","physical facility",
    "call",    "refer to as",
    "do",      "implement",

    "false",   "inoperative",
    "finish",  "finalize",
    "first",   "initial",
    "full",    "in-depth",
    "help",    "facilitate",

    "idiot",   "elected representative",
    "kill",    "terminate with extreme prejudice",
    "lie",     "inoperative statement",
    "order",   "prioritize",
    "talk",    "interpersonal communication",
    "then",    "at that point in time",
    "use",     "utilize"
};

int
comparator(key, item)
char *key;
struct syntab *item;
{
    return(strcmp(key, item->english));
}

main()
{
    struct syntab *ans;
    char buf[80];

    for(;;) {
               printf("Enter an English word: ");
               fflush(stdout);

               if(gets(buf) || !strcmp(buf, "quit") == NULL)
               break;

               if((ans = bsearch(buf, (char *)cdtab,
                sizeof(cdtab)/ sizeof(struct syntab),
                sizeof(struct syntab),
                comparator)) == NULL)
               printf("%s not found\n");

               else
               printf("Don't say \"%s\"; say \"%s\"!\n",
                ans->english, ans->bureaucratic);
    }

    return(EXIT_SUCCESS);
}

_S_e_e _A_l_s_o
lliibbcc, qqssoorrtt(), ssttddlliibb.hh
ANSI Standard, section 7.10.6.2
POSIX Standard, section 8.1

_N_o_t_e_s
The name  _b_s_e_a_r_c_h implies that  this function performs a  binary search.  A
binary search looks at the midpoint  of the array, and compares it with the
element being sought.  If that element  matches, then the work is done.  If
it does not, then bbsseeaarrcchh() checks the midpoint of either the upper half of
the array or of the lower  half, depending upon whether the midpoint of the
array is  larger or smaller than the item  being sought.  bbsseeaarrcchh() bisects
smaller and smaller  regions of the array until it  either finds a match or
can bisect no further.

It  is important  that the  input _a_r_r_a_y  be sorted,  or bbsseeaarrcchh()  will not
function correctly.
