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-2006 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.posix_time.time_period"> 11 <title>Time Period</title> 12 13 <link linkend="time_period_intro">Introduction</link> -- 14 <link linkend="time_period_header">Header</link> -- 15 <link linkend="time_period_constr">Construction</link> -- 16 <link linkend="time_period_mutators">Mutators</link> -- 17 <link linkend="time_period_accessors">Accessors</link> -- 18 <link linkend="time_period_to_string">Conversion To String</link> -- 19 <link linkend="time_period_operators">Operators</link> 20 21 <anchor id="time_period_intro" /> 22 <bridgehead renderas="sect3">Introduction</bridgehead> 23 <para> 24 The class boost::posix_time::time_period provides direct representation for ranges between two times. Periods provide the ability to simplify some types of calculations by simplifying the conditional logic of the program. 25 </para> 26 <para> 27 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. 28 </para> 29 <para> 30 The <link linkend="date_time.examples.time_periods">time periods example</link> provides an example of using time periods. 31 </para> 32 33 <anchor id="time_period_header" /> 34 <bridgehead renderas="sect3">Header</bridgehead> 35 <para> 36 <programlisting>#include "boost/date_time/posix_time/posix_time.hpp" //include all types plus i/o 37or 38#include "boost/date_time/posix_time/posix_time_types.hpp" //no i/o just types</programlisting> 39 </para> 40 41 <anchor id="time_period_constr" /> 42 <bridgehead renderas="sect3">Construction</bridgehead> 43 <para> 44 <informaltable frame="all"> 45 <tgroup cols="2"> 46 <thead> 47 <row> 48 <entry valign="top" morerows="1">Syntax</entry> 49 <entry>Description</entry> 50 </row> 51 <row> 52 <entry>Example</entry> 53 </row> 54 </thead> 55 <tbody> 56 <row> 57 <entry valign="top" morerows="1"><screen>time_period(ptime, 58 ptime)</screen></entry> 59 <entry> Create a period as [begin, end). If end is <= begin then the period will be defined as invalid.</entry> 60 </row> 61 <row> 62 <entry><screen>date d(2002,Jan,01); 63ptime t1(d, seconds(10)); //10 sec after midnight 64ptime t2(d, hours(10)); //10 hours after midnight 65time_period tp(t1, t2);</screen> 66 </entry> 67 </row> 68 69 <row> 70 <entry valign="top" morerows="1"><screen>time_period(ptime, 71 time_duration)</screen></entry> 72 <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> 73 </row> 74 <row> 75 <entry><screen>date d(2002,Jan,01); 76ptime t(d, seconds(10)); //10 sec after midnight 77time_period tp(t, hours(3));</screen> 78 </entry> 79 </row> 80 81 <row> 82 <entry valign="top" morerows="1"><screen>time_period(time_period rhs)</screen></entry> 83 <entry> Copy constructor</entry> 84 </row> 85 <row> 86 <entry><screen>time_period tp1(tp);</screen></entry> 87 </row> 88 </tbody> 89 </tgroup> 90 </informaltable> 91 </para> 92 93 94 <anchor id="time_period_mutators" /> 95 <bridgehead renderas="sect3">Mutators</bridgehead> 96 <para> 97 <informaltable frame="all"> 98 <tgroup cols="2"> 99 <thead> 100 <row> 101 <entry valign="top" morerows="1">Syntax</entry> 102 <entry>Description</entry> 103 </row> 104 <row> 105 <entry>Example</entry> 106 </row> 107 </thead> 108 <tbody> 109 110 <row> 111 <entry valign="top" morerows="1"><screen>time_period shift(time_duration)</screen></entry> 112 <entry>Add duration to both begin and end.</entry> 113 </row> 114 <row> 115 <entry> 116 <screen> 117time_period tp(ptime(date(2005,Jan,1),hours(1)), hours(2)); 118tp.shift(minutes(5)); 119// tp == 2005-Jan-01 01:05:00 to 2005-Jan-01 03:05:00 120 </screen> 121 </entry> 122 </row> 123 124 <row> 125 <entry valign="top" morerows="1"><screen>time_period expand(days)</screen></entry> 126 <entry>Subtract duration from begin and add duration to end.</entry> 127 </row> 128 <row> 129 <entry> 130 <screen> 131time_period tp(ptime(date(2005,Jan,1),hours(1)), hours(2)); 132tp.expand(minutes(5)); 133// tp == 2005-Jan-01 00:55:00 to 2005-Jan-01 03:05:00 134 </screen> 135 </entry> 136 </row> 137 138 </tbody> 139 </tgroup> 140 </informaltable> 141 </para> 142 143 144 <anchor id="time_period_accessors" /> 145 <bridgehead renderas="sect3">Accessors</bridgehead> 146 <para> 147 <informaltable frame="all"> 148 <tgroup cols="2"> 149 <thead> 150 <row> 151 <entry valign="top" morerows="1">Syntax</entry> 152 <entry>Description</entry> 153 </row> 154 <row> 155 <entry>Example</entry> 156 </row> 157 </thead> 158 <tbody> 159 <row> 160 <entry valign="top" morerows="1"><screen>ptime begin()</screen></entry> 161 <entry>Return first time of period.</entry> 162 </row> 163 <row> 164 <entry><screen>date d(2002,Jan,01); 165ptime t1(d, seconds(10)); //10 sec after midnight 166ptime t2(d, hours(10)); //10 hours after midnight 167time_period tp(t1, t2); 168tp.begin(); // --> 2002-Jan-01 00:00:10</screen> 169 </entry> 170 </row> 171 172 <row> 173 <entry valign="top" morerows="1"><screen>ptime last()</screen></entry> 174 <entry>Return last time in the period</entry> 175 </row> 176 <row> 177 <entry><screen>date d(2002,Jan,01); 178ptime t1(d, seconds(10)); //10 sec after midnight 179ptime t2(d, hours(10)); //10 hours after midnight 180time_period tp(t1, t2); 181tp.last();// --> 2002-Jan-01 09:59:59.999999999</screen> 182 </entry> 183 </row> 184 185 <row> 186 <entry valign="top" morerows="1"><screen>ptime end()</screen></entry> 187 <entry> Return one past the last in period</entry> 188 </row> 189 <row> 190 <entry><screen>date d(2002,Jan,01); 191ptime t1(d, seconds(10)); //10 sec after midnight 192ptime t2(d, hours(10)); //10 hours after midnight 193time_period tp(t1, t2); 194tp.last(); // --> 2002-Jan-01 10:00:00</screen> 195 </entry> 196 </row> 197 198 <row> 199 <entry valign="top" morerows="1"><screen>time_duration length()</screen></entry> 200 <entry>Return the length of the time period.</entry> 201 </row> 202 <row> 203 <entry><screen>date d(2002,Jan,01); 204ptime t1(d); //midnight 205time_period tp(t1, hours(1)); 206tp.length() --> 1 hour</screen> 207 </entry> 208 </row> 209 210 <row> 211 <entry valign="top" morerows="1"><screen>bool is_null()</screen></entry> 212 <entry>True if period is not well formed. eg: end is less than or equal to begin.</entry> 213 </row> 214 <row> 215 <entry><screen>date d(2002,Jan,01); 216ptime t1(d, hours(12)); // noon on Jan 1st 217ptime t2(d, hours(9)); // 9am on Jan 1st 218time_period tp(t1, t2); 219tp.is_null(); // true</screen> 220 </entry> 221 </row> 222 223 <row> 224 <entry valign="top" morerows="1"><screen>bool contains(ptime)</screen></entry> 225 <entry>True if ptime is within the period. Zero length periods cannot contain any points.</entry> 226 </row> 227 <row> 228 <entry><screen>date d(2002,Jan,01); 229ptime t1(d, seconds(10)); //10 sec after midnight 230ptime t2(d, hours(10)); //10 hours after midnight 231ptime t3(d, hours(2)); //2 hours after midnight 232time_period tp(t1, t2); 233tp.contains(t3); // true 234time_period tp2(t1, t1); 235tp2.contains(t1); // false</screen> 236 </entry> 237 </row> 238 239 <row> 240 <entry valign="top" morerows="1"><screen>bool contains(time_period)</screen></entry> 241 <entry>True if period is within the period</entry> 242 </row> 243 <row> 244 <entry><screen>time_period tp1(ptime(d,hours(1)), 245 ptime(d,hours(12))); 246time_period tp2(ptime(d,hours(2)), 247 ptime(d,hours(4))); 248tp1.contains(tp2); // --> true 249tp2.contains(tp1); // --> false</screen> 250 </entry> 251 </row> 252 253 <row> 254 <entry valign="top" morerows="1"><screen>bool intersects(time_period)</screen></entry> 255 <entry> True if periods overlap</entry> 256 </row> 257 <row> 258 <entry><screen>time_period tp1(ptime(d,hours(1)), 259 ptime(d,hours(12))); 260time_period tp2(ptime(d,hours(2)), 261 ptime(d,hours(4))); 262tp2.intersects(tp1); // --> true</screen> 263 </entry> 264 </row> 265 266 <row> 267 <entry valign="top" morerows="1"><screen>time_period intersection(time_period)</screen></entry> 268 <entry>Calculate the intersection of 2 periods. Null if no intersection.</entry> 269 </row> 270 <row> 271 <entry></entry> 272 </row> 273 274 <row> 275 <entry valign="top" morerows="1"><screen>time_period merge(time_period)</screen></entry> 276 <entry>Returns union of two periods. Null if no intersection.</entry> 277 </row> 278 <row> 279 <entry></entry> 280 </row> 281 282 <row> 283 <entry valign="top" morerows="1"><screen>time_period span(time_period)</screen></entry> 284 <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> 285 </row> 286 <row> 287 <entry></entry> 288 </row> 289 290 </tbody> 291 </tgroup> 292 </informaltable> 293 </para> 294 295 296 <anchor id="time_period_to_string" /> 297 <bridgehead renderas="sect3">Conversion To String</bridgehead> 298 <para> 299 <informaltable frame="all"> 300 <tgroup cols="2"> 301 <thead> 302 <row> 303 <entry valign="top" morerows="1">Syntax</entry> 304 <entry>Description</entry> 305 </row> 306 <row> 307 <entry>Example</entry> 308 </row> 309 </thead> 310 <tbody> 311 <row> 312 <entry valign="top" morerows="1"><screen>std::string 313 to_simple_string(time_period dp)</screen></entry> 314 <entry>To <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.</entry> 315 </row> 316 <row> 317 <entry><screen>[2002-Jan-01 01:25:10.000000001/ 318 2002-Jan-31 01:25:10.123456789] 319// string occupies one line</screen></entry> 320 </row> 321 </tbody> 322 </tgroup> 323 </informaltable> 324 </para> 325 326 327 <anchor id="time_period_operators" /> 328 <bridgehead renderas="sect3">Operators</bridgehead> 329 <para> 330 <informaltable frame="all"> 331 <tgroup cols="2"> 332 <thead> 333 <row> 334 <entry valign="top" morerows="1">Syntax</entry> 335 <entry>Description</entry> 336 </row> 337 <row> 338 <entry>Example</entry> 339 </row> 340 </thead> 341 <tbody> 342 <row> 343 <entry valign="top" morerows="1"><screen>operator<<</screen></entry> 344 <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> 345 </row> 346 <row> 347 <entry><screen>[2002-Jan-01 01:25:10.000000001/ \ 348 2002-Jan-31 01:25:10.123456789]</screen></entry> 349 </row> 350 351 <row> 352 <entry valign="top" morerows="1"><screen>operator>></screen></entry> 353 <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> 354 </row> 355 <row> 356 <entry><screen>[2002-Jan-01 01:25:10.000000001/ \ 357 2002-Jan-31 01:25:10.123456789]</screen></entry> 358 </row> 359 360 <row> 361 <entry valign="top" morerows="1"><screen>operator==, operator!=</screen></entry> 362 <entry>Equality operators. Periods are equal if p1.begin == p2.begin && p1.last == p2.last</entry> 363 </row> 364 <row> 365 <entry><screen>if (tp1 == tp2) {...</screen></entry> 366 </row> 367 368 <row> 369 <entry valign="top" morerows="1"><screen>operator<</screen></entry> 370 <entry>Ordering with no overlap. True if tp1.end() less than tp2.begin()</entry> 371 </row> 372 <row> 373 <entry><screen>if (tp1 < tp2) {...</screen></entry> 374 </row> 375 376 <row> 377 <entry valign="top" morerows="1"><screen>operator></screen></entry> 378 <entry>Ordering with no overlap. True if tp1.begin() greater than tp2.end()</entry> 379 </row> 380 <row> 381 <entry><screen>if (tp1 > tp2) {... etc</screen></entry> 382 </row> 383 384 <row> 385 <entry valign="top" morerows="1"><screen>operator<=, operator>=</screen></entry> 386 <entry>Defined in terms of the other operators.</entry> 387 </row> 388 <row> 389 <entry></entry> 390 </row> 391 </tbody> 392 </tgroup> 393 </informaltable> 394 </para> 395 396</section> 397