summaryrefslogtreecommitdiffstats
path: root/mimelib/doc/datetime.html
blob: 8461b260ebb28afa2a2f104c76f7da608a8964f8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
<HTML>
<HEAD>
  <TITLE> DwDateTime Man Page </TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H2>
  <FONT COLOR="navy"> NAME </FONT>
</H2>
<P>
DwDateTime -- Class representing an RFC-822 date-time
<H2>
  <FONT COLOR="navy"> SYNOPSIS </FONT>
</H2>
<PRE>class DW_EXPORT DwDateTime : public <A HREF="fieldbdy.html">DwFieldBody</A> {

public:

    <A HREF="datetime.html#DwDateTime">DwDateTime</A>();
    <A HREF="datetime.html#DwDateTime">DwDateTime</A>(const DwDateTime&amp; aDateTime);
    <A HREF="datetime.html#DwDateTime">DwDateTime</A>(const DwString&amp; aStr, DwMessageComponent* aParent=0);
    virtual ~DwDateTime();
    const DwDateTime&amp; <A HREF="datetime.html#op_eq">operator =</A> (const DwDateTime&amp; aDateTime);
    virtual void <A HREF="datetime.html#Parse">Parse</A>();
    virtual void <A HREF="datetime.html#Assemble">Assemble</A>();
    virtual DwMessageComponent* <A HREF="datetime.html#Clone">Clone</A>() const;
    DwUint32 <A HREF="datetime.html#AsUnixTime">AsUnixTime</A>() const;
    void <A HREF="datetime.html#FromUnixTime">FromUnixTime</A>(DwUint32 aTime);
    time_t <A HREF="datetime.html#AsCalendarTime">AsCalendarTime</A>() const;
    void <A HREF="datetime.html#FromCalendarTime">FromCalendarTime</A>(time_t aTime);
    DwInt32 <A HREF="datetime.html#DateAsJulianDayNum">DateAsJulianDayNum</A>() const;
    void <A HREF="datetime.html#DateFromJulianDayNum">DateFromJulianDayNum</A>(DwInt32 aJdn);
    DwInt32 <A HREF="datetime.html#TimeAsSecsPastMidnight">TimeAsSecsPastMidnight</A>() const;
    void <A HREF="datetime.html#TimeFromSecsPastMidnight">TimeFromSecsPastMidnight</A>(DwInt32 aSecs);
    int <A HREF="datetime.html#Year">Year</A>() const;
    void <A HREF="datetime.html#SetYear">SetYear</A>(int aYear);
    int <A HREF="datetime.html#Month">Month</A>() const;
    void <A HREF="datetime.html#SetMonth">SetMonth</A>(int aMonth);
    int <A HREF="datetime.html#Day">Day</A>() const;
    void <A HREF="datetime.html#SetDay">SetDay</A>(int aDay);
    int <A HREF="datetime.html#Hour">Hour</A>() const;
    void <A HREF="datetime.html#SetHour">SetHour</A>(int aHour);
    int <A HREF="datetime.html#Minute">Minute</A>() const;
    void <A HREF="datetime.html#SetMinute">SetMinute</A>(int aMinute);
    int <A HREF="datetime.html#Second">Second</A>() const;
    void <A HREF="datetime.html#SetSecond">SetSecond</A>(int aSecond);
    int <A HREF="datetime.html#Zone">Zone</A>() const;
    void <A HREF="datetime.html#SetZone">SetZone</A>(int aZone);
    static void <A HREF="datetime.html#SetDefaultZone">SetDefaultZone</A>(int aZone);
    static DwDateTime* <A HREF="datetime.html#NewDateTime">NewDateTime</A>(const DwString&amp;, DwMessageComponent*);
    static DwDateTime* (*<A HREF="datetime.html#sNewDateTime">sNewDateTime</A>)(const DwString&amp;, DwMessageComponent*);

protected:

    void <A HREF="datetime.html#_FromUnixTime">_FromUnixTime</A>(DwUint32 aTime);
    void <A HREF="datetime.html#_FromCalendarTime">_FromCalendarTime</A>(time_t aTime);
    int  mYear;
    int  mMonth;
    int  mDay;
    int  mHour;
    int  mMinute;
    int  mSecond;
    int  mZone;
    static int sDefaultZone;
    static int sIsDefaultZoneSet;

public:

    virtual void <A HREF="datetime.html#PrintDebugInfo">PrintDebugInfo</A>(ostream&amp; aStrm, int aDepth=0) const;
    virtual void <A HREF="datetime.html#CheckInvariants">CheckInvariants</A>() const;

protected:

    void _PrintDebugInfo(ostream&amp; aStrm) const;
};
</PRE>
<H2>
  <FONT COLOR="navy"> DESCRIPTION </FONT>
