mozilla/nsprpub/pr/include/prtime.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is the Netscape Portable Runtime (NSPR).
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998-2000
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 /*
  39  *----------------------------------------------------------------------
  40  *
  41  * prtime.h --
  42  *
  43  *     NSPR date and time functions
  44  *
  45  *-----------------------------------------------------------------------
  46  */
  47
  48 #ifndef prtime_h___
  49 #define prtime_h___
  50
  51 #include "prlong.h"
  52
  53 PR_BEGIN_EXTERN_C
  54
  55 /**********************************************************************/
  56 /************************* TYPES AND CONSTANTS ************************/
  57 /**********************************************************************/
  58
  59 #define PR_MSEC_PER_SEC         1000UL
  60 #define PR_USEC_PER_SEC         1000000UL
  61 #define PR_NSEC_PER_SEC         1000000000UL
  62 #define PR_USEC_PER_MSEC        1000UL
  63 #define PR_NSEC_PER_MSEC        1000000UL
  64
  65 /*
  66  * PRTime --
  67  *
  68  *     NSPR represents basic time as 64-bit signed integers relative
  69  *     to midnight (00:00:00), January 1, 1970 Greenwich Mean Time (GMT).
  70  *     (GMT is also known as Coordinated Universal Time, UTC.)
  71  *     The units of time are in microseconds. Negative times are allowed
  72  *     to represent times prior to the January 1970 epoch. Such values are
  73  *     intended to be exported to other systems or converted to human
  74  *     readable form.
  75  *
  76  *     Notes on porting: PRTime corresponds to time_t in ANSI C.  NSPR 1.0
  77  *     simply uses PRInt64.
  78  */
  79
  80 typedef PRInt64 PRTime;
  81
  82 /*
  83  * Time zone and daylight saving time corrections applied to GMT to
  84  * obtain the local time of some geographic location
  85  */
  86
  87 typedef struct PRTimeParameters {
  88     PRInt32 tp_gmt_offset;     /* the offset from GMT in seconds */
  89     PRInt32 tp_dst_offset;     /* contribution of DST in seconds */
  90 } PRTimeParameters;
  91
  92 /*
  93  * PRExplodedTime --
  94  *
  95  *     Time broken down into human-readable components such as year, month,
  96  *     day, hour, minute, second, and microsecond.  Time zone and daylight
  97  *     saving time corrections may be applied.  If they are applied, the
  98  *     offsets from the GMT must be saved in the 'tm_params' field so that
  99  *     all the information is available to reconstruct GMT.
 100  *
 101  *     Notes on porting: PRExplodedTime corrresponds to struct tm in
 102  *     ANSI C, with the following differences:
 103  *       - an additional field tm_usec;
 104  *       - replacing tm_isdst by tm_params;
 105  *       - the month field is spelled tm_month, not tm_mon;
 106  *       - we use absolute year, AD, not the year since 1900.
 107  *     The corresponding type in NSPR 1.0 is called PRTime.  Below is
 108  *     a table of date/time type correspondence in the three APIs:
 109  *         API          time since epoch          time in components
 110  *       ANSI C             time_t                  struct tm
 111  *       NSPR 1.0           PRInt64                   PRTime
 112  *       NSPR 2.0           PRTime                  PRExplodedTime
 113  */
 114
 115 typedef struct PRExplodedTime {
 116     PRInt32 tm_usec;                /* microseconds past tm_sec (0-99999)  */
 117     PRInt32 tm_sec;             /* seconds past tm_min (0-61, accomodating
 118                                    up to two leap seconds) */
 119     PRInt32 tm_min;             /* minutes past tm_hour (0-59) */
 120     PRInt32 tm_hour;            /* hours past tm_day (0-23) */
 121     PRInt32 tm_mday;            /* days past tm_mon (1-31, note that it
 122                                                 starts from 1) */
 123     PRInt32 tm_month;           /* months past tm_year (0-11, Jan = 0) */
 124     PRInt16 tm_year;            /* absolute year, AD (note that we do not
 125                                                 count from 1900) */
 126
 127     PRInt8 tm_wday;                     /* calculated day of the week
 128                                                 (0-6, Sun = 0) */
 129     PRInt16 tm_yday;            /* calculated day of the year
 130                                                 (0-365, Jan 1 = 0) */
 131
 132     PRTimeParameters tm_params;  /* time parameters used by conversion */
 133 } PRExplodedTime;
 134
 135 /*
 136  * PRTimeParamFn --
 137  *
 138  *     A function of PRTimeParamFn type returns the time zone and
 139  *     daylight saving time corrections for some geographic location,
 140  *     given the current time in GMT.  The input argument gmt should
 141  *     point to a PRExplodedTime that is in GMT, i.e., whose
 142  *     tm_params contains all 0's.
 143  *
 144  *     For any time zone other than GMT, the computation is intended to
 145  *     consist of two steps:
 146  *       - Figure out the time zone correction, tp_gmt_offset.  This number
 147  *         usually depends on the geographic location only.  But it may
 148  *         also depend on the current time.  For example, all of China
 149  *         is one time zone right now.  But this situation may change
 150  *         in the future.
 151  *       - Figure out the daylight saving time correction, tp_dst_offset.
 152  *         This number depends on both the geographic location and the
 153  *         current time.  Most of the DST rules are expressed in local
 154  *         current time.  If so, one should apply the time zone correction
 155  *         to GMT before applying the DST rules.
 156  */
 157
 158 typedef PRTimeParameters (PR_CALLBACK *PRTimeParamFn)(const PRExplodedTime *gmt);
 159
 160 /**********************************************************************/
 161 /****************************** FUNCTIONS *****************************/
 162 /**********************************************************************/
 163
 164 /*
 165  * The PR_Now routine returns the current time relative to the
 166  * epoch, midnight, January 1, 1970 UTC. The units of the returned
 167  * value are microseconds since the epoch.
 168  *
 169  * The values returned are not guaranteed to advance in a linear fashion
 170  * due to the application of time correction protocols which synchronize
 171  * computer clocks to some external time source. Consequently it should
 172  * not be depended on for interval timing.
 173  *
 174  * The implementation is machine dependent.
 175  * Cf. time_t time(time_t *tp) in ANSI C.
 176  */
 177 NSPR_API(PRTime)
 178 PR_Now(void);
 179
 180 /*
 181  * Expand time binding it to time parameters provided by PRTimeParamFn.
 182  * The calculation is envisoned to proceed in the following steps:
 183  *   - From given PRTime, calculate PRExplodedTime in GMT
 184  *   - Apply the given PRTimeParamFn to the GMT that we just calculated
 185  *     to obtain PRTimeParameters.
 186  *   - Add the PRTimeParameters offsets to GMT to get the local time
 187  *     as PRExplodedTime.
 188  */
 189
 190 NSPR_API(void) PR_ExplodeTime(
 191     PRTime usecs, PRTimeParamFn params, PRExplodedTime *exploded);
 192
 193 /* Reverse operation of PR_ExplodeTime */
 194 NSPR_API(PRTime)
 195 PR_ImplodeTime(const PRExplodedTime *exploded);
 196
 197 /*
 198  * Adjust exploded time to normalize field overflows after manipulation.
 199  * Note that the following fields of PRExplodedTime should not be
 200  * manipulated:
 201  *   - tm_month and tm_year: because the number of days in a month and
 202  *     number of days in a year are not constant, it is ambiguous to
 203  *     manipulate the month and year fields, although one may be tempted
 204  *     to.  For example, what does "a month from January 31st" mean?
 205  *   - tm_wday and tm_yday: these fields are calculated by NSPR.  Users
 206  *     should treat them as "read-only".
 207  */
 208
 209 NSPR_API(void) PR_NormalizeTime(
 210     PRExplodedTime *exploded, PRTimeParamFn params);
 211
 212 /**********************************************************************/
 213 /*********************** TIME PARAMETER FUNCTIONS *********************/
 214 /**********************************************************************/
 215
 216 /* Time parameters that suit current host machine */
 217 NSPR_API(PRTimeParameters) PR_LocalTimeParameters(const PRExplodedTime *gmt);
 218
 219 /* Time parameters that represent Greenwich Mean Time */
 220 NSPR_API(PRTimeParameters) PR_GMTParameters(const PRExplodedTime *gmt);
 221
 222 /*
 223  * Time parameters that represent the US Pacific Time Zone, with the
 224  * current daylight saving time rules (for testing only)
 225  */
 226 NSPR_API(PRTimeParameters) PR_USPacificTimeParameters(const PRExplodedTime *gmt);
 227
 228 /*
 229  * This parses a time/date string into a PRExplodedTime
 230  * struct. It populates all fields but it can't split
 231  * the offset from UTC into tp_gmt_offset and tp_dst_offset in
 232  * most cases (exceptions: PST/PDT, MST/MDT, CST/CDT, EST/EDT, GMT/BST).
 233  * In those cases tp_gmt_offset will be the sum of these two and
 234  * tp_dst_offset will be 0.
 235  * It returns PR_SUCCESS on success, and PR_FAILURE
 236  * if the time/date string can't be parsed.
 237  *
 238  * Many formats are handled, including:
 239  *
 240  *   14 Apr 89 03:20:12
 241  *   14 Apr 89 03:20 GMT
 242  *   Fri, 17 Mar 89 4:01:33
 243  *   Fri, 17 Mar 89 4:01 GMT
 244  *   Mon Jan 16 16:12 PDT 1989
 245  *   Mon Jan 16 16:12 +0130 1989
 246  *   6 May 1992 16:41-JST (Wednesday)
 247  *   22-AUG-1993 10:59:12.82
 248  *   22-AUG-1993 10:59pm
 249  *   22-AUG-1993 12:59am
 250  *   22-AUG-1993 12:59 PM
 251  *   Friday, August 04, 1995 3:54 PM
 252  *   06/21/95 04:24:34 PM
 253  *   20/06/95 21:07
 254  *   95-06-08 19:32:48 EDT
 255  *
 256  * If the input string doesn't contain a description of the timezone,
 257  * we consult the `default_to_gmt' to decide whether the string should
 258  * be interpreted relative to the local time zone (PR_FALSE) or GMT (PR_TRUE).
 259  * The correct value for this argument depends on what standard specified
 260  * the time string which you are parsing.
 261  */
 262
 263 NSPR_API(PRStatus) PR_ParseTimeStringToExplodedTime (
 264         const char *string,
 265         PRBool default_to_gmt,
 266         PRExplodedTime *result);
 267
 268 /*
 269  * This uses PR_ParseTimeStringToExplodedTime to parse
 270  * a time/date string and PR_ImplodeTime to transform it into
 271  * a PRTime (microseconds after "1-Jan-1970 00:00:00 GMT").
 272  * It returns PR_SUCCESS on success, and PR_FAILURE
 273  * if the time/date string can't be parsed.
 274  */
 275
 276 NSPR_API(PRStatus) PR_ParseTimeString (
 277         const char *string,
 278         PRBool default_to_gmt,
 279         PRTime *result);
 280
 281 /*
 282  * FIXME: should we also have a formatting function, such as asctime, ctime,
 283  * and strftime in standard C library?  But this would involve
 284  * internationalization issues.  Might want to provide a US English version.
 285  */
 286
 287 /**********************************************************************/
 288 /*********************** OLD COMPATIBILITYFUNCTIONS *******************/
 289 /**********************************************************************/
 290 #ifndef NO_NSPR_10_SUPPORT
 291
 292 /* Format a time value into a buffer. Same semantics as strftime() */
 293 NSPR_API(PRUint32) PR_FormatTime(char *buf, int buflen, const char *fmt,
 294                                            const PRExplodedTime *tm);
 295
 296 /* Format a time value into a buffer. Time is always in US English format, regardless
 297  * of locale setting.
 298  */
 299 NSPR_API(PRUint32)
 300 PR_FormatTimeUSEnglish( char* buf, PRUint32 bufSize,
 301                         const char* format, const PRExplodedTime* tm );
 302
 303 #endif /* NO_NSPR_10_SUPPORT */
 304
 305 PR_END_EXTERN_C
 306
 307 #endif /* prtime_h___ */