;+
; NAME:
;  rt_locate
; PURPOSE: (one line)
;  Search an ordered list by bisection
; DESCRIPTION:
;  Given an array xx[0..n-1], and given a value x, returns a value j
;  such that x is between xx[j] and xx[j+1]. 
;  xx must be monotonic, either increasing or decreasing. 
;  j=-1 or j=n-1 is returned to indicate that x is out of range.
; CATEGORY:
;  RT
; CALLING SEQUENCE:
;  j = rt_locate(xx, x)
; INPUTS:
;  xx - array, monotonic, either increasing or decreasing
;  x - the value to be found in xx
; OPTIONAL INPUT PARAMETERS:
;  none
; KEYWORD INPUT PARAMETERS:
;  none
; KEYWORD OUTPUT PARAMETERS:
;  none
; OUTPUTS:
;  j such that  x is between xx[j] and xx[j+1]. 
; COMMON BLOCKS:
; SIDE EFFECTS:
; RESTRICTIONS:
;  None
; PROCEDURE:
; 
;  Modifies from locate, numerical recipes
; 
; MODIFICATION HISTORY:
;  Written 2004 May 8, Leslie Young SwRI
;  based on locate, Numerical Recipes, Press et al.
;-

function rt_locate, xx, x 

    n = n_elements(xx)
    ascnd= (xx[n-1] gt xx[0])
    
    case 1 of
        x eq xx[n-1]: return, n-2
        (x le xx[0]) eq ascnd: return, -1
        (x gt xx[n-1]) eq ascnd: return, n-1
        else:
    endcase

    jl = -1                        
    ju = n                      
    while ( (ju-jl) gt 1) do begin
        jm=(ju+jl)/2
        if ( (x ge xx[jm]) eq ascnd) then begin
            jl=jm               
        endif else begin
            ju=jm              
        endelse
    endwhile

    return, jl

end