</H2>
<P>
<B><TT>DwDatetime</TT></B> represents a <I>date-time</I> as described in
RFC-822 and RFC-1123. The parse method for <B><TT>DwDateTime</TT></B> parses
the string representation to extract the year, month, day, hour, minute,
second, and time zone. <B><TT>DwDateTime</TT></B> provides member functions
to set or get the individual components of the date-time.
<H2>
  <FONT COLOR="navy"> Public Member Functions </FONT>
</H2>
<P>
<FONT COLOR="teal"><B> <A NAME="DwDateTime">DwDateTime</A>() <BR>
DwDateTime(const DwDateTime&amp; aDateTime) <BR>
DwDateTime(const DwString&amp; aStr, DwMessageComponent* aParent=0)
</B></FONT>
<P>
The first constructor is the default constructor, which assigns the current
date and time as reported by the operating system.
<P>
The second constructor is the copy constructor. The tqparent of the new
<B><TT>DwDateTime</TT></B> object is set to <B><TT>NULL</TT></B>.
<P>
The third constructor sets <B><TT>aStr</TT></B> as the
<B><TT>DwDateTime</TT></B> object's string representation and sets
<B><TT>aParent</TT></B> as its tqparent. The virtual member function
<B><TT>Parse()</TT></B> should be called after this constructor to extract
the date and time information from the string representation. Unless it is
<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of
a class derived from <B><TT>DwField</TT></B>.
<P>
<FONT COLOR="teal"><B> const DwDateTime&amp; <A NAME="op_eq">operator =</A>
(const DwDateTime&amp; aDateTime) </B></FONT>
<P>
This is the assignment operator, which sets this
<B><TT>DwDateTime</TT></B> object to the same value as
<B><TT>aDateTime</TT></B>.
<P>
<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT>
<P>
This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>,
executes the parse method for <B><TT>DwDateTime</TT></B> objects. The parse
method creates or updates the broken-down representation from the string
representation. For <B><TT>DwDateTime</TT></B> objects, the parse method
parses the string representation to extract the year, month, day, hour, minute,
second, and time zone.
<P>
This function clears the is-modified flag.
<P>
<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>()
</B></FONT>
<P>
This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>,
executes the assemble method for <B><TT>DwDateTime</TT></B> objects. It should
be called whenever one of the object's attributes is changed in order to
assemble the string representation from its broken-down representation. It
will be called automatically for this object by the tqparent object's
<B><TT>Assemble()</TT></B> member function if the is-modified flag is set.
<P>
This function clears the is-modified flag.
<P>
<FONT COLOR="teal"><B> virtual DwMessageComponent*
<A NAME="Clone">Clone</A>() const </B></FONT>
<P>
This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>,
creates a new <B><TT>DwDateTime</TT></B> on the free store that has the same
value as this <B><TT>DwDateTime</TT></B> object. The basic idea is that of
a virtual copy constructor.
<P>
<FONT COLOR="teal"><B> DwUint32 <A NAME="AsUnixTime">AsUnixTime</A>() const
</B></FONT>
<P>
Returns the date and time as a UNIX (POSIX) time, defined as the number of
seconds elapsed since 1 Jan 1970 00:00:00 UTC.
<P>
<FONT COLOR="teal"><B> void <A NAME="FromUnixTime">FromUnixTime</A>(DwUint32
aTime) </B></FONT>
<P>
Sets the date and time from <B><TT>aTime</TT></B>, interpreted as the number
of of seconds elapsed since 1 Jan 1970 00:00:00 UTC.
<P>
<FONT COLOR="teal"><B> time_t <A NAME="AsCalendarTime">AsCalendarTime</A>()
const </B></FONT>
<P>
Returns the date and time as a value of type <B><TT>time_t</TT></B> that
conforms to the native format returned by the <B><TT>time()</TT></B> ANSI
C function. On most UNIX systems, this function returns the same value as
<B><TT>AsUnixTime()</TT></B>. (For efficiency, use
<B><TT>AsUnixTime()</TT></B> instead of <B><TT>AsCalendarTime()</TT></B>
if possible).
<P>
<FONT COLOR="teal"><B> void
<A NAME="FromCalendarTime">FromCalendarTime</A>(time_t aTime) </B></FONT>
<P>
Sets the date and time from <B><TT>aTime</TT></B>, which is assumed to be
in a format compatible with the native <B><TT>time()</TT></B> ANSI C function.
For most UNIX systems, this function is the same as the function
<B><TT>FromUnixTime()</TT></B>. (For efficiency, use
<B><TT>FromUnixTime()</TT></B> instead of
<B><TT>FromCalendarTime()</TT></B> if possible).
<P>
<FONT COLOR="teal"><B> DwInt32
<A NAME="DateAsJulianDayNum">DateAsJulianDayNum</A>() const </B></FONT>
<P>
Returns the Julian Day Number, defined as the number of days elapsed since
1 Jan 4713 BC. The JDN is calculated directly from the values of the year,
month, and day; time zone information is ignored.
<P>
<FONT COLOR="teal"><B> void
<A NAME="DateFromJulianDayNum">DateFromJulianDayNum</A>(DwInt32 aJdn)
</B></FONT>
<P>
Sets the year, month, and day from <B><TT>aJdn</TT></B>, interpreted as a
Julian Day Number. By definition, the JDN is the number of days elapsed since
1 Jan 4713 BC. This member function ignores time zone information.
<P>
<FONT COLOR="teal"><B> DwInt32
<A NAME="TimeAsSecsPastMidnight">TimeAsSecsPastMidnight</A>() const
</B></FONT>
<P>
Returns the number of seconds past midnight. The value is calculated directly
from the values of the hour, minute, and second; time zone information is
ignored.
<P>
<FONT COLOR="teal"><B> void
<A NAME="TimeFromSecsPastMidnight">TimeFromSecsPastMidnight</A>(DwInt32 aSecs)
</B></FONT>
<P>
Sets the hour, minute, and second from <B><TT>aSecs</TT></B>, interpreted
as the number of seconds elapsed since midnight. This member function ignores
time zone information. The argument <B><TT>aSecs</TT></B> should be in the
range 0 to 86399, inclusive.
<P>
<FONT COLOR="teal"><B> int <A NAME="Year">Year</A>() const </B></FONT>
<P>
Returns the four digit year, e.g. 1997.
<P>
<FONT COLOR="teal"><B> void <A NAME="SetYear">SetYear</A>(int aYear)
</B></FONT>
<P>
Sets the year from <B><TT>aYear</TT></B>, which should be a four digit year.
<P>
<FONT COLOR="teal"><B> int <A NAME="Month">Month</A>() const </B></FONT>
<P>
Returns the month. Values range from 1 to 12.
<P>
<FONT COLOR="teal"><B> void <A NAME="SetMonth">SetMonth</A>(int aMonth)
</B></FONT>
<P>
Sets the month from <B><TT>aMonth</TT></B>, which should be in the range
1 to 12.
<P>
<FONT COLOR="teal"><B> int <A NAME="Day">Day</A>() const </B></FONT>
<P>
Returns the day of the month. Values range from 1 to 31.
<P>
<FONT COLOR="teal"><B> void <A NAME="SetDay">SetDay</A>(int aDay) </B></FONT>
<P>
Sets the day of the month from <B><TT>aDay</TT></B>.
<P>
<FONT COLOR="teal"><B> int <A NAME="Hour">Hour</A>() const </B></FONT>
<P>
Returns the hour according to the 24 hour clock. Values range from 0 to 23.
<P>
<FONT COLOR="teal"><B> void <A NAME="SetHour">SetHour</A>(int aHour)
</B></FONT>
<P>
Sets the hour from <B><TT>aHour</TT></B> based on the 24-hour clock.
<B><TT>aHour</TT></B> should be in the range 0 to 23.
<P>
<FONT COLOR="teal"><B> int <A NAME="Minute">Minute</A>() const </B></FONT>
<P>
Returns the minute. Values range from 0 to 59.
<P>
<FONT COLOR="teal"><B> void <A NAME="SetMinute">SetMinute</A>(int aMinute)
</B></FONT>
<P>
Sets the minute from <B><TT>aMinute</TT></B>, which should be in the range
0 to 59.
<P>
<FONT COLOR="teal"><B> int <A NAME="Second">Second</A>() const </B></FONT>
<P>
Returns the second. Values range from 0 to 59.
<P>
<FONT COLOR="teal"><B> void <A NAME="SetSecond">SetSecond</A>(int aSecond)
</B></FONT>
<P>
Sets the second from <B><TT>aSecond</TT></B>, which should be in the range
0 to 59.
<P>
<FONT COLOR="teal"><B> int <A NAME="Zone">Zone</A>() const </B></FONT>
<P>
Returns the time zone as the diffence in minutes between local time and
Coordinated Universal Time (UTC or GMT).
<P>
<FONT COLOR="teal"><B> void <A NAME="SetZone">SetZone</A>(int aZone)
</B></FONT>
<P>
Sets the time zone from <B><TT>aZone</TT></B>, interpreted as the time difference
in minutes between local time and Coordinated Universal Time (UTC, or GMT).
<P>
<FONT COLOR="teal"><B> static void
<A NAME="SetDefaultZone">SetDefaultZone</A>(int aZone) </B></FONT>
<P>
Sets the default time zone. <B><TT>aZone</TT></B> should be the time difference
in minutes between local time and Coordinated Universal Time (UTC, or GMT).
The value is used to set the time zone for any objects created using the
default constructor.
<P>
<FONT COLOR="teal"><B> static DwDateTime*
<A NAME="NewDateTime">NewDateTime</A>(const DwString&amp;, DwMessageComponent*)
</B></FONT>
<P>
Creates a new <B><TT>DwDateTime</TT></B> object on the free store. If the
static data member <B><TT>sNewDateTime</TT></B> is <B><TT>NULL</TT></B>,
this member function will create a new <B><TT>DwDateTime</TT></B> and return
it. Otherwise, <B><TT>NewDateTime()</TT></B> will call the user-supplied
function pointed to by <B><TT>sNewDateTime</TT></B>, which is assumed to
return an object from a class derived from <B><TT>DwDateTime</TT></B>, and
return that object.
<P>
<FONT COLOR="teal"><B> virtual void
<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream&amp; aStrm, int aDepth=0)
const </B></FONT>
<P>
This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>,
prints debugging information about this object to <B><TT>aStrm</TT></B>.
<P>
This member function is available only in the debug version of the library.
<P>
<FONT COLOR="teal"><B> virtual void
<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT>
<P>
Aborts if one of the invariants of the object fails. Use this member function
to track down bugs.
<P>
This member function is available only in the debug version of the library.
<H2>
  <FONT COLOR="navy"> Public Data Members </FONT>
</H2>
<P>
<FONT COLOR="teal"><B> static DwDateTime*
(*<A NAME="sNewDateTime">sNewDateTime</A>)(const DwString&amp;,
DwMessageComponent*) </B></FONT>
<P>
If <B><TT>sNewDateTime</TT></B> is not <B><TT>NULL</TT></B>, it is assumed
to point to a user-supplied function that returns an object from a class
derived from <B><TT>DwDateTime</TT></B>.
<H2>
  <FONT COLOR="navy"> Protected Member Functions </FONT>
</H2>
<P>
<B><FONT COLOR="teal"> void
<A NAME="_FromUnixTime">_FromUnixTime</A>(DwUint32 aTime) </FONT></B>
<P>
Like <B><TT>FromUnixTime()</TT></B>, but doesn't set the is-modified flag.
<P>
<B><FONT COLOR="teal"> void
<A NAME="_FromCalendarTime">_FromCalendarTime</A>(time_t aTime) </FONT></B>
<P>
Like <B><TT>FromCalendarTime()</TT></B>, but doesn't set the is-modified
flag.
<P>
</BODY></HTML>