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