base/third_party/nspr/prtime.h

   1 /* Portions are Copyright (C) 2011 Google Inc */
   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  * CVS revision 3.10
  45  * This file contains definitions of NSPR's basic types required by
  46  * prtime.cc. These types have been copied over from the following NSPR
  47  * files prtime.h, prtypes.h(CVS revision 3.35), prlong.h(CVS revision 3.13)
  48  *
  49  *---------------------------------------------------------------------------
  50  */
  51
  52 #ifndef BASE_PRTIME_H__
  53 #define BASE_PRTIME_H__
  54
  55 #include "base/base_export.h"
  56 #include "base/third_party/nspr/prtypes.h"
  57
  58 #define PR_ASSERT DCHECK
  59
  60 #define LL_I2L(l, i)    ((l) = (PRInt64)(i))
  61 #define LL_MUL(r, a, b) ((r) = (a) * (b))
  62
  63 /**********************************************************************/
  64 /************************* TYPES AND CONSTANTS ************************/
  65 /**********************************************************************/
  66
  67 #define PR_MSEC_PER_SEC         1000UL
  68 #define PR_USEC_PER_SEC         1000000UL
  69 #define PR_NSEC_PER_SEC         1000000000UL
  70 #define PR_USEC_PER_MSEC        1000UL
  71 #define PR_NSEC_PER_MSEC        1000000UL
  72
  73 /*
  74  * PRTime --
  75  *
  76  *     NSPR represents basic time as 64-bit signed integers relative
  77  *     to midnight (00:00:00), January 1, 1970 Greenwich Mean Time (GMT).
  78  *     (GMT is also known as Coordinated Universal Time, UTC.)
  79  *     The units of time are in microseconds. Negative times are allowed
  80  *     to represent times prior to the January 1970 epoch. Such values are
  81  *     intended to be exported to other systems or converted to human
  82  *     readable form.
  83  *
  84  *     Notes on porting: PRTime corresponds to time_t in ANSI C.  NSPR 1.0
  85  *     simply uses PRInt64.
  86  */
  87
  88 typedef PRInt64 PRTime;
  89
  90 /*
  91  * Time zone and daylight saving time corrections applied to GMT to
  92  * obtain the local time of some geographic location
  93  */
  94
  95 typedef struct PRTimeParameters {
  96     PRInt32 tp_gmt_offset;     /* the offset from GMT in seconds */
  97     PRInt32 tp_dst_offset;     /* contribution of DST in seconds */
  98 } PRTimeParameters;
  99
 100 /*
 101  * PRExplodedTime --
 102  *
 103  *     Time broken down into human-readable components such as year, month,
 104  *     day, hour, minute, second, and microsecond.  Time zone and daylight
 105  *     saving time corrections may be applied.  If they are applied, the
 106  *     offsets from the GMT must be saved in the 'tm_params' field so that
 107  *     all the information is available to reconstruct GMT.
 108  *
 109  *     Notes on porting: PRExplodedTime corrresponds to struct tm in
 110  *     ANSI C, with the following differences:
 111  *       - an additional field tm_usec;
 112  *       - replacing tm_isdst by tm_params;
 113  *       - the month field is spelled tm_month, not tm_mon;
 114  *       - we use absolute year, AD, not the year since 1900.
 115  *     The corresponding type in NSPR 1.0 is called PRTime.  Below is
 116  *     a table of date/time type correspondence in the three APIs:
 117  *         API          time since epoch          time in components
 118  *       ANSI C             time_t                  struct tm
 119  *       NSPR 1.0           PRInt64                   PRTime
 120  *       NSPR 2.0           PRTime                  PRExplodedTime
 121  */
 122
 123 typedef struct PRExplodedTime {
 124     PRInt32 tm_usec;                /* microseconds past tm_sec (0-99999)  */
 125     PRInt32 tm_sec;             /* seconds past tm_min (0-61, accomodating
 126                                    up to two leap seconds) */
 127     PRInt32 tm_min;             /* minutes past tm_hour (0-59) */
 128     PRInt32 tm_hour;            /* hours past tm_day (0-23) */
 129     PRInt32 tm_mday;            /* days past tm_mon (1-31, note that it
 130                                                 starts from 1) */
 131     PRInt32 tm_month;           /* months past tm_year (0-11, Jan = 0) */
 132     PRInt16 tm_year;            /* absolute year, AD (note that we do not
 133                                                 count from 1900) */
 134
 135     PRInt8 tm_wday;                     /* calculated day of the week
 136                                                 (0-6, Sun = 0) */
 137     PRInt16 tm_yday;            /* calculated day of the year
 138                                                 (0-365, Jan 1 = 0) */
 139
 140     PRTimeParameters tm_params;  /* time parameters used by conversion */
 141 } PRExplodedTime;
 142
 143 /*
 144  * PRTimeParamFn --
 145  *
 146  *     A function of PRTimeParamFn type returns the time zone and
 147  *     daylight saving time corrections for some geographic location,
 148  *     given the current time in GMT.  The input argument gmt should
 149  *     point to a PRExplodedTime that is in GMT, i.e., whose
 150  *     tm_params contains all 0's.
 151  *
 152  *     For any time zone other than GMT, the computation is intended to
 153  *     consist of two steps:
 154  *       - Figure out the time zone correction, tp_gmt_offset.  This number
 155  *         usually depends on the geographic location only.  But it may
 156  *         also depend on the current time.  For example, all of China
 157  *         is one time zone right now.  But this situation may change
 158  *         in the future.
 159  *       - Figure out the daylight saving time correction, tp_dst_offset.
 160  *         This number depends on both the geographic location and the
 161  *         current time.  Most of the DST rules are expressed in local
 162  *         current time.  If so, one should apply the time zone correction
 163  *         to GMT before applying the DST rules.
 164  */
 165
 166 typedef PRTimeParameters (PR_CALLBACK *PRTimeParamFn)(const PRExplodedTime *gmt);
 167
 168 /**********************************************************************/
 169 /****************************** FUNCTIONS *****************************/
 170 /**********************************************************************/
 171
 172 NSPR_API(PRTime)
 173 PR_ImplodeTime(const PRExplodedTime *exploded);
 174
 175 /*
 176  * Adjust exploded time to normalize field overflows after manipulation.
 177  * Note that the following fields of PRExplodedTime should not be
 178  * manipulated:
 179  *   - tm_month and tm_year: because the number of days in a month and
 180  *     number of days in a year are not constant, it is ambiguous to
 181  *     manipulate the month and year fields, although one may be tempted
 182  *     to.  For example, what does "a month from January 31st" mean?
 183  *   - tm_wday and tm_yday: these fields are calculated by NSPR.  Users
 184  *     should treat them as "read-only".
 185  */
 186
 187 NSPR_API(void) PR_NormalizeTime(
 188     PRExplodedTime *exploded, PRTimeParamFn params);
 189
 190 /**********************************************************************/
 191 /*********************** TIME PARAMETER FUNCTIONS *********************/
 192 /**********************************************************************/
 193
 194 /* Time parameters that represent Greenwich Mean Time */
 195 NSPR_API(PRTimeParameters) PR_GMTParameters(const PRExplodedTime *gmt);
 196
 197 /*
 198  * This parses a time/date string into a PRTime
 199  * (microseconds after "1-Jan-1970 00:00:00 GMT").
 200  * It returns PR_SUCCESS on success, and PR_FAILURE
 201  * if the time/date string can't be parsed.
 202  *
 203  * Many formats are handled, including:
 204  *
 205  *   14 Apr 89 03:20:12
 206  *   14 Apr 89 03:20 GMT
 207  *   Fri, 17 Mar 89 4:01:33
 208  *   Fri, 17 Mar 89 4:01 GMT
 209  *   Mon Jan 16 16:12 PDT 1989
 210  *   Mon Jan 16 16:12 +0130 1989
 211  *   6 May 1992 16:41-JST (Wednesday)
 212  *   22-AUG-1993 10:59:12.82
 213  *   22-AUG-1993 10:59pm
 214  *   22-AUG-1993 12:59am
 215  *   22-AUG-1993 12:59 PM
 216  *   Friday, August 04, 1995 3:54 PM
 217  *   06/21/95 04:24:34 PM
 218  *   20/06/95 21:07
 219  *   95-06-08 19:32:48 EDT
 220  *
 221  * If the input string doesn't contain a description of the timezone,
 222  * we consult the `default_to_gmt' to decide whether the string should
 223  * be interpreted relative to the local time zone (PR_FALSE) or GMT (PR_TRUE).
 224  * The correct value for this argument depends on what standard specified
 225  * the time string which you are parsing.
 226  */
 227
 228 /*
 229  * This is the only funtion that should be called from outside base, and only
 230  * from the unit test.
 231  */
 232
 233 BASE_EXPORT PRStatus PR_ParseTimeString (
 234         const char *string,
 235         PRBool default_to_gmt,
 236         PRTime *result);
 237
 238 #endif  // BASE_PRTIME_H__