/***********************************************************************
 *
 * TITLE:	utc.h
 *
 * AUTHOR:	Kevin J. Miller, Ana Maria Guerrero
 *
 * DESCRIPTION:
 *	This module is part of the the SOE editor: soeedt.  It is a
 *	header file for the time conversion functions.
 *
 *				CHANGE HISTORY
 *
 * $Log: utc.h,v $
 * Revision 1.10  1994/04/30  02:18:12  kevin
 * port to ANSI
 *
 * Revision 1.9  1992/12/31  23:44:13  kevin
 * added Chris' get_hms() and getx_days() functions
 *
 * Revision 1.8  1992/02/05  23:04:50  kevin
 * added local time function
 *
 * Revision 1.7  1991/09/05  00:01:15  kevin
 * added functions to return integer values
 *
 * Revision 1.6  1991/07/18  20:59:54  kevin
 * added week functions
 *
 * Revision 1.5  1991/06/21  01:56:46  kevin
 * added m/d/y functions
 *
 * Revision 1.4  1991/04/24  23:53:51  kevin
 * added UTC_TEXT_LENGTH (including '\0')
 *
 * Revision 1.3  1991/04/12  00:15:09  kevin
 * added standard SFOC header
 *
 * Revision 1.2  1991/03/07  20:34:49  kevin
 * added getx_doy() and getx_year() functions
 *
 * Revision 1.1  1991/03/04  21:41:09  kevin
 * Initial revision
 *
 ***********************************************************************
 *
 * WARNINGS:
 *
 * EXTERNAL CALLABLE COMPONENTS (PUBLIC):
 *
 * GLOBALS:
 *
 * WAIVERS:
 *
 * NOTES:
 *
 * MANPAGE:
 *
 ***********************************************************************/

#ifndef utc_h
#define utc_h

#ifndef lint
static char rcsid_utc[] = 
    "$Id: utc.h,v 1.10 1994/04/30 02:18:12 kevin OEL $";
#endif

/*****************************************************************************
 *
 *				UTC ROUTINES
 *
 * To simplify time calculations, all times are stored as unsigned long
 * seconds since Jan 1, 1970 (just like UNIX time functions).  Leap years
 * are assumed for years divisible by four, so these routines will not be
 * valid for 2100 (but they will be vaid for 2000).  No leap seconds are
 * used.
 *
 * The symbol utc_val is typedef'ed to unsigned long.
 *
 * The constant UTC_INVALID is defined to be 0xffffffff;
 *
 * The form of the functions is one of the following:
 *
 *		set_	- set the utc value from a number
 *		setx_	- set the utc value from text
 *		get_	- get a number from the utc value
 *		getx_	- get text from the utc value
 *   
 * The function include:
 *
 *   void init_utc_resol(val)	set resolution for text output routines
 *   int val;			use UTC_SECONDS, UTC_MINUTES, ...
 *
 *   utc_val setx_utc(text)	standard utc text (year-doyThh:mm:ss) is
 *   char *text;		converted to utc_val.  If less significant
 *				fields are missing, they are assumed zero.
 *
 *   void get_utc(utc, year,	utc_val is converted to a series of integers
 *	doy, hour, min, sec)	The number of arguments required and used
 *   utc_val utc;		depends on the value of the resolution.
 *   int *year, *doy, *hour,
 *	*min, *sec;
 *
 *   void getx_utc(text, utc)	utc_val is converted to standard utc text
 *   char *text;		(year-doyThh:mm:ss).  If less significant
 *   utc_val utc;		fields are missing, they are assumed zero.
 *
 *   void getx_year(text, utc)	the 4 digit year text is extracted from the
 *   char *text;		input utc_val.
 *   utc_val utc;
 *
 *   int get_doy(utc)		the 3 digit day-of-year integer is extracted
 *   utc_val utc;		from the input utc_val.
 *
 *   void getx_doy(text, utc)	the 3 digit day-of-year text is extracted
 *   char *text;		from the input utc_val.
 *   utc_val utc;
 *
 *   int get_wkday(utc)		returns day of week (Monday is day 0)
 *   utc_val utc;		input time.
 *
 *   char *getx_wkday(utc)	returns day of week as static string
 *   utc_val utc;		input time.
 *
 *   utc_val set_mdy(m, d, y)	integer m/d/y is converted to utc_val.
 *   int m, d, y;		(m: 1-12, d: 1-31, y >= 1970).
 *
 *   void get_mdy(m, d, y, utc)	utc_val is converted to integer m/d/y.
 *   int *m, *d, *y;
 *   utc_val utc;
 *
 *   utc_val set_week(wk, yr)	returns the utc_val corresponding to the
 *   int wk, yr;		start of the wk/yr input.
 *
 *   void get_week(wk, yr, utc)	finds the wk/yr containing the input
 *   int *wk, *yr;		utc_val.
 *   utc_val utc;
 *
 *   int get_local_offset(utc,	return conversion for local time
 *	isdst_ptr, zone_ptr);	if isdst_ptr is not NULL, return a
 *   utc_val utc;		TRUE / FALSE for DST
 *   int *isdst_ptr;		if zone_ptr is not NULL, return the
 *   char zone_ptr[4];		time zone
 *
 *   void get_hms(hrs, min,	return integer hh:mm:ss
 *	sec, tval)
 *   int *hrs, *min, *sec;	returned time
 *   utc_val utc;		input time value
 *
 *   void getx_days(days, utc)	return  digit number of days text
 *   char *days;		returned days text string
 *   utc_val utc;		input time value
 *
 ****************************************************************************/

/*
 * utc value type (seconds from 1970-001)
 */
typedef unsigned long utc_val;

/*
 * invalid utc value
 */
#define UTC_INVALID 0xffffffffL

/*
 * constants used to set resolution
 */
#define UTC_SECONDS 0
#define UTC_MINUTES 1
#define UTC_HOURS 2
#define UTC_DAYS 3

/*
 * constants useful for calculations
 */
#define UTC_ONE_SECOND 1L
#define UTC_ONE_MINUTE 60L
#define UTC_ONE_HOUR 3600L
#define UTC_ONE_DAY 86400L
#define UTC_ONE_STD_YEAR 31536000L
#define UTC_ONE_LEAP_YEAR 31622400L

/*
 * length of full (YYYY-DDDTHH:MM:SS) utc text string
 */
#define UTC_TEXT_LENGTH 18

/*
 * global function prototypes
 */
extern void init_utc_resol(int);
extern utc_val setx_utc(char []);
extern void get_utc(utc_val, int *, int *, ...);
extern void getx_utc(char [], utc_val);
extern void getx_year(char [], utc_val);
extern int get_doy(utc_val);
extern void getx_doy(char [], utc_val);
extern int get_wkday(utc_val);
extern char *getx_wkday(utc_val);
extern utc_val set_mdy(int, int, int);
extern void get_mdy(int *, int *, int *, utc_val);
extern utc_val set_week(int, int);
extern void get_week(int *, int *, utc_val);
extern int get_local_offset(utc_val, int *, char *);
extern void get_hms(int *, int *, int *, utc_val);
extern void getx_days(char *, utc_val);

#endif