ms_time - Time conversion and string generation

       With software provided by http://2038bug.com/ (site offline, checked Oct. 2017)

       Chad Trabant
       IRIS Data Management Center

Libmseed API                                       2013/02/22                                         MS_TIME(3)

       These routines convert between various time formats.  Internally, libmseed represents time values as high
       precision  epoch  times  (hptime),  the  number  of ticks from the epoch: 00:00:00.00 1 January 1970.  By
       default a tick is defined as a microsecond (0.000001  seconds).   See  INTERNALHPTIME  below  for  more
       details.   Also  used  is  the  SEED  binary time represented by the following data structure (defined in
       libmseed.h):

       typedef struct btime_s
       {
         uint16_t  year;     /* year with century                 */
         uint16_t  day;      /* day, 1 - 366                      */
         uint8_t   hour;     /* hour, 0 - 23                      */
         uint8_t   min;      /* minute, 0 - 59                    */
         uint8_t   sec;      /* second, 0 - 60 (60 = leap second) */
         uint8_t   unused;   /* unused alignment byte             */
         uint16_t  fract;    /* fractional seconds, 0 - 9999      */
       } BTime;

       MS_EPOCH2HPTIME is a macro which converts a Unix/POSIX epoch time (elapsed seconds since 1 January  1970)
       to a hptime which are related by a simple scaling factor.

       MS_HPTIME2EPOCH  is  a macro which converts an hptime to a Unix/POSIX epoch time (elapsed seconds since 1
       January 1970) which are related by a simple scaling factor.  The result can be cast  to  an  integer,  in
       which  cast  no rounding is performed and sub-second precision is truncated, or can be cast into a double
       to get a double precision epoch time.

       ms_btime2hptime converts a btime to a hptime.

       ms_btime2isotimestr  generates  an  ISO  recommended  format  time  string  from   a   btime.    Example:
       '2001-07-29T12:38:00.0000'.   The  isotimestr  must  have  enough  room for 25 characters.  The resulting
       string will be NULL terminated.

       ms_btime2mdtimestr generates a month-day formatted  time  string  from  a  btime.   Example:  '2001-07-29
       12:38:00.0000'.   The  mdtimestr  must  have enough room for 25 characters.  The resulting string will be
       NULL terminated.

       ms_btime2seedtimestr   generates   a   SEED   format   time    string    from    a    btime.     Example:
       '2001,195,12:38:00.0000'.  The seedtimestr must have enough room for 23 characters.  The resulting string
       will be NULL terminated.

       ms_hptime2btime  converts  a  hptime  to a btime.  By default, hptime has microsecond precision whereas a
       BTime structure can only represent time to 0.0001 seconds.   The  precision  will  be  lost  during  this
       conversion, it will not be accounted for by rounding but will be truncated.  This behavior is by design.

       ms_hptime2isotimestr   generates  an  ISO  recommended  format  time  string  from  a  hptime.   Example:
       '2001-07-29T12:38:00.000000' or '2001-07-29T12:38:00'.  The isotimestr  must  have  enough  room  for  27
       characters.   The  subseconds  flag  controls  whether  the sub-second precision is included or not.  The
       resulting string will be NULL terminated.

       ms_hptime2mdtimestr generates a month-day formatted time string  from  a  hptime.   Example:  '2001-07-29
       12:38:00.000000'  or '2001-07-29 12:38:00'.  The isotimestr must have enough room for 27 characters.  The
       subseconds flag controls whether the sub-second precision is included or not.  The resulting string  will
       be NULL terminated.

       ms_hptime2seedtimestr    generates    a    SEED   format   time   string   from   a   hptime.    Example:
       '2001,195,12:38:00.000000' or  '2001,195,12:38:00'.   The  seedtimestr  must  have  enough  room  for  25
       characters.   The  subseconds  flag  controls  whether  the sub-second precision is included or not.  The
       resulting string will be NULL terminated.

       ms_time2hptime converts the time represented by  the  specified  year,  day,  hour,  min,  sec  and  usec
       (microseconds) to an hptime.  The range expected for each value is as follows:

       year : 1800 - 5000
       day  : 1 - 366  (366 = last day of leap year)
       hour : 0 - 23
       min  : 0 - 59
       sec  : 0 - 60   (60 = leap second)
       usec : 0 - 999999

       NOTE:  miniSEED  data  records  are  only  supported by limbseed with a year range between 1900 and 2100.
       These routines allow a wider range to support times for metadata, etc.

       ms_seedtimestr2hptime converts a SEED time string (day-of-year style) to a  high  precision  epoch  time.
       The  time  format  expected  is "YYYY[,DDD,HH,MM,SS.FFFFFF]", the delimiter can be a comma [,], dash [-],
       colon [:] or period [.].  Additionally a 'T' or space may be used to seprate the  day  and  hour  fields.
       The fractional seconds ("FFFFFF") must begin with a period [.] if present.

       ms_timestr2hptime  converts  a  generic  time string to a high precision epoch time.  SEED time format is
       "YYYY[/MM/DD HH:MM:SS.FFFF]", the delimiter can be a dash [-], comma[,], slash [/], colon [:], or  period
       [.].   Additionally  a 'T' or space may be used between the date and time fields.  The fractional seconds
       ("FFFFFF") must begin with a period [.] if present.

       For both ms_seedtimestr2hptime and ms_timestr2hptime the input time string may be "short", in which  case
       the  vales  omitted on the right hand side are assumed to be 0 (with the exception of month and day which
       are assumed to be 1).  The year is always required.  This characteristic means  that  these  time  string
       parsers  are  very  lenient and should not be used for validation or considered to be applying any strict
       validation.

       The time values internal to libmseed are defined as the number of ticks from  the  epoch:  00:00:00.00  1
       January  1970  and  often referred to as hptime.  By default a tick is defined as a microsecond (0.000001
       seconds).  The tick interval, and thus hptime precision, is controlled by the definition of HPTMODULUS in
       libmseed.h.  It is not recommended to change HPTMODULUS from the default value of 1000000.

       This epoch time system is similar to the  Unix/POSIX  epoch  times  except  that  the  ticks  are  higher
       precision than the 1-second ticks used in POSIX.  An hptime can always be converted to a Unix/POSIX epoch
       time  by  dividing hptime by HPTMODULUS (reducing the hptime to second precision) and vise-versa, see the
       documentation for the MS_HPTIME2EPOCH and MS_EPOCH2HPTIME macros above.

       As long as the system's gmtime function supports negative epoch times the internal time routines will  be
       able to represent times earlier than the epoch, i.e. times earlier than 1 January 1970.

       The  hptime  values  are  stored as 64-bit integers to allow high precision and avoid accumulation errors
       associated with floating point values.

       A special value defined as HPTERROR in libmseed.h is used to  represent  errors  for  routines  returning
       hptime.

       ms_time - Time conversion and string generation

