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 59or 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& rhs), 108operator!=(const ptime& rhs), 109operator>, operator<, 110operator>=, operator<=</screen> 111 </entry> 112 <entry>A full complement of comparison operators</entry> 113 </row> 114 <row> 115 <entry><screen>date d(2002,Jan,1); 116ptime start_time(d, hours(1)); 117//increment by 10 minutes 118time_iterator titr(start_time, minutes(10)); 119ptime end_time = start_time + hours(2); 120if (titr == end_time) // false 121if (titr != end_time) // true 122if (titr >= end_time) // false 123if (titr <= 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 133time_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); 144time_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> 153