 |
 |
|
 |
|
|
[Contents] [Previous]
[Next] [Last]
Chapter 24
Date and Time
<< UNDER CONSTRUCTION >>
This chapter describes the date and time functions in NSPR.
Consider time instants as points along a time line. A time instant
is represented by its position on the time line relative to the origin,
called the epoch. NSPR defines the epoch to be midnight (00:00:00)
1 January 1970 UTC (Universal Coordinated Time). In this form, time
is just a point on the time line. There is no notion of timezone.
For human consumption, time can also be represented in the familiar
year, month, day, hour, minute, second components. In this form,
the timezone information is important. For example, what time is 8:00AM
1 May 1998? Without specifying the timezone, this is ambiguous.
The NSPR data type for the "broken-down" form of time has the timezone
information in it, so that its corresponding point in time is uniquely
specified.
NSPR provides functions to convert between the two representations of
time.
Types and Constants
Functions
Year 2000 Compliance
Types and Constants
PR_MSEC_PER_SEC,
PR_USEC_PER_SEC, PR_NSEC_PER_SEC, PR_USEC_PER_MSEC, PR_NSEC_PER_MSEC
Syntax
#include <prtime.h>
#define PR_MSEC_PER_SEC 1000UL
#define PR_USEC_PER_SEC 1000000UL
#define PR_NSEC_PER_SEC 1000000000UL
#define PR_USEC_PER_MSEC 1000UL
#define PR_NSEC_PER_MSEC 1000000UL
Description
These convenience macros are provided to improve the readability of your
code as well as to avoid mistakes in counting the number of zeros.
SEC stands for seconds, MSEC for milliseconds, USEC
for microseconds, and NSEC for nanoseconds.
PRTime
Syntax
#include <prtime.h>
typedef PRInt64 PRTime;
Description
PRTime is a 64-bit integer, representing the number of microseconds
since the NSPR epoch, midnight (00:00:00) 1 January 1970 Coordinated Universal
Time (UTC). A time after the epoch has a positive value, and a time
before the epoch has a negative value.
In NSPR, we use the more familiar term Greenwich Mean Time (GMT) in
place of UTC. Although UTC and GMT are not exactly the same, for
laymen like us it is probably okay to abuse the terminology.
Because PRTime is a 64-bit integer, one must use the LL macros
defined in prlong.h to manipulate PRTime values.
PRTimeParameters
Syntax
#include <prtime.h>
typedef struct PRTimeParameters {
PRInt32 tp_gmt_offset;
PRInt32 tp_dst_offset;
} PRTimeParameters;
Description
Each geographic location has a standard time zone, and if daylight saving
time (DST) is practiced, a daylight timezone.
The PRTimeParameters structure represents the local timezone
information in terms of the offset (in seconds) from GMT. The overall
offset is broken into two components:
-
tp_gmt_offset: the offset of the local standard time from GMT.
-
tp_dst_offset: If DST is in effect, the DST adjustment from the
local standard time. This is most commonly 1 hour, but may also be
30 minutes or some other amount. If DST is not in effect, the tp_dst_offset
component is 0.
Take the US Pacific Time Zone for example. It has both a standard
timezone (Pacific Standard Time, or PST) and a daylight timezone (Pacific
Daylight Time, or PDT).
In PST, the local time is 8 hours behind GMT, so tp_gmt_offset
is -28800 seconds. tp_dst_offset is 0, indicating
that daylight saving time is not in effect.
In PDT, the clock is turned forward by one hour, so the local time is
7 hours behind GMT. This is broken down as -8 + 1 hours, so tp_gmt_offset
is -28800 seconds, and tp_dst_offset is 3600 seconds.
Our second example is Japan. Japan is 7 hours ahead of GMT.
Japan does not use daylight saving time, so the only time zone is Japan
Standard Time (JST). In JST tp_gmt_offset is 25200 seconds,
and tp_dst_offset is 0.
PRExplodedTime
Syntax
#include <prtime.h>
typedef struct PRExplodedTime {
PRInt32 tm_usec;
PRInt32 tm_sec;
PRInt32 tm_min;
PRInt32 tm_hour;
PRInt32 tm_mday;
PRInt32 tm_month;
PRInt32 tm_year;
PRInt32 tm_wday;
PRInt32 tm_yday;
PRTimeParameters tm_params;
} PRExplodedTime;
Description
Time can be represented in the "broken-down" form by a PRExplodedTime
structure. PRExplodedTime has the familiar time components:
year, month, day of month, hour, minute, second. It also has a microsecond
component, as well as the day of week and the day of year. In addition,
PRExplodedTime contains a PRTimeParameters
structure representing the local timezone information, so that the time
point is non ambiguously specified.
The essential members of PRExplodedTime are:
-
tm_year: absolute year, AD. Note that we do not count from
1900 so as not to introduce year 2000 problems.
-
tm_month: number of months past tm_year. The range
is [0, 11]. (0 is January and 11 is December.)
-
tm_mday: the day of month. The range is [1, 31]. Note
that it starts from 1 as opposed to 0.
-
tm_hour: number of hours past tm_mday. The range
is [0, 23].
-
tm_min: number of minutes past tm_hour. The
range is [0, 59].
-
tm_sec: number of seconds past tm_min. The range
is [0, 61]. The values 60 and 61 are for accommodating up to two leap
seconds.
-
tm_usec: number of microseconds past tm_sec. The
range is [0, 999999].
-
tm_params: a PRTimeParameters structure representing
the local timezone information.
The nonessential members of PRExplodedTime are:
-
tm_wday: day of week. The range is [0, 6]. (0
is Sunday, 1 is Monday, and 6 is Saturday.)
-
tm_yday: day of year. The range is [0, 365].
(0 is the 1st of January.)
On input to NSPR functions, only the essential members of PRExplodedTime
must be specified. The two nonessential members (day of week
and day of year) are ignored by NSPR functions as input. When an
NSPR function returns a PRExplodedTime object or sets a PRExplodedTime
object as output, all of the PRExplodedTime members are set, including
the nonessential members.
PRTimeParamFn
Syntax
#include "prtime.h"
typedef PRTimeParameters (PR_CALLBACK_DECL *PRTimeParamFn) (const
PRExplodedTime *gmt);
Description
The type PRTimeParamFn represents a function that, when given
a time instant in GMT, returns the timezone information (offset from GMT
and DST offset) at that time instant. The reason we use a function
is for generality. In some geographic locations, whether DST is practiced
or not and the rule of de terming the dates on which DST starts and ends
have changed a few times. One way to encode all this information
is to use a function.
The two most often used PRTimeParamFn functions are PR_GMTParameters
and PR_LocalTimeParameters. PR_GMTParameters encodes
the rule of the GMT. So this is a trivial function -- for any input,
it returns a PRTimeParameters structure with both fields 0.
PR_LocalTimeParameters encodes the rule of the local timezone.
Functions
PR_Now
PR_ExplodeTime
PR_ImplodeTime
PR_NormalizeTIme
PR_LocalTimeParameters
and PR_GMTParameters
PR_ParseTimeString
PR_Now
Syntax
#include <prtime.h>
PRTime PR_Now(void);
Description
PR_Now returns the current time as number of microseconds since
the NSPR epoch, midnight (00:00:00) 1 January 1970 GMT.
One cannot assume that the values returned by PR_Now is
monotonically increasing because the system clock of the computer may be
reset. To obtain monotonically increasing time stamps suitable for
measuring elapsed time, use PR_IntervalNow.
See Also: PR_IntervalNow.
PR_ExplodeTime
Syntax
#include <prtime.h"
void PR_ExplodeTime(
PRTime usecs, PRTimeParamFn params, PRExplodedTime *exploded);
Description
PR_ExplodeTime converts PRTime to PRExplodedTime
in the specified timezone. The input argument usecs is the
PRTime value to be converted and params is the time parameter
function of the specified timezone. The output argument exploded
points to a PRExplodedTime object. On return, PR_ExplodeTime
fills the result in the object pointed to by exploded.
PR_ImplodeTime
Syntax
#include <prtime.h>
PRTime PR_ImplodeTime(const PRExplodedTime *exploded);
Description
PR_ImplodeTime converts PRExplodeTime to PRTime.
PR_NormalizeTime
Syntax
#include <prtime.h>
void PR_NormalizeTime(PR_ExplodedTime *time, PRTimeParamFn params);
Description
PR_NormalizeTime adjusts the fields of the PRExplodedTime
structure pointed to by time according to the time parameter function
params so that they are in the proper range. This function
can be used to solve the following problems:
-
To normalize the fields: For example, if you have a PRExplodedTime
object that represents the date 3 March 1998 and you want to say "forty
days from 3 March 1998", you can simply add 40 to the tm_mday
field and then call PR_NormalizeTime.
-
To compute the day of week: What day was 3 March 1998? You can set
tm_mday to 3, tm_month to 2, and tm_year to
1998, and all the other fields to 0, and call PR_NormalizeTime
with PR_GMTParameters. On return, tm_wday (and
tm_yday) will be set for you.
-
To convert from one timezone to another: If the input argument time
is in timezone A and the input argument params represents timezone
B, when PR_NormalizeTime returns, time will be
in timezone B.
PR_LocalTimeParameters
and PR_GMTParameters
#include <prtime.h>
PRTimeParameters PR_LocalTimeParameters(const PRExplodedTime *gmt);
PRTimeParameters PR_GMTParameters(const PRExplodedTime *gmt);
Description
You should seldom invoke the following two functions directly. Rather,
you pass them as arguments for PR_ExplodeTime and PR_NormalizeTime.
PR_ParseTimeString
Syntax
#include <prtime.h>
PRStatus PR_ParseTimeString(
const char *string, PRBool default_to_gmt, PRTime *result);
Description
Please see the comments in the header file prtime.h.
[Contents] [Previous]
[Next] [Last]
Last Updated: Tue Jul 14 18:35:36 PDT 1998
Copyright © 1998 Netscape
Communications Corporation
|
|
|
