.TH bsearch() "" "" "General Function (libc)"
.PC "Search an array"
.B "#include <stdlib.h>"
\fBchar *bsearch(\fIkey, array, number, size, comparison\^\fB)\fR
\fBchar *\fIkey\^\fB, *\fIarray\^\fB;\fR
\fBsize_t \fInumber\^\fB, \fIsize\^\fB;\fR
\fBint (\fI*comparison\^\fB)();\fR
.PP
.II "binary search"
.II "array, search"
.II "search an array"
.B bsearch()
searches a sorted array for a given item.
.I item
points to the object sought.
.I array
points to the base of the array;
it has
.I number
elements, each of which is
.I size
bytes long.
Its elements must be sorted into ascending order before it is searched by
.BR bsearch() .
.PP
.I comparison
points to the function that compares
array elements.
.I comparison
must return zero if its arguments match, a number greater than zero if
the element pointed to by
.I arg1
is greater than the element pointed to by
.IR arg2 ,
and a number less than zero if the element pointed to by
.I arg1
is less than the element pointed to by
.IR arg2 .
.PP
.B bsearch()
returns a pointer to the array element that matches
.IR item .
If no element matches
.IR item ,
then
.B bsearch()
returns NULL.
If more than one element within
.I array
matches
.IR item ,
which element is matched is unspecified.
.SH Example
This example uses
.B bsearch()
to translate English into \*(QLbureaucrat\-ese\*(QR.
.DM
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
.DE
.DM
struct syntab {
	char *english, *bureaucratic;
} cdtab[] = {
/* The left column is in alphabetical order */
.DE
.DM
.ta 0.4i 1.5i
	"affect",	"impact",
	"after",	"subsequent to",
	"broke",	"revenue shortfall",
	"building",	"physical facility",
	"call",	"refer to as",
	"do",	"implement",
.DE
.DM
.ta 0.4i 1.5i
	"false",	"inoperative",
	"finish",	"finalize",
	"first",	"initial",
	"full",	"in-depth",
	"help",	"facilitate",
.DE
.DM
.ta 0.4i 1.5i
	"idiot",	"elected representative",
	"kill",	"terminate with extreme prejudice",
	"lie",	"inoperative statement",
	"order",	"prioritize",
	"talk",	"interpersonal communication",
	"then",	"at that point in time",
	"use",	"utilize"
};
.DE
.DM
int
comparator(key, item)
char *key;
struct syntab *item;
{
	return(strcmp(key, item->english));
}
.DE
.DM
main()
{
	struct syntab *ans;
	char buf[80];
.DE
.DM
	for(;;) {
		printf("Enter an English word: ");
		fflush(stdout);
.DE
.DM
		if(gets(buf) || !strcmp(buf, "quit") == NULL)
			break;
.DE
.DM
		if((ans = bsearch(buf, (char *)cdtab, 
				sizeof(cdtab)/ sizeof(struct syntab),
				sizeof(struct syntab),
				comparator)) == NULL)
			printf("%s not found\en");
.DE
.DM
		else
			printf("Don't say \e"%s\e"; say \e"%s\e"!\en",
				ans->english, ans->bureaucratic);
	}
.DE
.DM
	return(EXIT_SUCCESS);
}
.DE
.SH "See Also"
.Xr libc, libc
.Xr qsort(), qsort
.Xr stdlib.h stdlib.h
.br
\*(AS, \(sc7.10.6.2
.br
\*(PX, \(sc8.1
.SH Notes
The name
.I bsearch
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 bsearch()
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 bsearch()
bisects smaller and smaller regions of the array until it either
finds a match or can bisect no further.
.PP
It is important that the input
.I array
be sorted, or
.B bsearch()
will not function correctly.
