ceph/src/boost/libs/date_time/xmldoc/time_iterators.xml

   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.posix_time.time_iterators">
  11   <title>Time Iterators</title>
  12
  13   <link linkend="time_iter_intro">Introduction</link> --
  14   <link linkend="time_iter_header">Header</link> --
  15   <link linkend="time_iter_overview">Overview</link> --
  16   <link linkend="time_iter_operators">Operators</link>
  17
  18   <anchor id="time_iter_intro" />
  19   <bridgehead renderas="sect3">Introduction</bridgehead>
  20   <para>
  21     Time iterators provide a mechanism for iteration through times. Time iterators are similar to <ulink url="http://www.sgi.com/tech/stl/BidirectionalIterator.html">Bidirectional Iterators</ulink>. However, time_iterators are different than standard iterators in that there is no underlying sequence, just a calculation function. In addition, time_iterators are directly comparable against instances of <link linkend="date_time.posix_time.ptime_class">class ptime</link>. Thus a second iterator for the end point of the iteration is not required, but rather a point in time can be used directly. For example, the following code iterates using a 15 minute iteration interval. The <link linkend="date_time.examples.print_hours">print hours</link> example also illustrates the use of the time_iterator.
  22   </para>
  23   <para>
  24     <programlisting>
  25       <![CDATA[
  26         #include "boost/date_time/posix_time/posix_time.hpp"
  27         #include <iostream>
  28
  29
  30         int
  31         main()
  32         {
  33           using namespace boost::gregorian;
  34           using namespace boost::posix_time;
  35           date d(2000,Jan,20);
  36           ptime start(d);
  37           ptime end = start + hours(1);
  38           time_iterator titr(start,minutes(15)); //increment by 15 minutes
  39           //produces 00:00:00, 00:15:00, 00:30:00, 00:45:00
  40           while (titr < end) {
  41             std::cout << to_simple_string(*titr) << std::endl;
  42             ++titr;
  43           }
  44           std::cout << "Now backward" << std::endl;
  45           //produces 01:00:00, 00:45:00, 00:30:00, 00:15:00
  46           while (titr > start) {
  47             std::cout << to_simple_string(*titr) << std::endl;
  48             --titr;
  49           }
  50         }
  51       ]]>
  52     </programlisting>
  53   </para>
  54
  55   <anchor id="time_iter_header" />
  56   <bridgehead renderas="sect3">Header</bridgehead>
  57   <para>
  58     <programlisting>#include "boost/date_time/posix_time/posix_time.hpp" //include all types plus i/o
  59 or
  60 #include "boost/date_time/posix_time/posix_time_types.hpp" //no i/o just types</programlisting>
  61   </para>
  62
  63   <anchor id="time_iter_overview" />
  64   <bridgehead renderas="sect3">Overview</bridgehead>
  65   <para>
  66     <informaltable frame="all">
  67       <tgroup cols="2">
  68         <thead>
  69           <row>
  70             <entry valign="top" morerows="1">Class</entry>
  71             <entry>Description</entry>
  72           </row>
  73           <row>
  74             <entry>Construction Parameters</entry>
  75           </row>
  76         </thead>
  77         <tbody>
  78           <row>
  79             <entry valign="top" morerows="1"><screen>time_iterator</screen></entry>
  80             <entry>Iterate incrementing by the specified duration.</entry>
  81           </row>
  82           <row>
  83             <entry><screen>ptime start_time, time_duration increment</screen></entry>
  84           </row>
  85         </tbody>
  86       </tgroup>
  87     </informaltable>
  88   </para>
  89
  90
  91   <anchor id="time_iter_operators" />
  92   <bridgehead renderas="sect3">Operators</bridgehead>
  93   <para>
  94     <informaltable frame="all">
  95       <tgroup cols="2">
  96         <thead>
  97           <row>
  98             <entry valign="top" morerows="1">Syntax</entry>
  99             <entry>Description</entry>
 100           </row>
 101           <row>
 102             <entry>Example</entry>
 103           </row>
 104         </thead>
 105         <tbody>
 106           <row>
 107             <entry valign="top" morerows="1"><screen>operator==(const ptime&amp; rhs),
 108 operator!=(const ptime&amp; rhs),
 109 operator>, operator&lt;,
 110 operator>=, operator&lt;=</screen>
 111             </entry>
 112             <entry>A full complement of comparison operators</entry>
 113           </row>
 114           <row>
 115             <entry><screen>date d(2002,Jan,1);
 116 ptime start_time(d, hours(1));
 117 //increment by 10 minutes
 118 time_iterator titr(start_time, minutes(10));
 119 ptime end_time = start_time + hours(2);
 120 if (titr == end_time) // false
 121 if (titr != end_time) // true
 122 if (titr >= end_time) // false
 123 if (titr &lt;= end_time) // true</screen>
 124             </entry>
 125           </row>
 126
 127           <row>
 128             <entry valign="top" morerows="1"><screen>prefix increment</screen></entry>
 129             <entry>Increment the iterator by the specified duration.</entry>
 130           </row>
 131           <row>
 132             <entry><screen>//increment by 10 milli seconds
 133 time_iterator titr(start_time, milliseconds(10));
 134 ++titr; // == start_time + 10 milliseconds</screen>
 135             </entry>
 136           </row>
 137
 138           <row>
 139             <entry valign="top" morerows="1"><screen>prefix decrement</screen></entry>
 140             <entry>Decrement the iterator by the specified time duration.</entry>
 141           </row>
 142           <row>
 143             <entry><screen>time_duration td(1,2,3);
 144 time_iterator titr(start_time, td);
 145 --titr; // == start_time - 01:02:03</screen></entry>
 146           </row>
 147         </tbody>
 148       </tgroup>
 149     </informaltable>
 150   </para>
 151
 152 </section>