function nbtwn,array,lim1,lim2,outside=outside,gtr=gtr,less=less,inclusive=inclusive,where=where

;+
;
; NBTWN:
; Function that returns the number of elements in an array between two
; values, or -1 if no values exist.  Does other stuff too.
;
; Call Sequence:
; Result = NBTWN(ARRAY, LIM1 [, LIM2], [, /OUTSIDE] [, /GTR] 
;                [, /LESS] [, /INCLUSIVE] [, /WHERE])
;
; Inputs:
; ARRAY - Array to be searched.
; LIM1 - First limit.
; LIM2 - Second limit (optional when /gtr, /less are set)
;
; Returns:
; If two limits are specified, returns number of elements between two
; limits, or -1 if criteria are not satisfied.  If only one limit is
; specified, returns number greater or lower depending on /less or
; /gtr setting.  
;
; Keywords:
; OUTSIDE - Set /OUTSIDE to return number of elements outside the two
;           limits rather than the nubmer between the two limits.
; GTR - Set /GTR to return number of elements greater than LIM1.
; LESS - Set /LESS to return number of elements less than LIM1.
; INCLUSIVE - Set /INCL to include limits (use le/ge rather than
;             default lt/gt).
; WHERE - Returns where output array rather than n_elements(where(...))
;
; KP / May 2007
;
;-

; Check.
if (N_params() lt 2) then begin
  print,' NBTWN: Syntax - Result=NBTWN(array, limit1 [, limit2'
  print,'                 ,/outside ,/gtr ,/less]'
  return,'nbtwn.pro'
endif

; Assess problem type.
if (n_elements(lim2) eq 0) then begin
  if (~keyword_set(gtr) and ~keyword_set(less)) then begin
    message,' NBTWN: With one limit, /GTR or /LESS must be specified.'
  endif
  nlim=1 
endif else nlim=2

; Do appropriate where statement.
if keyword_set(outside) then out=1 else out=0
if keyword_set(inclusive) then inc=1 else inc=0
if (nlim eq 2) then begin
  ; Assess upper & lower limits.
  ulim = (lim1 > lim2)
  llim = (lim1 < lim2)
  ; Find wheres.
  case 1 of
    (out and inc):   w = where((array le llim) or (array ge ulim))
    (out and ~inc):  w = where((array lt llim) or (array gt ulim))
    (~out and inc):  w = where((array ge llim) and (array le ulim))
    (~out and ~inc): w = where((array gt llim) and (array lt ulim))
  endcase
endif
; (Setting /GTR or /LESS overrides NLIM=2.)
if keyword_set(gtr) then gtr=1 else gtr=0
if keyword_set(less) then less=1 else less=0
case 1 of
  (gtr and inc):    w = where(array ge lim1)
  (gtr and ~inc):   w = where(array gt lim1) 
  (less and inc):   w = where(array le lim1)
  (less and ~inc):  w = where(array lt lim1)
  (~gtr and ~less): w = w   ;(Do nothing if keywords not set.)
endcase

; Get number of elements that satisfy criteria.
if (w[0] eq -1) then n = -1 else n = n_elements(w)

; Return to user.
if keyword_set(where) then n=w
return,n
end