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
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
|
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"../../../tools/boostbook/dtd/boostbook.dtd">
<!-- Copyright (c) 2001-2005 CrystalClear Software, Inc.
Subject to the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)
-->
<section id="date_time.local_time.local_date_time">
<title>Local Date Time</title>
<link linkend="local_date_time_intro">Introduction</link> --
<link linkend="local_date_time_header">Header</link> --
<link linkend="local_date_time_clock_constr">Construct From Clock</link> --
<link linkend="local_date_time_constr">Construction</link> --
<link linkend="local_date_time_accessors">Accessors</link> --
<link linkend="local_date_time_operators">Operators</link> --
<link linkend="local_date_time_tm_func">Struct tm Functions</link>
<anchor id="local_date_time_intro" />
<bridgehead renderas="sect3">Introduction</bridgehead>
<para>
A local_date_time object is a point in time and an associated time zone. The time is represented internally as UTC.
</para>
<anchor id="local_date_time_header" />
<bridgehead renderas="sect3">Header</bridgehead>
<para>
The inclusion of a single header will bring in all boost::local_time types,
functions, and IO operators.
<programlisting>
#include "boost/date_time/local_time/local_time.hpp"
</programlisting>
</para>
<anchor id="local_date_time_clock_constr" />
<bridgehead renderas="sect3">Construct From Clock</bridgehead>
<para>
Creation of a local_date_time object from clock is possible with either second, or sub second resolution.
</para>
<para>
<informaltable frame="all">
<tgroup cols="2">
<thead>
<row>
<entry>Syntax</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry valign="top"><screen>local_microsec_clock(...)
Return Type:
local_date_time
Parameter:
time_zone_ptr</screen></entry>
<entry><screen>time_zone_ptr zone(
new posix_time_zone("MST-07")
);
local_date_time ldt =
local_microsec_clock::local_time(
zone);</screen>
</entry>
</row>
<row>
<entry valign="top"><screen>local_sec_clock(...)
Return Type:
local_date_time
Parameter:
time_zone_ptr</screen></entry>
<entry><screen>time_zone_ptr zone(
new posix_time_zone("MST-07")
);
local_date_time ldt =
local_sec_clock::local_time(zone);</screen>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="local_date_time_constr" />
<bridgehead renderas="sect3">Construction</bridgehead>
<para>
Construction of a local_date_time object can be done with a ptime and a time_zone_ptr where the ptime represents UTC time. Construction with a wall-clock representation takes the form of a date, a time_duration, a time_zone_ptr, and a fourth parameter that addresses the following complication.
</para>
<para>
Construction from a wall-clock rep may result in differing shifts for a particular time zone, depending on daylight savings rules for that zone. This means it is also possible to create a local_date_time with a non-existent, or duplicated, UTC representation. These cases occur during the forward shift in time that is the transition into daylight savings and during the backward shift that is the transition out of daylight savings. The user has two options for handling these cases: a bool flag that states if the time is daylight savings, or an enum that states what to do when either of these cases are encountered.
</para>
<para>
The bool flag is ignored when the given time_zone has no daylight savings specification. When the daylight savings status of a given time label is calculated and it does not match the flag, a <code>local_time::dst_not_valid</code> exception is thrown. If a time label is invalid (does not exist), a <code>local_time::time_label_invalid</code> exception is thrown.
</para>
<para>
There are two elements in the <code>local_date_time::DST_CALC_OPTIONS</code> enum: <code>EXCEPTION_ON_ERROR</code> and <code>NOT_DATE_TIME_ON_ERROR</code>. The possible exceptions thrown are a <code>local_time::ambiguous_result</code> or a <code>local_time::time_label_invalid</code>. The <code>NOT_DATE_TIME_ON_ERROR</code> sets the time value to the special value <code>local_time::not_a_date_time</code> in the event of either a invalid or an ambiguous time label.
</para>
<para>
<informaltable frame="all">
<tgroup cols="2">
<thead>
<row>
<entry morerows="1">Syntax</entry>
<entry>Description</entry>
</row>
<row>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry valign="top" morerows="1"><screen>local_date_time(...)
Parameters:
posix_time::ptime
time_zone_ptr</screen></entry>
<entry>The given time is expected to be UTC. Therefore, the given time will be adjusted according to the offset described in the time zone.</entry>
</row>
<row>
<entry><screen>
// 3am, 2004-Nov-05 local time
ptime pt(date(2004,Nov,5),
hours(10));
time_zone_ptr zone(
new posix_time_zone("MST-07"));
local_date_time az(pt, zone);</screen>
</entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>local_date_time(...)
Parameters:
date
time_duration
time_zone_ptr
bool</screen></entry>
<entry>The passed time information understood to be in the passed tz. The DST flag must be passed to indicate whether the time is in daylight savings or not. May throw a <code>dst_not_valid</code> or <code>time_label_invalid</code> exception.</entry>
</row>
<row>
<entry><screen>date d(2004,Nov,5);
time_duration td(5,0,0,0);
string z("PST-8PDT,M4.1.0,M10.1.0")
time_zone_ptr zone(
new posix_time_zone(z));
local_date_time nyc(d, td,
zone, false);</screen>
</entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>local_date_time(...)
Parameters:
date
time_duration
time_zone_ptr
DST_CALC_OPTIONS</screen></entry>
<entry>The passed time information understood to be in the passed tz. The DST flag is calculated according to the specified rule. May throw a <code>ambiguous_result</code> or <code>time_label_invalid</code> exception.</entry>
</row>
<row>
<entry><screen>date d(2004,Nov,5);
time_duration td(5,0,0,0);
string z("PST-8PDT,M4.1.0,M10.1.0")
time_zone_ptr zone(
new posix_time_zone(z));
local_date_time nyc(d, td, zone,
NOT_DATE_TIME_ON_ERROR);</screen>
</entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>local_date_time(local_date_time);</screen></entry>
<entry>Copy Constructor.</entry>
</row>
<row>
<entry><screen>local_date_time az_2(az);</screen></entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>local_date_time(...)
Parameters:
special_values
time_zone_ptr</screen></entry>
<entry>Special Values constructor.</entry>
</row>
<row>
<entry><screen>time_zone_ptr zone(
new posix_time_zone("MST-07")
);
local_date_time nadt(not_a_date_time,
zone);
// default NULL time_zone_ptr
local_date_time nadt(pos_infin);</screen>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="local_date_time_accessors" />
<bridgehead renderas="sect3">Accessors</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="2">
<thead>
<row>
<entry valign="top" morerows="1">Syntax</entry>
<entry>Description</entry>
</row>
<row>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry valign="top" morerows="1"><screen>time_zone_ptr zone()</screen></entry>
<entry>Returns associated time_zone object via a time_zone_ptr</entry>
</row>
<row>
<entry><screen></screen></entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>bool is_dst()</screen></entry>
<entry>Determines if time value is in DST for associated zone.</entry>
</row>
<row>
<entry></entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>ptime utc_time()</screen></entry>
<entry>Converts the local time value to a UTC value.</entry>
</row>
<row>
<entry><screen>ptime pt(date(2004,Nov,5),
hours(10));
time_zone_ptr zone(
new posix_time_zone("MST-07"));
local_date_time az(pt, zone);
az.utc_time(); // 10am 2004-Nov-5</screen>
</entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>ptime local_time()</screen></entry>
<entry>Returns the local time for this object (Wall-clock).</entry>
</row>
<row>
<entry><screen>ptime pt(date(2004,Nov,5),
hours(10));
time_zone_ptr zone(
new posix_time_zone("MST-07"));
local_date_time az(pt, zone);
az.utc_time(); // 10am 2004-Nov-5
az.local_time(); // 3am 2004-Nov-5</screen></entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>local_time_in(...)
Return Type:
local_date_time
Parameters:
time_zone_ptr
time_duration</screen></entry>
<entry>Returns a local_date_time representing the same UTC time as calling object, plus optional time_duration, with given time zone.</entry>
</row>
<row>
<entry><screen>local_date_time nyc = az.local_time_in(nyc_zone);
// nyc == 7am 2004-Nov-5</screen>
</entry>
</row>
<!--
<row>
<entry valign="top" morerows="1"><screen>std::string zone_name()</screen></entry>
<entry>Returns full zone name from associated time zone or "Coordinated Universal Time" if time_zone_ptr is NULL.</entry>
</row>
<row>
<entry>
</entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>std::string zone_abbrev()</screen></entry>
<entry>Returns zone abbreviation from associated time zone or "UTC" if time_zone_ptr is NULL.</entry>
</row>
<row>
<entry>
</entry>
</row>
-->
<row>
<entry valign="top" morerows="1"><screen>bool is_infinity() const</screen></entry>
<entry>Returns true if local_date_time is either positive or negative infinity</entry>
</row>
<row>
<entry><screen>local_date_time ldt(pos_infin);
ldt.is_infinity(); // --> true</screen></entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>bool is_neg_infinity() const</screen></entry>
<entry>Returns true if local_date_time is negative infinity</entry>
</row>
<row>
<entry><screen>local_date_time ldt(neg_infin);
ldt.is_neg_infinity(); // --> true</screen></entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>bool is_pos_infinity() const</screen></entry>
<entry>Returns true if local_date_time is positive infinity</entry>
</row>
<row>
<entry><screen>local_date_time ldt(neg_infin);
ldt.is_pos_infinity(); // --> true</screen></entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>bool is_not_a_date_time() const</screen></entry>
<entry>Returns true if value is not a date</entry>
</row>
<row>
<entry><screen>local_date_time ldt(not_a_date_time);
ldt.is_not_a_date_time(); // --> true</screen></entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>bool is_special() const</screen></entry>
<entry>Returns true if local_date_time is any <code>special_value</code></entry>
</row>
<row>
<entry><screen>local_date_time ldt(pos_infin);
local_date_time ldt2(not_a_date_time);
time_zone_ptr
mst(new posix_time_zone("MST-07"));
local_date_time
ldt3(local_sec_clock::local_time(mst));
ldt.is_special(); // --> true
ldt2.is_special(); // --> true
ldt3.is_special(); // --> false</screen></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="local_date_time_operators" />
<bridgehead renderas="sect3">Operators</bridgehead>
<informaltable frame="all">
<tgroup cols="2">
<thead>
<row>
<entry valign="top" morerows="1">Syntax</entry>
<entry>Description</entry>
</row>
<row>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry valign="top" morerows="1"><screen>operator<<</screen></entry>
<entry>Output streaming operator. This operator is part of the v1.33 IO addition to date_time. For complete details on this feature see <link linkend="date_time.date_time_io">Date Time IO</link>. The default output is shown in this example.</entry>
</row>
<row>
<entry><screen>
time_zone_ptr zone(new posix_time_zone("MST-07");
local_date_time ldt(date(2005,Jul,4),
hours(20),
false);
std::cout << ldt << std::endl;
// "2005-Jul-04 20:00:00 MST"
</screen></entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>operator>></screen></entry>
<entry>Input streaming operator. This operator is part of the v1.33 IO addition to date_time. For complete details on this feature see <link linkend="date_time.date_time_io">Date Time IO</link>. At this time, <code>local_date_time</code> objects can only be streamed in with a Posix Time Zone string. A complete description of a Posix Time Zone string can be found in the documentation for the <link linkend="posix_time_zone_intro">posix_time_zone</link> class.</entry>
</row>
<row>
<entry><screen>stringstream ss;
ss.str("2005-Jul-04 20:00:00 MST-07");
ss >> ldt;
</screen></entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>operator==, operator!=,
operator>, operator<,
operator>=, operator<=</screen></entry>
<entry>A full complement of comparison operators</entry>
</row>
<row>
<entry><screen>ldt1 == ldt2, etc</screen></entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>operator+, operator+=,
operator-, operator-=</screen></entry>
<entry>Addition, subtraction, and shortcut operators for <code>local_date_time</code> and date duration types. These include: <code>days</code>, <code>months</code>, and <code>years</code>.</entry>
</row>
<row>
<entry><screen>ldt + days(5), etc</screen></entry>
</row>
<row>
<entry valign="top" morerows="1"><screen>operator+, operator+=,
operator-, operator-=</screen></entry>
<entry>Addition, subtraction, and shortcut operators for <code>local_date_time</code> and <code>time_duration</code>.</entry>
</row>
<row>
<entry><screen>ldt + hours(5), etc</screen></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<anchor id="local_date_time_tm_func" />
<bridgehead renderas="sect3">Struct tm Functions</bridgehead>
<para>Function for converting a <code>local_date_time</code> object to a <code>tm</code> struct is provided.</para>
<informaltable frame="all">
<tgroup cols="2">
<thead>
<row>
<entry valign="top" morerows="1">Syntax</entry>
<entry>Description</entry>
</row>
<row>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry valign="top" morerows="1"><screen>tm to_tm(local_date_time)</screen></entry>
<entry>A function for converting a <code>local_date_time</code> object to a <code>tm</code> struct.</entry>
</row>
<row>
<entry><screen>
// 6am, 2005-Jul-05 local time
std::string z("EST-05EDT,M4.1.0,M10.1.0");
ptime pt(date(2005,Jul,5),
hours(10));
time_zone_ptr zone( new posix_time_zone(z));
local_date_time ldt(pt, zone);
tm ldt_tm = to_tm(ldt);
/* tm_year => 105
tm_mon => 6
tm_mday => 5
tm_wday => 2 (Tuesday)
tm_yday => 185
tm_hour => 6
tm_min => 0
tm_sec => 0
tm_isddst => 1 */</screen>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
|
