1<?xml version="1.0" encoding="utf-8"?> 2<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" 3"../../../tools/boostbook/dtd/boostbook.dtd"> 4 5<!-- Copyright (c) 2001-2005 CrystalClear Software, Inc. 6 Subject to the Boost Software License, Version 1.0. 7 (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt) 8--> 9 10<section id="date_time.local_time.local_time_period"> 11 <title>Local Time Period</title> 12 13 <link linkend="local_time_period_intro">Introduction</link> -- 14 <link linkend="local_time_period_header">Header</link> -- 15 <link linkend="local_time_period_constr">Construction</link> -- 16 <link linkend="local_time_period_accessors">Accessors</link> -- 17 <link linkend="local_time_period_operators">Operators</link> 18 19 <anchor id="local_time_period_intro" /> 20 <bridgehead renderas="sect3">Introduction</bridgehead> 21 <para> 22 The class <code>boost::local_time::local_time_period</code> provides direct representation for ranges between two local times. Periods provide the ability to simplify some types of calculations by simplifying the conditional logic of the program. 23 </para> 24 <para> 25 A period that is created with beginning and end points being equal, or with a duration of zero, is known as a zero length period. Zero length periods are considered invalid (it is perfectly legal to construct an invalid period). For these periods, the <code>last</code> point will always be one unit less that the <code>begin</code> point. 26 </para> 27 28 <anchor id="local_time_period_header" /> 29 <bridgehead renderas="sect3">Header</bridgehead> 30 <para> 31 <programlisting>#include "boost/date_time/local_time/local_time.hpp" //include all types plus i/o 32or 33#include "boost/date_time/local_time/local_time_types.hpp" //no i/o just types</programlisting> 34 </para> 35 36 <anchor id="local_time_period_constr" /> 37 <bridgehead renderas="sect3">Construction</bridgehead> 38 <para> 39 <informaltable frame="all"> 40 <tgroup cols="2"> 41 <thead> 42 <row> 43 <entry valign="top" morerows="1">Syntax</entry> 44 <entry>Description</entry> 45 </row> 46 <row> 47 <entry>Example</entry> 48 </row> 49 </thead> 50 <tbody> 51 <row> 52 <entry valign="top" morerows="1"><screen>local_time_period(...) 53 Parameters: 54 local_date_time beginning 55 local_date_time end</screen></entry> 56 <entry> Create a period as [begin, end). If end is <= begin then the period will be defined as invalid.</entry> 57 </row> 58 <row> 59 <entry><screen>time_zone_ptr 60 zone(new posix_time_zone("MST-07")); 61local_date_time 62 beg(ptime(date(2005,Jan,1),hours(0)), zone); 63local_date_time 64 end(ptime(date(2005,Feb,1),hours(0)), zone); 65// period for the entire month of Jan 2005 66local_time_period ltp(beg, end);</screen> 67 </entry> 68 </row> 69 70 <row> 71 <entry valign="top" morerows="1"><screen>local_time_period(...) 72 Parameters: 73 local_date_time beginning 74 time_duration length</screen></entry> 75 <entry>Create a period as [begin, begin+len) where end would be begin+len. If len is <= zero then the period will be defined as invalid.</entry> 76 </row> 77 <row> 78 <entry><screen>time_zone_ptr 79 zone(new posix_time_zone("MST-07")); 80local_date_time 81 beg(ptime(date(2005,Jan,1),hours(0)), zone); 82// period for the whole day of 2005-Jan-01 83local_time_period ltp(beg, hours(24));</screen> 84 </entry> 85 </row> 86 87 <row> 88 <entry valign="top" morerows="1"><screen>local_time_period(local_time_period rhs)</screen></entry> 89 <entry>Copy constructor</entry> 90 </row> 91 <row> 92 <entry><screen>local_time_period ltp1(ltp);</screen></entry> 93 </row> 94 </tbody> 95 </tgroup> 96 </informaltable> 97 </para> 98 99 100 <anchor id="local_time_period_accessors" /> 101 <bridgehead renderas="sect3">Accessors</bridgehead> 102 <para> 103 <informaltable frame="all"> 104 <tgroup cols="2"> 105 <thead> 106 <row> 107 <entry valign="top" morerows="1">Syntax</entry> 108 <entry>Description</entry> 109 </row> 110 <row> 111 <entry>Example</entry> 112 </row> 113 </thead> 114 <tbody> 115 <row> 116 <entry valign="top" morerows="1"><screen>local_date_time begin()</screen></entry> 117 <entry>Return first local_date_time of the period.</entry> 118 </row> 119 <row> 120 <entry><screen>time_zone_ptr 121 zone(new posix_time_zone("MST-07")); 122local_date_time 123 ldt((ptime(date(2005,Jan,1)),hours(0)), zone); 124local_time_period ltp(ldt, hours(2)); 125ltp.begin(); // => 2005-Jan-01 00:00:00</screen> 126 </entry> 127 </row> 128 129 <row> 130 <entry valign="top" morerows="1"><screen>local_date_time last()</screen></entry> 131 <entry>Return last local_date_time in the period</entry> 132 </row> 133 <row> 134 <entry><screen>time_zone_ptr 135 zone(new posix_time_zone("MST-07")); 136local_date_time 137 ldt((ptime(date(2005,Jan,1),hours(0))), zone); 138local_time_period ltp(ldt, hours(2)); 139ltp.last(); // => 2005-Jan-01 01:59:59.999999999</screen> 140 </entry> 141 </row> 142 143 <row> 144 <entry valign="top" morerows="1"><screen>local_date_time end()</screen></entry> 145 <entry>Return one past the last in period</entry> 146 </row> 147 <row> 148 <entry><screen>time_zone_ptr 149 zone(new posix_time_zone("MST-07")); 150local_date_time 151 ldt((ptime(date(2005,Jan,1),hours(0))), zone); 152local_time_period ltp(ldt, hours(2)); 153ltp.end(); // => 2005-Jan-01 02:00:00</screen> 154 </entry> 155 </row> 156 157 <row> 158 <entry valign="top" morerows="1"><screen>time_duration length()</screen></entry> 159 <entry>Return the length of the local_time period.</entry> 160 </row> 161 <row> 162 <entry><screen>time_zone_ptr 163 zone(new posix_time_zone("MST-07")); 164local_date_time 165 ldt((ptime(date(2005,Jan,1),hours(0))), zone); 166local_time_period ltp(ldt, hours(2)); 167ltp.length(); // => 02:00:00</screen> 168 </entry> 169 </row> 170 171 <row> 172 <entry valign="top" morerows="1"><screen>bool is_null()</screen></entry> 173 <entry>True if period is not well formed. eg: end less than or equal to begin.</entry> 174 </row> 175 <row> 176 <entry><screen>time_zone_ptr 177 zone(new posix_time_zone("MST-07")); 178local_date_time 179 beg((ptime(date(2005,Feb,1),hours(0))), zone); 180local_date_time 181 end((ptime(date(2005,Jan,1),hours(0))), zone); 182local_time_period ltp(beg, end); 183ltp.is_null(); // => true</screen> 184 </entry> 185 </row> 186 187 <row> 188 <entry valign="top" morerows="1"><screen>bool contains(local_date_time)</screen></entry> 189 <entry>True if local_date_time is within the period. Zero length periods cannot contain any points</entry> 190 </row> 191 <row> 192 <entry><screen>time_zone_ptr 193 zone(new posix_time_zone("MST-07")); 194local_date_time 195 beg((ptime(date(2005,Jan,1),hours(0))), zone); 196local_date_time 197 end((ptime(date(2005,Feb,1),hours(0))), zone); 198local_time_period jan_mst(beg, end); 199 200local_date_time 201ldt((ptime(date(2005,Jan,15),hours(12))), zone); 202jan_mst.contains(ldt); // => true 203 204local_time_period zero(beg, beg); 205zero.contains(beg); // false</screen></entry> 206 </row> 207 208 <row> 209 <entry valign="top" morerows="1"><screen>bool contains(local_time_period)</screen></entry> 210 <entry>True if period is within the period</entry> 211 </row> 212 <row> 213 <entry><screen>// using jan_mst period from previous example 214 215local_date_time 216 beg((ptime(date(2005,Jan,7),hours(0))), zone); 217local_time_period ltp(beg, hours(24)); 218 219jan_mst.contains(ltp); // => true</screen></entry> 220 </row> 221 222 <row> 223 <entry valign="top" morerows="1"><screen>bool intersects(local_time_period)</screen></entry> 224 <entry> True if periods overlap</entry> 225 </row> 226 <row> 227 <entry><screen>// using jan_mst period from previous example 228 229local_date_time 230 beg((ptime(date(2005,Jan,7),hours(0))), zone); 231local_date_time 232 end((ptime(date(2005,Feb,7),hours(0))), zone); 233local_time_period ltp(beg, end); 234 235jan_mst.intersects(ltp); // => true</screen></entry> 236 </row> 237 238 <row> 239 <entry valign="top" morerows="1"><screen>local_time_period intersection(local_time_period)</screen></entry> 240 <entry>Calculate the intersection of 2 periods. Null if no intersection.</entry> 241 </row> 242 <row> 243 <entry><screen>// using jan_mst period from previous example 244 245local_date_time 246 beg((ptime(date(2005,Jan,7),hours(0))), zone); 247local_date_time 248 end((ptime(date(2005,Feb,7),hours(0))), zone); 249local_time_period ltp(beg, end); 250 251local_time_period res(jan_mst.intersection(ltp)); 252// res => 2005-Jan-07 00:00:00 through 253// 2005-Jan-31 23:59:59.999999999 (inclusive)</screen></entry> 254 </row> 255 256 <row> 257 <entry valign="top" morerows="1"><screen>local_time_period merge(local_time_period)</screen></entry> 258 <entry>Returns union of two periods. Null if no intersection.</entry> 259 </row> 260 <row> 261 <entry><screen>// using jan_mst period from previous example 262 263local_date_time 264 beg((ptime(date(2005,Jan,7),hours(0))), zone); 265local_date_time 266 end((ptime(date(2005,Feb,7),hours(0))), zone); 267local_time_period ltp(beg, end); 268 269local_time_period res(jan_mst.merge(ltp)); 270// res => 2005-Jan-07 00:00:00 through 271// 2005-Feb-06 23:59:59.999999999 (inclusive)</screen></entry> 272 </row> 273 274 <row> 275 <entry valign="top" morerows="1"><screen>local_time_period span(local_time_period)</screen></entry> 276 <entry>Combines two periods and any gap between them such that begin = min(p1.begin, p2.begin) and end = max(p1.end , p2.end).</entry> 277 </row> 278 <row> 279 <entry><screen>// using jan_mst period from previous example 280 281local_date_time 282 beg((ptime(date(2005,Mar,1),hours(0))), zone); 283local_date_time 284 end((ptime(date(2005,Apr,1),hours(0))), zone); 285local_time_period mar_mst(beg, end); 286 287local_time_period res(jan_mst.span(mar_mst)); 288// res => 2005-Jan-01 00:00:00 through 289// 2005-Mar-31 23:59:59.999999999 (inclusive)</screen></entry> 290 </row> 291 292 <row> 293 <entry valign="top" morerows="1"><screen>void shift(time_duration)</screen></entry> 294 <entry>Add duration to both begin and end.</entry> 295 </row> 296 <row> 297 <entry><screen>local_date_time 298 beg((ptime(date(2005,Mar,1),hours(0))), zone); 299local_date_time 300 end((ptime(date(2005,Apr,1),hours(0))), zone); 301local_time_period mar_mst(beg, end); 302 303mar_mst.shift(hours(48)); 304// mar_mst => 2005-Mar-03 00:00:00 through 305// 2005-Apr-02 23:59:59.999999999 (inclusive)</screen></entry> 306 </row> 307 </tbody> 308 </tgroup> 309 </informaltable> 310 </para> 311 312 313 <anchor id="local_time_period_operators" /> 314 <bridgehead renderas="sect3">Operators</bridgehead> 315 <para> 316 <informaltable frame="all"> 317 <tgroup cols="2"> 318 <thead> 319 <row> 320 <entry valign="top" morerows="1">Syntax</entry> 321 <entry>Description</entry> 322 </row> 323 <row> 324 <entry>Example</entry> 325 </row> 326 </thead> 327 <tbody> 328 <!-- TODO: the streaming operators have not bee changed from time_period to local_time_period 329 <row> 330 <entry valign="top" morerows="1"><screen>operator<<</screen></entry> 331 <entry>Output streaming operator for time duration. Uses facet to output [date time_of_day/date time_of_day]. The default is format is <code>[YYYY-mmm-DD hh:mm:ss.fffffffff/YYYY-mmm-DD hh:mm:ss.fffffffff]</code> string where <code>mmm</code> is 3 char month name and the fractional seconds are left out when zero.</entry> 332 </row> 333 <row> 334 <entry><screen>[2002-Jan-01 01:25:10.000000001/ \ 335 2002-Jan-31 01:25:10.123456789]</screen></entry> 336 </row> 337 338 <row> 339 <entry valign="top" morerows="1"><screen>operator>></screen></entry> 340 <entry>Input streaming operator for time duration. Uses facet to read [date time_of_day/date time_of_day]. The default is format is <code>[YYYY-mmm-DD hh:mm:ss.fffffffff/YYYY-mmm-DD hh:mm:ss.fffffffff]</code> string where <code>mmm</code> is 3 char month name and the fractional seconds are left out when zero.</entry> 341 </row> 342 <row> 343 <entry><screen>[2002-Jan-01 01:25:10.000000001/ \ 344 2002-Jan-31 01:25:10.123456789]</screen></entry> 345 </row> 346 --> 347 <row> 348 <entry valign="top" morerows="1"><screen>operator==, operator!=</screen></entry> 349 <entry>Equality operators. Periods are equal if ltp1.begin == ltp2.begin && ltp1.last == ltp2.last</entry> 350 </row> 351 <row> 352 <entry><screen>if (ltp1 == ltp2) {...</screen></entry> 353 </row> 354 355 <row> 356 <entry valign="top" morerows="1"><screen>operator<</screen></entry> 357 <entry>Ordering with no overlap. True if ltp1.end() less than ltp2.begin()</entry> 358 </row> 359 <row> 360 <entry><screen>if (ltp1 < ltp2) {...</screen></entry> 361 </row> 362 363 <row> 364 <entry valign="top" morerows="1"><screen>operator></screen></entry> 365 <entry>Ordering with no overlap. True if ltp1.begin() greater than ltp2.end()</entry> 366 </row> 367 <row> 368 <entry><screen>if (ltp1 > ltp2) {... etc</screen></entry> 369 </row> 370 371 <row> 372 <entry valign="top" morerows="1"><screen>operator<=, operator>=</screen></entry> 373 <entry>Defined in terms of the other operators.</entry> 374 </row> 375 <row> 376 <entry></entry> 377 </row> 378 </tbody> 379 </tgroup> 380 </informaltable> 381 </para> 382 383</section> 384