;+
; NAME:
;	TimeMonth
; PURPOSE:
;	Converts integer month to 3-char month and v.v.
; CATEGORY:
;	gen/idl/toolbox/time
; CALLING SEQUENCE:
	FUNCTION TimeMonth, month, check=check, year=year
; INPUTS:
;	month			scalar or array; type: integer or string
;						if integer then values must be between 1 and 12
;						if char then values must be one of
;						JAN,FEB,MAR,APR,MAY,JUN,JUL,AUG,SEP,OCT,NOV,DEC
;						(case insensitive).
; OPTIONAL INPUT PARAMETERS:
;	/check			if set then no conversion is done, but the input
;						array is checked to make sure all entries are valid.
;						The input array must be numeric (usually integer).
;	year=year		if /check is set, or numeric input is converted to string
;						then months outside the range 1-12 are mapped back
;						into the range 1-12. In this case 'year' is updated
;						accordingly where the month was changed.
;						(e.g. if month=14 and year=2003 on input, then
;						month=2 and year=2004 is returned).
; OUTPUTS:
;	mon 			same array type as input; type; string or integer
;						converted month array
; INCLUDE:
	@compile_opt.pro		; On error, return to caller
; CALLS:
;	InitVar, IsType, SyncArgs
; PROCEDURE:
; MODIFICATION HISTORY:
;	JAN-2004, Paul Hick (UCSD/CASS)
;	MAY-2008, Paul Hick (UCSD/CASS)
;		Integer month input is now mapped to range 1,12
;		instead of aborting when outside this range.
;	JUL-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
;		Added keyword 'year'.
;-

InitVar, check, /key
has_year = arg_present(year)

MONTHS	= ['','JAN','FEB','MAR','APR','MAY','JUN','JUL','AUG','SEP','OCT','NOV','DEC']

CASE 1 OF

check: BEGIN

	m = (((month mod 12)+11) mod 12)+1
	IF has_year THEN year += (month-m)/12

END

IsType(month,/string): BEGIN		; Month input as 3-char string

	cm = strupcase(month)			; Switch to uppercase
	m  = 0
	SyncArgs, cm, m

	FOR i=1,12 DO m += (cm EQ MONTHS[i])*i

	IF (where(m EQ 0))[0] NE -1 THEN message, 'invalid character input for month'

END

ELSE: BEGIN							; Numeric input

	m = round(month)				; Make m integer
	m = (((m mod 12)+11) mod 12)+1	; Map to [1,12]
	IF has_year THEN year += (round(month)-m)/12
	m = MONTHS[m]					; Convert to 3-element char

END
ENDCASE

RETURN, m  &  END