ms_btime2hptime, ms_time2hptime, ms_seedtimestr2hptime and ms_timestr2hptime return a hptime  on  success
       and HPTERROR on error.

       ms_btime2isotimestr,  ms_btime2mdtimestr, ms_btime2seedtimestr, ms_hptime2isotimestr, ms_hptime2mdtimestr
       and ms_hptime2seedtimestr return a pointer to the resulting string or NULL on error.

       ms_hptime2btime returns 0 on success and -1 on error.

#include<libmseed.h>MS_EPOCH2HPTIME(X)X*(hptime_t)HPTMODULUSMS_HPTIME2EPOCH(X)X/HPTMODULUShptime_tms_btime2hptime(BTime*btime);char*ms_btime2isotimestr(BTime*btime,char*isotimestr);char*ms_btime2mdtimestr(BTime*btime,char*mdtimestr);char*ms_btime2seedtimestr(BTime*btime,char*seedtimestr);intms_hptime2btime(hptime_thptime,BTime*btime);char*ms_hptime2isotimestr(hptime_thptime,char*isotimestr,flagsubseconds);char*ms_hptime2mdtimestr(hptime_thptime,char*mdtimestr,flagsubseconds);char*ms_hptime2seedtimestr(hptime_thptime,char*seedtimestr,flagsubseconds);hptime_tms_time2hptime(intyear,intday,inthour,intmin,intsec,intusec);hptime_tms_seedtimestr2hptime(char*seedtimestr);hptime_tms_timestr2hptime(char*timestr);