function binSearch ( $h, $n, $a=0, $b=-1, $m=false, $f=-1, $l=-1, $depth=0 )
        {
#-k     search array
#-      binary search of a sorted contiguous array of strings
#-      $h      - haystack
#-      $n      - needle
#-      $a      - start offset counting from 0 (default 0)
#-      $b      - bytes to test (default strlen($n) )
#-      $m      - FALSE return next greater (default); TRUE must find an exact match
#-      $f      - first array index (default first)
#-      $l      - last array index (default last)
#-      $depth  - recursion depth
#-
#-      return index of 1st one found, else error:
#-              -1 if entry not found
#-              -2 if param error (str offset falls outside string)
#-              -3 if recursion depth too great
#-              -4 if str is < the start of this set
#-              -5 if string is > the end of this set
#-
#-      sample call:
#-      $ret = binSearch ( $zips, '06790', 0, 6 );

        $maxDepth = 50;

        if ($b == -1) $b = strlen($n);
        if ($l == -1) $l = count($h)-1;
        if ($f == -1) $f = key($h);

        if ($depth == 0) { $n .= ' '; $b++; }   # append ' ' to force a search for the beginning of the set
        if ($depth > $maxDepth)
                {
                prt ( '<br>============== binSearch error -3 ==============' );
                prt ( 'binSearch hit maxdepth of ' . $maxDepth );
                return -3;
                }
        $depth++;

#               search is down to the last one
        if (($l-$f) < 2)
                {
                if ($m == true) return -1;
                else return $l;
                }

#               check the endpoints
        $sh = substr($h[$f], $a, $b);
        if (!strlen($sh))
                {
                prt ( '<br>============== binSearch error -2.1 ==============', 1 );
                prt ( '<br>str offset (' . $a . ' for ' . $b . ') of index ' . $f . ' falls outside string', 1 );
                prt ( '<br>string: [' . $h[$f] . ']', 1 );
                prt ( '<br>needle: [' . $n . ']', 1 );
                return -2;
                }
        $c = strcmp ( $sh, $n );
        if ($c > 0)
                {       # $sh > $n
                if ($m == true) return -4;
                else return $f;
                }
        if (!$c) return $f;

        $sh = substr($h[$l], $a, $b);
        if (!strlen($sh))
                {
                prt ( '<br>============== binSearch error -2.2 ==============', 1 );
                prt ( '<br>str offset (' . $a . ' for ' . $b . ') of index ' . $l . ' falls outside string', 1 );
                prt ( '<br>string: [' . $h[$l] . ']', 1 );
                prt ( '<br>needle: [' . $n . ']', 1 );
                return -2;
                }
        $c = strcmp ( $sh, $n );
        if ($c < 0) return -5;
        if (!$c) return $l;

        $i = round(($f + $l)/2);                # find midpoint

        $sh = substr($h[$i], $a, $b);
        if (!strlen($sh))
                {
                prt ( '<br>============== binSearch error -2.3 ==============', 1 );
                prt ( '<br>str offset (' . $a . ' for ' . $b . ') of index ' . $i . ' falls outside string', 1 );
                prt ( '<br>string: [' . $h[$i] . ']', 1 );
                prt ( '<br>needle: [' . $n . ']', 1 );
                return -2;
                }
        $c = strcmp ( $sh, $n );
        if (!$c) {
                        return $i; }
        elseif ($c < 0) { return $i = binSearch ( $h, $n, $a, $b, $m, $i, $l, $depth ); }
        else            { return $i = binSearch ( $h, $n, $a, $b, $m, $f, $i, $depth ); }
        }

?>