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 (dmb@ing.iac.es)
;
; 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