; docformat = 'rst'
;+
;Given a target value and an array of values, returns the index of the
;nearest item to the target value without going over ("The Price Is Right"
;function).
;
;From The Price Is Right. A prize is shown without revealing its price.
;Four contestants guess its price, and the one nearest the actual price
;without going over is the winner. The prize value is $1234, and the 4 
;contestants guess the following: [123,500,1200,1235]. Contestant 2 
;(indexes start at zero like always in IDL) wins, even though contestant 3
;was closer. His guess was over the target.
;
;Special cases 
;If a number in Data exactly equals SearchValue, that one is it. If two or
;more values in sorted data are equal and it, then it will return the 
;higest index of those that are it. If all of them are over, the return
;value is -1.
;
; :Examples:
;   result = tpir(data, search_value)
;-
;+
; :Params:
;   Data : in, required, type=array of double
;     An array of values to examine. If the array is not sorted, use the
;     /unsorted keyword.
;   SearchValue : in, required, type=double 
;     The target value for the search. Must be a scalar.
;   
; :Keywords: 
;   unsorted : in, optional, type=boolean 
;     Must be set if the data is not assorted in ascending order. Does no
;     harm to set this keyword if the data is or might be sorted, except
;     that the function will take the time to sort the things internally.
;     Unsorted data not flagged as such will silently return the wrong
;     answer.
; 
; :Returns:
;   Returns the index value of the value that is closest and less than or 
;   equal to the search value.
;-
function tpir,Data,SearchValue,unsorted=unsorted
  if keyword_set(unsorted) then begin
    s=sort(Data);
    return,s[max(where(Data(s) le SearchValue))]
  end else begin
    return,max(where(Data le SearchValue))
  end
end