;+
; NAME:
;	where_overlap
; PURPOSE:
;	Compares two set of numerical ranges and determines
;	where the two sets overlap. The set of overlapping
;	ranges is returned. Optionally, the input ranges
;	are returned with the overlaps removed.
; CATEGORY:
; CALLING SEQUENCE:
	FUNCTION where_overlap, r1_,r2_, $
		overlap	= overlap_	, $
		nn1		= nn1		, $
		rr1		= rr1_		, $
		nn2		= nn2		, $
		rr2		= rr2_
; INPUTS:
;	r1_,r2_		array[2,n] or array[2]
;				two sets of numerical ranges specified
;				as pairs of start and end points
; OUTPUTS:
;	result		scalar; integer
;				number of pairs in the set of overlapping ranges
; OPTIONAL OUTPUT PARAMETERS:
;	overlap=overlap
;				array[2,overlap], or aray[2]
;	nn1=nn1		# pairs in 1st set after removal of overlaps
;	rr1=rr1		array[2,nn1], or aray[2]
;				1st set after removal of overlaps
;	nn2=nn2		# pairs in 2nd set after removal of overlaps
;	rr2=rr2		array[2,nn2], or aray[2]
;				2nd set after removal of overlaps
; INCLUDE:
	@compile_opt.pro		; On error, return to caller
; CALLS:
;	destroyvar, merge_ranges
; PROCEDURE:
;	Both input ranges are first reduced in merge_ranges
; MODIFICATION HISTORY:
;	APR-2013, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
;-

n1 = merge_ranges(r1_, merge=r1)
n2 = merge_ranges(r2_, merge=r2)

i1 = 0
i2 = 0

WHILE i1 LT n1 AND i2 LT n2 DO BEGIN

	IF r1[0,i1] LT r2[0,i2] THEN BEGIN

		r = r1[*,i1]
		r[1] <= r2[0,i2]
		IF n_elements(rr1) EQ 0 THEN rr1 = r ELSE rr1 = [[rr1],[r]]

		IF r1[1,i1] LE r2[0,i2] THEN BEGIN
			i1++
			continue
		ENDIF
		r1[0,i1] = r2[0,i2]

	ENDIF ELSE IF r2[0,i2] LT r1[0,i1] THEN BEGIN

		r = r2[*,i2]
		r[1] <= r1[0,i1]
		IF n_elements(rr2) EQ 0 THEN rr2 = r ELSE rr2 = [[rr2],[r]]

		IF r2[1,i2] LE r1[0,i1] THEN BEGIN
			i2++
			continue
		ENDIF
		r2[0,i2] = r1[0,i1]

	ENDIF

	r = r1[*,i1]
	r[1] <= r2[1,i2]
	IF n_elements(overlap) EQ 0 THEN overlap = r ELSE overlap = [[overlap],[r]]

	IF r1[1,i1] LT r2[1,i2] THEN BEGIN
		r2[0,i2] = r1[1,i1]
		i1++
	ENDIF ELSE IF r2[1,i2] LT r1[1,i1] THEN BEGIN
		r1[0,i1] = r2[1,i2]
		i2++
	ENDIF ELSE BEGIN
		i1++
		i2++
	ENDELSE

ENDWHILE

IF i1 LT n1 THEN BEGIN
	r = r1[*,i1:n1-1]
	IF n_elements(rr1) EQ 0 THEN rr1 = r ELSE rr1 = [[rr1],[r]]
ENDIF

IF i2 LT n2 THEN BEGIN
	r = r2[*,i2:n2-1]
	IF n_elements(rr2) EQ 0 THEN rr2 = r ELSE rr2 = [[rr2],[r]]
ENDIF

nn1 = n_elements(rr1)/2
nn2 = n_elements(rr2)/2
nno = n_elements(overlap)/2

IF nn1 GT 0 THEN rr1_     = rr1		ELSE destroyvar, rr1_
IF nn2 GT 0 THEN rr2_     = rr2		ELSE destroyvar, rr2_
IF nno GT 0 THEN overlap_ = overlap	ELSE destroyvar, overlap_

RETURN, nno  &  END