PRO binary_search_with_tol, v1, v2, tol, nmatch, lo_ind, hi_ind, NO_PAR_CHECK = no_par_check
; Description: This module searches for the set of values from an input vector of data
; "v2" that match within a tolerance "tol" of the value "v1". The module
; employs a fast binary search algorithm and it is for this reason that
; the vector of data values "v2" must be already sorted in to ascending
; order. The indices of the smallest and largest matching data values
; from "v2" are returned as the indices "lo_ind" and "hi_ind" respectively.
;
; Input Parameters:
;
; v1 - FLOAT/DOUBLE - The value for which matching data values are to be found.
; v2 - FLOAT/DOUBLE VECTOR - The set of data values to be searched for matches,
; already sorted into ascending order.
; tol - DOUBLE - The maximum difference between values that is considered a match.
;
; Output Parameters:
;
; nmatch - LONG - The number of values from "v2" that match within a tolerance "tol"
; of the value "v1".
; lo_ind - LONG - The index of the smallest matching data value from "v2". If there
; are no matching values, then "lo_ind" is returned with the value
; "-1".
; hi_ind - LONG - The index of the largest matching data value from "v2". If there
; are no matching values, then "hi_ind" is returned with the value
; "-1".
;
; Keywords:
;
; If the keyword NO_PAR_CHECK is set (as "/NO_PAR_CHECK"), then the program will not
; perform parameter checking on the input parameters, reducing program overheads.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 03/07/2008 - Module created (dmb)
;Perform parameter checking if not instructed otherwise
;Check that "v1" is a number
;Check that "v2" is vector containing number data
;Check that "tol" is a non-negative number
;If no parameter checking is performed, then determine the number of elements in "v2"
;Find the lowest subscript in the set of data values "v2" such that the corresponding
;value is greater than the value "v1" minus the search tolerance "tol"
;Find the highest subscript in the set of data values "v2" such that the corresponding
;value is less than the value "v1" plus the search tolerance "tol"
;Count the number of matching data values