lsearch.3

来自「<B>Digital的Unix操作系统VAX 4.2源码</B>」· 3 代码 · 共 100 行

.\" SCCSID: @(#)lsearch.3	8.1	9/11/90
.TH lsearch 3 
.SH Name
lsearch, lfind \- linear search and update
.SH Syntax
.B #include <search.h>
.br
.B #include <sys/types.h>
.PP
.B "void *lsearch (\fIkey, base, nelp, width, compar\fP)"
.br
.B void *\fIkey\fP;
.br
.B void *\fIbase\fP;
.br
.B size_t *\fInelp\fP;
.br 
.B size_t \fIwidth\fP; 
.br
.B int (*\fIcompar\fP)( );
.PP
.B "void *lfind (\fIkey, base, nelp, width, compar\fP)"
.br
.B void *\fIkey\fP;
.br
.B void *\fIbase\fP;
.br
.B size_t *\fInelp\fP; 
.br
.B size_t \fIwidth\fP; 
.br
.B int (*\fIcompar\fP)( );
.SH Description
.NXR "lsearch subroutine"
.NXR "lfind subroutine"
.NXR "linear search routine"
The
.PN lsearch
subroutine
is a linear search routine generalized from Knuth (6.1) Algorithm S.
It returns a pointer into a table indicating where
a datum may be found.
If the datum does not occur, it is added
at the end of the table.  The
.I key
points to the datum to be sought in the table.
The
.I base\^
points to the first element in the table.
The
.I nelp\^
points to an integer containing the current number of 
elements in the table.
The
.I width\^
is the size of an element in bytes.
The integer is incremented if the datum is added to the table.
The
.I compar\^
is the name of the comparison function which the user must supply
(strcmp, for example).
It is called with two arguments that point
to the elements being compared.
The function must return zero 
if the elements are equal and non-zero otherwise.
.PP
The
.PN lfind
subroutine is the same as lsearch except that if the datum is not found,
it is not added to the table.  Instead, a NULL pointer
is returned.
.NT
The pointers to the key and the element at the
base of the table should be
of type pointer-to-element,
and cast to type pointer-to-character.
.PP
The comparison function need not compare every byte,
so arbitrary data may be contained
in the elements in addition to the values being compared.
.PP
Although declared as type pointer-to-character,
the value returned should be cast into type pointer-to-element.
.NE
.SH Restrictions
Undefined results can occur if there is not enough room in the table to
add a new item.
.SH Return Values
If the searched for datum is found, both 
.PN lsearch 
and
.PN lfind
return a pointer to it.  Otherwise, 
.PN lfind
returns NULL and
.PN lsearch 
returns a pointer to the newly added element.
.SH See Also
bsearch(3), hsearch(3), tsearch(3)