distrib/share/tcl/help/tcl/files/bsearch

   1        bsearch fileId key ?retvar? ?compare_proc?
   2               Search  an  opened  file  fileId containing lines of text sorted
   3               into ascending order for a match.  Key contains  the  string  to
   4               match.   If  retvar is specified, then the line from the file is
   5               returned in retvar, and the command returns 1 if key was  found,
   6               and  0  if  it  wasn't.  If retvar is not specified or is a null
   7               name, then the command returns the line that was  found,  or  an
   8               empty string if key wasn't found.
   9
  10               By  default,  the  key  is matched against the first white-space
  11               separated field in each line.  The field is treated as an  ASCII
  12               string.   If compare_proc is specified, then it defines the name
  13               of a Tcl procedure to evaluate against each line read  from  the
  14               sorted  file  during the execution of the bsearch command.  Com-
  15               pare_proc takes two arguments, the key and a line extracted from
  16               the  file.  The compare routine should return a number less than
  17               zero if the key is less than the line, zero if the  key  matches
  18               the  line,  or  greater than zero if the key is greater than the
  19               line.  The file must be sorted in ascending order  according  to
  20               the  same criteria compare_proc uses to compare the key with the
  21               line, or erroneous results will occur.
  22
  23               This command does not  work  on  files  containing  binary  data
  24               (bytes of zero).