doc/html/date_time/date_time_io.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   5 <title>Date Time Input/Output</title>
   6 <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
   7 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   8 <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
   9 <link rel="up" href="../date_time.html" title="Chapter&#160;12.&#160;Boost.Date_Time">
  10 <link rel="prev" href="local_time.html" title="Local Time">
  11 <link rel="next" href="serialization.html" title="Serialization">
  12 </head>
  13 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  14 <table cellpadding="2" width="100%"><tr>
  15 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
  16 <td align="center"><a href="../../../index.html">Home</a></td>
  17 <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  19 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  20 <td align="center"><a href="../../../more/index.htm">More</a></td>
  21 </tr></table>
  22 <hr>
  23 <div class="spirit-nav">
  24 <a accesskey="p" href="local_time.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../date_time.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="serialization.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
  25 </div>
  26 <div class="section">
  27 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  28 <a name="date_time.date_time_io"></a>Date Time Input/Output</h2></div></div></div>
  29 <div class="toc"><dl class="toc">
  30 <dt><span class="section"><a href="date_time_io.html#date_time.format_flags">Format Flags</a></span></dt>
  31 <dt><span class="section"><a href="date_time_io.html#date_time.date_facet">Date Facet</a></span></dt>
  32 <dt><span class="section"><a href="date_time_io.html#date_time.date_input_facet">Date Input Facet</a></span></dt>
  33 <dt><span class="section"><a href="date_time_io.html#date_time.time_facet">Time Facet</a></span></dt>
  34 <dt><span class="section"><a href="date_time_io.html#date_time.time_input_facet">Time Input Facet</a></span></dt>
  35 <dt><span class="section"><a href="date_time_io.html#date_time.io_objects">Date Time Formatter/Parser Objects</a></span></dt>
  36 <dt><span class="section"><a href="date_time_io.html#date_time.io_tutorial">Date Time IO Tutorial</a></span></dt>
  37 </dl></div>
  38 <h3>
  39 <a name="idp212682352"></a>Date Time IO System</h3>
  40 <p>
  41     <a class="link" href="date_time_io.html#streaming_exceptions">Exception Handling on Streams</a>
  42   </p>
  43 <p>As of version 1.33, the date_time library utilizes a new IO streaming system. This new system gives the user great control over how dates and times can be represented. The customization options can be broken down into two groups: format flags and string elements. Format flags provide flexibility in the order of the date elements as well as the type. Customizing the string elements allows the replacement of built in strings from month names, weekday names, and other strings used in the IO.</p>
  44 <p>The output system is based on a date_facet (derived from std::facet), while the input system is based on a date_input_facet (also derived from std::facet). The time and local_time facets are derived from these base types. The output system utilizes three formatter objects, whereas the input system uses four parser objects. These formatter and parser objetcs are also customizable.</p>
  45 <p>It is important to note, that while all the examples shown here use narrow streams, there are wide stream facets available as well (see <a class="link" href="date_time_io.html#io_objects_table">IO Objects</a> for a complete list).</p>
  46 <p>It should be further noted that not all compilers are capable of using this IO system. For those compilers the IO system used in previous <code class="computeroutput">date_time</code> versions is still available. The "legacy IO" is automatically selected for these compilers, however, the legacy IO system can be manually selected by defining <code class="computeroutput">USE_DATE_TIME_PRE_1_33_FACET_IO</code>. See the <a class="link" href="details.html#date_time.buildinfo" title="Build-Compiler Information">Build-Compiler Information</a> for more information.</p>
  47 <a name="streaming_exceptions"></a><h6>
  48 <a name="idp212691360"></a>Exception Handling on Streams</h6>
  49 <p>When an error occurs during the input streaming process, the <code class="computeroutput">std::ios_base::failbit</code> will (always) be set on the stream. It is also possible to have exceptions thrown when an error occurs. To "turn on" these exceptions, call the stream's <code class="computeroutput">exceptions</code> function with a parameter of <code class="computeroutput">std::ios_base::failbit</code>.</p>
  50 <pre class="screen">// "Turning on" exceptions
  51 date d(not_a_date_time);
  52 std::stringstream ss;
  53 ss.exceptions(std::ios_base::failbit);
  54 ss.str("204-Jan-01");
  55 ss &gt;&gt; d; // throws bad_year exception AND sets failbit on stream</pre>
  56 <h6>
  57 <a name="idp212695728"></a>A simple example of this new system:</h6>
  58 <pre class="screen">//example to customize output to be "LongWeekday LongMonthname day, year"
  59 //                                  "%A %b %d, %Y"
  60 date d(2005,Jun,25);
  61 date_facet* facet(new date_facet("%A %B %d, %Y"));
  62 std::cout.imbue(std::locale(std::cout.getloc(), facet));
  63 std::cout &lt;&lt; d &lt;&lt; std::endl;
  64 // "Saturday June 25, 2005"</pre>
  65 <div class="section">
  66 <div class="titlepage"><div><div><h3 class="title">
  67 <a name="date_time.format_flags"></a>Format Flags</h3></div></div></div>
  68 <p>Many of the format flags this new system uses for output are those used by <code class="computeroutput">strftime(...)</code>, but not all. Some new flags have been added, and others overridden. The input system supports only specific flags, therefore, not all flags that work for output will work with input (we are currently working to correct this situation).</p>
  69 <p>The following tables list the all the flags available for both date_time IO as well as strftime. Format flags marked with a single asterisk (*) have a behavior unique to date_time. Those flags marked with an exclamation point (!) are not usable for input (at this time). The flags marked with a hash sign (#) are implemented by system locale and are known to be missing on some platforms. The first table is for dates, and the second table is for times.
  70   </p>
  71 <p>
  72     <a name="date_time_io.date_format_flags"></a>
  73     Date Facet Format Flags
  74     </p>
  75 <div class="informaltable"><table class="table">
  76 <colgroup>
  77 <col>
  78 <col>
  79 </colgroup>
  80 <thead>
  81 <tr>
  82 <th rowspan="2" valign="top">Format Specifier</th>
  83 <th>Description</th>
  84 </tr>
  85 <tr><th>Example</th></tr>
  86 </thead>
  87 <tbody>
  88 <tr>
  89 <td rowspan="2" valign="top"><pre class="screen">%a</pre></td>
  90 <td>Abbreviated weekday name</td>
  91 </tr>
  92 <tr><td><pre class="screen">"Mon" =&gt; Monday</pre></td></tr>
  93 <tr>
  94 <td rowspan="2" valign="top"><pre class="screen">%A</pre></td>
  95 <td>Long weekday name</td>
  96 </tr>
  97 <tr><td><pre class="screen">"Monday"</pre></td></tr>
  98 <tr>
  99 <td rowspan="2" valign="top"><pre class="screen">%b</pre></td>
 100 <td>Abbreviated month name</td>
 101 </tr>
 102 <tr><td><pre class="screen">"Feb" =&gt; February</pre></td></tr>
 103 <tr>
 104 <td rowspan="2" valign="top"><pre class="screen">%B</pre></td>
 105 <td>Full month name</td>
 106 </tr>
 107 <tr><td><pre class="screen">"February"</pre></td></tr>
 108 <tr>
 109 <td rowspan="2" valign="top"><pre class="screen">%c !</pre></td>
 110 <td>The  preferred  date  and  time  representation  for the current locale.</td>
 111 </tr>
 112 <tr><td><pre class="screen"></pre></td></tr>
 113 <tr>
 114 <td rowspan="2" valign="top"><pre class="screen">%C !#</pre></td>
 115 <td>The century number (year/100) as a 2-digit integer.</td>
 116 </tr>
 117 <tr><td><pre class="screen"></pre></td></tr>
 118 <tr>
 119 <td rowspan="2" valign="top"><pre class="screen">%d</pre></td>
 120 <td>Day of the month as decimal 01 to 31</td>
 121 </tr>
 122 <tr><td><pre class="screen"></pre></td></tr>
 123 <tr>
 124 <td rowspan="2" valign="top"><pre class="screen">%D !#</pre></td>
 125 <td>Equivalent to %m/%d/%y</td>
 126 </tr>
 127 <tr><td><pre class="screen"></pre></td></tr>
 128 <tr>
 129 <td rowspan="2" valign="top"><pre class="screen">%e #</pre></td>
 130 <td>Like %d, the day of the month as a decimal number, but a leading zero is replaced by a space</td>
 131 </tr>
 132 <tr><td><pre class="screen"></pre></td></tr>
 133 <tr>
 134 <td rowspan="2" valign="top"><pre class="screen">%G !</pre></td>
 135 <td>This has the same format and value as %y, except that if the ISO week number belongs to the previous or next year, that year is used instead.</td>
 136 </tr>
 137 <tr><td><pre class="screen"></pre></td></tr>
 138 <tr>
 139 <td rowspan="2" valign="top"><pre class="screen">%g !</pre></td>
 140 <td>Like %G, but without century.</td>
 141 </tr>
 142 <tr><td><pre class="screen"></pre></td></tr>
 143 <tr>
 144 <td rowspan="2" valign="top"><pre class="screen">%h !#</pre></td>
 145 <td> Equivalent to %b</td>
 146 </tr>
 147 <tr><td><pre class="screen"></pre></td></tr>
 148 <tr>
 149 <td rowspan="2" valign="top"><pre class="screen">%j</pre></td>
 150 <td>Day of year as decimal from 001 to 366 for leap years, 001 - 365 for non-leap years.</td>
 151 </tr>
 152 <tr><td><pre class="screen">"060" =&gt; Feb-29</pre></td></tr>
 153 <tr>
 154 <td rowspan="2" valign="top"><pre class="screen">%m</pre></td>
 155 <td>Month name as a decimal 01 to 12</td>
 156 </tr>
 157 <tr><td><pre class="screen">"01" =&gt; January</pre></td></tr>
 158 <tr>
 159 <td rowspan="2" valign="top"><pre class="screen">%u !</pre></td>
 160 <td>The  day of the week as a decimal, range 1 to 7, Monday being 1.</td>
 161 </tr>
 162 <tr><td><pre class="screen"></pre></td></tr>
 163 <tr>
 164 <td rowspan="2" valign="top"><pre class="screen">%U</pre></td>
 165 <td>The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. In 2005, Jan 1st falls on a Saturday, so therefore it falls within week 00 of 2005 (week 00 spans 2004-Dec-26 to 2005-Jan-01. This also happens to be week 53 of 2004).</td>
 166 </tr>
 167 <tr><td><pre class="screen">date d(2005, Jan, 1); // Saturday
 168 // with format %U
 169 ss &lt;&lt; d; // "00"
 170 d += day(1); // Sunday
 171 ss &lt;&lt; d; // "01" beginning of week 1</pre></td></tr>
 172 <tr>
 173 <td rowspan="2" valign="top"><pre class="screen">%V !#</pre></td>
 174 <td>The ISO 8601:1988 week number of the current year as  a  decimal number,  range 01 to 53, where week 1 is the first week that has at least 4 days in the current year,  and  with  Monday  as  the first day of the week.</td>
 175 </tr>
 176 <tr><td><pre class="screen"></pre></td></tr>
 177 <tr>
 178 <td rowspan="2" valign="top"><pre class="screen">%w</pre></td>
 179 <td>Weekday as decimal number 0 to 6</td>
 180 </tr>
 181 <tr><td><pre class="screen">"0" =&gt; Sunday</pre></td></tr>
 182 <tr>
 183 <td rowspan="2" valign="top"><pre class="screen">%W</pre></td>
 184 <td>Week number 00 to 53 where Monday is first day of week 1</td>
 185 </tr>
 186 <tr><td><pre class="screen">date d(2005, Jan, 2); // Sunday
 187 // with format %W
 188 ss &lt;&lt; d; // "00"
 189 d += day(1); // Monday
 190 ss &lt;&lt; d; // "01" beginning of week 1</pre></td></tr>
 191 <tr>
 192 <td rowspan="2" valign="top"><pre class="screen">%x</pre></td>
 193 <td>Implementation defined date format from the locale.</td>
 194 </tr>
 195 <tr><td><pre class="screen">date d(2005,Oct,31);
 196 date_facet* f = new date_facet("%x");
 197
 198 locale loc = locale(locale("en_US"), f);
 199 cout.imbue(loc);
 200 cout &lt;&lt; d; // "10/31/2005"
 201
 202 loc = locale(locale("de_DE"), f);
 203 cout.imbue(loc);
 204 cout &lt;&lt; d; // "31.10.2005"</pre></td></tr>
 205 <tr>
 206 <td rowspan="2" valign="top"><pre class="screen">%y</pre></td>
 207 <td>Two digit year</td>
 208 </tr>
 209 <tr><td><pre class="screen">"05" =&gt; 2005</pre></td></tr>
 210 <tr>
 211 <td rowspan="2" valign="top"><pre class="screen">%Y</pre></td>
 212 <td>Four digit year</td>
 213 </tr>
 214 <tr><td><pre class="screen">"2005"</pre></td></tr>
 215 <tr>
 216 <td rowspan="2" valign="top"><pre class="screen">%Y-%b-%d</pre></td>
 217 <td>Default date format</td>
 218 </tr>
 219 <tr><td><pre class="screen">"2005-Apr-01"</pre></td></tr>
 220 <tr>
 221 <td rowspan="2" valign="top"><pre class="screen">%Y%m%d</pre></td>
 222 <td>ISO format</td>
 223 </tr>
 224 <tr><td><pre class="screen">"20050401"</pre></td></tr>
 225 <tr>
 226 <td rowspan="2" valign="top"><pre class="screen">%Y-%m-%d</pre></td>
 227 <td>ISO extended format</td>
 228 </tr>
 229 <tr><td><pre class="screen">"2005-04-01"</pre></td></tr>
 230 </tbody>
 231 </table></div>
 232 <p>
 233
 234
 235     <a name="date_time_io.time_format_flags"></a>
 236     Time Facet Format Flags
 237     </p>
 238 <div class="informaltable"><table class="table">
 239 <colgroup>
 240 <col>
 241 <col>
 242 </colgroup>
 243 <thead>
 244 <tr>
 245 <th rowspan="2" valign="top">Format Specifier</th>
 246 <th>Description</th>
 247 </tr>
 248 <tr><th>Example</th></tr>
 249 </thead>
 250 <tbody>
 251 <tr>
 252 <td rowspan="2" valign="top"><pre class="screen">%- *!</pre></td>
 253 <td>Placeholder for the sign of a duration. Only displays when the duration is negative.</td>
 254 </tr>
 255 <tr><td><pre class="screen">"-13:15:16"</pre></td></tr>
 256 <tr>
 257 <td rowspan="2" valign="top"><pre class="screen">%+ *!</pre></td>
 258 <td>Placeholder for the sign of a duration. Always displays for both positive and negative.</td>
 259 </tr>
 260 <tr><td><pre class="screen">"+13:15:16"</pre></td></tr>
 261 <tr>
 262 <td rowspan="2" valign="top"><pre class="screen">%f</pre></td>
 263 <td>Fractional seconds are always used, even when their value is zero</td>
 264 </tr>
 265 <tr><td><pre class="screen">"13:15:16.000000"</pre></td></tr>
 266 <tr>
 267 <td rowspan="2" valign="top"><pre class="screen">%F *</pre></td>
 268 <td>Fractional seconds are used only when their value is not zero.</td>
 269 </tr>
 270 <tr><td><pre class="screen">"13:15:16"
 271 "05:04:03.001234"</pre></td></tr>
 272 <tr>
 273 <td rowspan="2" valign="top"><pre class="screen">%H</pre></td>
 274 <td>The hour as a decimal number using a 24-hour clock (range 00 to 23).</td>
 275 </tr>
 276 <tr><td>&#160;</td></tr>
 277 <tr>
 278 <td rowspan="2" valign="top"><pre class="screen">%I !</pre></td>
 279 <td>The hour as a decimal number using a 12-hour clock (range 01 to 12).</td>
 280 </tr>
 281 <tr><td>&#160;</td></tr>
 282 <tr>
 283 <td rowspan="2" valign="top"><pre class="screen">%k !</pre></td>
 284 <td>The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank.</td>
 285 </tr>
 286 <tr><td>&#160;</td></tr>
 287 <tr>
 288 <td rowspan="2" valign="top"><pre class="screen">%l !</pre></td>
 289 <td>The hour (12-hour clock) as a decimal number (range  1  to  12); single digits are preceded by a blank.</td>
 290 </tr>
 291 <tr><td>&#160;</td></tr>
 292 <tr>
 293 <td rowspan="2" valign="top"><pre class="screen">%M</pre></td>
 294 <td>The minute as a decimal number (range 00 to 59).</td>
 295 </tr>
 296 <tr><td>&#160;</td></tr>
 297 <tr>
 298 <td rowspan="2" valign="top"><pre class="screen">%O</pre></td>
 299 <td>The number of hours in a time duration as a decimal number (range 0 to max. representable duration); single digits are preceded by a zero.</td>
 300 </tr>
 301 <tr><td>&#160;</td></tr>
 302 <tr>
 303 <td rowspan="2" valign="top"><pre class="screen">%p !</pre></td>
 304 <td>Either `AM' or `PM' according to the given time value, or the corresponding strings for the current locale.</td>
 305 </tr>
 306 <tr><td>&#160;</td></tr>
 307 <tr>
 308 <td rowspan="2" valign="top"><pre class="screen">%P !#</pre></td>
 309 <td>Like %p but in lowercase: `am' or `pm' or a corresponding string for the current locale.</td>
 310 </tr>
 311 <tr><td>&#160;</td></tr>
 312 <tr>
 313 <td rowspan="2" valign="top"><pre class="screen">%r !#</pre></td>
 314 <td>The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to `%I:%M:%S %p'</td>
 315 </tr>
 316 <tr><td>&#160;</td></tr>
 317 <tr>
 318 <td rowspan="2" valign="top"><pre class="screen">%R !</pre></td>
 319 <td>The time in 24-hour notation (%H:%M)</td>
 320 </tr>
 321 <tr><td>&#160;</td></tr>
 322 <tr>
 323 <td rowspan="2" valign="top"><pre class="screen">%s *</pre></td>
 324 <td>Seconds with fractional seconds.</td>
 325 </tr>
 326 <tr><td><pre class="screen">"59.000000"</pre></td></tr>
 327 <tr>
 328 <td rowspan="2" valign="top"><pre class="screen">%S</pre></td>
 329 <td>Seconds only</td>
 330 </tr>
 331 <tr><td><pre class="screen">"59"</pre></td></tr>
 332 <tr>
 333 <td rowspan="2" valign="top"><pre class="screen">%T !</pre></td>
 334 <td>The time in 24-hour notation (%H:%M:%S)</td>
 335 </tr>
 336 <tr><td>&#160;</td></tr>
 337 <tr>
 338 <td rowspan="2" valign="top"><pre class="screen">%q</pre></td>
 339 <td>ISO time zone (output only). This flag is ignored when using the time_facet with a ptime.</td>
 340 </tr>
 341 <tr><td><pre class="screen">"-0700" // Mountain Standard Time</pre></td></tr>
 342 <tr>
 343 <td rowspan="2" valign="top"><pre class="screen">%Q</pre></td>
 344 <td>ISO extended time zone (output only). This flag is ignored when using the time_facet with a ptime.</td>
 345 </tr>
 346 <tr><td><pre class="screen">"-05:00" // Eastern Standard Time</pre></td></tr>
 347 <tr>
 348 <td rowspan="2" valign="top"><pre class="screen">%z *!</pre></td>
 349 <td>Abbreviated time zone (output only). This flag is ignored when using the time_facet with a ptime.</td>
 350 </tr>
 351 <tr><td><pre class="screen">"MST" // Mountain Standard Time</pre></td></tr>
 352 <tr>
 353 <td rowspan="2" valign="top"><pre class="screen">%Z *!</pre></td>
 354 <td>Full time zone name (output only). This flag is ignored when using the time_facet with a ptime.</td>
 355 </tr>
 356 <tr><td><pre class="screen">"EDT" // Eastern Daylight Time</pre></td></tr>
 357 <tr>
 358 <td rowspan="2" valign="top"><pre class="screen">%ZP *</pre></td>
 359 <td>Posix time zone string (available to both input and output). This flag is ignored when using the time_facet with a ptime. For complete details on posix time zone strings, see <a class="link" href="local_time.html#date_time.local_time.posix_time_zone" title="Posix Time Zone">posix_time_zone class</a>.</td>
 360 </tr>
 361 <tr><td><pre class="screen">"EST-05EDT+01,M4.1.0/02:00,M10.5.0/02:00"</pre></td></tr>
 362 <tr>
 363 <td rowspan="2" valign="top"><pre class="screen">%x %X</pre></td>
 364 <td>Implementation defined date/time format from the locale.</td>
 365 </tr>
 366 <tr><td><pre class="screen">date d(2005,Oct,31);
 367 ptime pt(d, hours(20));
 368 time_facet* f = new time_facet("%x %X");
 369
 370 locale loc = locale(locale("en_US"), f);
 371 cout.imbue(loc);
 372 cout &lt;&lt; pt; // "10/31/2005 08:00:00 PM"
 373
 374 loc = locale(locale("de_DE"), f);
 375 cout.imbue(loc);
 376 cout &lt;&lt; pt; // "31.10.2005 20:00:00"</pre></td></tr>
 377 <tr>
 378 <td rowspan="2" valign="top"><pre class="screen">%Y%m%dT%H%M%S%F%q</pre></td>
 379 <td>ISO format</td>
 380 </tr>
 381 <tr><td><pre class="screen">"20051015T131211-0700" // Oct 15, 2005 13:12:11 MST</pre></td></tr>
 382 <tr>
 383 <td rowspan="2" valign="top"><pre class="screen">%Y-%m-%d %H:%M:%S%F%Q</pre></td>
 384 <td>Extended ISO format</td>
 385 </tr>
 386 <tr><td><pre class="screen">"2005-10-15 13:12:11-07:00"</pre></td></tr>
 387 <tr>
 388 <td rowspan="2" valign="top"><pre class="screen">%Y-%b-%d %H:%M:%S%F %z</pre></td>
 389 <td>Default format used when outputting ptime and local_date_time.</td>
 390 </tr>
 391 <tr><td><pre class="screen">"2005-Oct-15 13:12:11 MST"</pre></td></tr>
 392 <tr>
 393 <td rowspan="2" valign="top"><pre class="screen">%Y-%b-%d %H:%M:%S%F %ZP</pre></td>
 394 <td>Default format used when inputting ptime and local_date_time.</td>
 395 </tr>
 396 <tr><td><pre class="screen">"2005-Oct-15 13:12:11 MST-07"</pre></td></tr>
 397 <tr>
 398 <td rowspan="2" valign="top"><pre class="screen">%-%H:%M:%S%F !</pre></td>
 399 <td>Default time_duration format for output. Sign will only be displayed for negative durations.</td>
 400 </tr>
 401 <tr><td><pre class="screen">"-13:14:15.003400"</pre></td></tr>
 402 <tr>
 403 <td rowspan="2" valign="top"><pre class="screen">%H:%M:%S%F</pre></td>
 404 <td>Default time_duration format for input.</td>
 405 </tr>
 406 <tr><td><pre class="screen">"13:14:15.003400"</pre></td></tr>
 407 </tbody>
 408 </table></div>
 409 <p>
 410   </p>
 411 <p>* Signifies flags that have a behavior unique to <code class="computeroutput">date_time</code>.</p>
 412 <p># Signifies flags that have a platform-dependent behavior. These may not be supported everywhere.</p>
 413 <p>! Signifies flags that currently do not work for input.</p>
 414 </div>
 415 <p>The following table lists the available facets.</p>
 416 <a name="io_objects_table"></a><h4>
 417 <a name="idp212890672"></a>IO Objects</h4>
 418 <p>
 419     </p>
 420 <div class="informaltable"><table class="table">
 421 <colgroup>
 422 <col>
 423 <col>
 424 </colgroup>
 425 <thead><tr>
 426 <th>Output</th>
 427 <th>Input</th>
 428 </tr></thead>
 429 <tbody>
 430 <tr>
 431 <td><code class="computeroutput"><a class="link" href="../boost/date_time/date_facet.html" title="Class template date_facet">date_facet</a></code></td>
 432 <td><code class="computeroutput"><a class="link" href="../boost/date_time/date_input_facet.html" title="Class template date_input_facet">date_input_facet</a></code></td>
 433 </tr>
 434 <tr>
 435 <td><code class="computeroutput"><a class="link" href="../boost/date_time/date_facet.html" title="Class template date_facet">wdate_facet</a></code></td>
 436 <td><code class="computeroutput"><a class="link" href="../boost/date_time/date_input_facet.html" title="Class template date_input_facet">wdate_input_facet</a></code></td>
 437 </tr>
 438 <tr>
 439 <td><code class="computeroutput"><a class="link" href="../boost/date_time/time_facet.html" title="Class template time_facet">time_facet</a></code></td>
 440 <td><code class="computeroutput"><a class="link" href="../boost/date_time/time_input_facet.html" title="Class template time_input_facet">time_input_facet</a></code></td>
 441 </tr>
 442 <tr>
 443 <td><code class="computeroutput"><a class="link" href="../boost/date_time/time_facet.html" title="Class template time_facet">wtime_facet</a></code></td>
 444 <td><code class="computeroutput"><a class="link" href="../boost/date_time/time_input_facet.html" title="Class template time_input_facet">wtime_input_facet</a></code></td>
 445 </tr>
 446 <tr>
 447 <td>
 448 <code class="computeroutput"><a class="link" href="../boost/date_time/time_facet.html" title="Class template time_facet">local_time_facet</a></code>*</td>
 449 <td>
 450 <code class="computeroutput"><a class="link" href="../boost/date_time/time_input_facet.html" title="Class template time_input_facet">local_time_input_facet</a></code>*</td>
 451 </tr>
 452 <tr>
 453 <td>
 454 <code class="computeroutput"><a class="link" href="../boost/date_time/time_facet.html" title="Class template time_facet">wlocal_time_facet</a></code>*</td>
 455 <td>
 456 <code class="computeroutput"><a class="link" href="../boost/date_time/time_input_facet.html" title="Class template time_input_facet">wlocal_time_input_facet</a></code>*</td>
 457 </tr>
 458 </tbody>
 459 </table></div>
 460 <p>
 461     * These links lead to the <code class="computeroutput">time_facet</code> and <code class="computeroutput">time_input_facet</code> reference sections. They are not actual classes but typedefs.
 462   </p>
 463 <h4>
 464 <a name="idp212916320"></a>Formatter/Parser Objects</h4>
 465 <p>To implement the new i/o facets the date-time library uses a number of new parsers and formatters. These classes are available for users that want to implement specialized input/output routines.</p>
 466 <p>
 467     </p>
 468 <div class="informaltable"><table class="table">
 469 <colgroup>
 470 <col>
 471 <col>
 472 </colgroup>
 473 <thead><tr>
 474 <th>Output</th>
 475 <th>Input</th>
 476 </tr></thead>
 477 <tbody>
 478 <tr>
 479 <td><code class="computeroutput"><a class="link" href="../boost/date_time/period_formatter.html" title="Class template period_formatter">period_formatter</a></code></td>
 480 <td><code class="computeroutput"><a class="link" href="../boost/date_time/period_parser.html" title="Class template period_parser">period_parser</a></code></td>
 481 </tr>
 482 <tr>
 483 <td><code class="computeroutput"><a class="link" href="../boost/date_time/date_generator_formatter.html" title="Class template date_generator_formatter">date_generator_formatter</a></code></td>
 484 <td><code class="computeroutput"><a class="link" href="../boost/date_time/date_generator_parser.html" title="Class template date_generator_parser">date_generator_parser</a></code></td>
 485 </tr>
 486 <tr>
 487 <td><code class="computeroutput"><a class="link" href="../boost/date_time/special_values_formatter.html" title="Class template special_values_formatter">special_values_formatter</a></code></td>
 488 <td><code class="computeroutput"><a class="link" href="../boost/date_time/special_values_parser.html" title="Class template special_values_parser">special_values_parser</a></code></td>
 489 </tr>
 490 <tr>
 491 <td>&#160;</td>
 492 <td><code class="computeroutput"><a class="link" href="../boost/date_time/format_date_parser.html" title="Class template format_date_parser">format_date_parser</a></code></td>
 493 </tr>
 494 </tbody>
 495 </table></div>
 496 <p>
 497   </p>
 498 <div class="section">
 499 <div class="titlepage"><div><div><h3 class="title">
 500 <a name="date_time.date_facet"></a>Date Facet</h3></div></div></div>
 501 <a class="link" href="date_time_io.html#date_facet_intro">Introduction</a> -
 502   <a class="link" href="date_time_io.html#date_facet_constr">Construction</a> -
 503   <a class="link" href="date_time_io.html#date_facet_accessors">Accessors</a><a name="date_facet_intro"></a><h4>
 504 <a name="idp212938672"></a>Introduction</h4>
 505 <p>The <code class="computeroutput">boost::date_time::date_facet</code> enables users to have significant control over the output streaming of dates (and other gregorian objects). The date_facet is typedef'd in the <code class="computeroutput">gregorian</code> namespace as <code class="computeroutput">date_facet</code> and <code class="computeroutput">wdate_facet</code>.
 506   </p>
 507 <a name="date_facet_constr"></a><h4>
 508 <a name="idp212943488"></a>Construction</h4>
 509 <p>
 510     </p>
 511 <div class="informaltable"><table class="table">
 512 <colgroup>
 513 <col>
 514 <col>
 515 </colgroup>
 516 <thead><tr>
 517 <th>Syntax</th>
 518 <th>Description</th>
 519 </tr></thead>
 520 <tbody>
 521 <tr>
 522 <td valign="top"><pre class="screen">date_facet()</pre></td>
 523 <td>Default constructor</td>
 524 </tr>
 525 <tr>
 526 <td valign="top"><pre class="screen">date_facet(...)
 527   Parameters:
 528     char_type* format
 529     input_collection_type</pre></td>
 530 <td>Format given will be used for date output. All other formats will use their defaults. Collection is the set of short names to be used for months. All other name collections will use their defaults.</td>
 531 </tr>
 532 <tr>
 533 <td valign="top"><pre class="screen">date_facet(...)
 534   Parameters:
 535     char_type* format
 536     period_formatter_type
 537     special_values_formatter_type
 538     date_gen_formatter_type</pre></td>
 539 <td>Format given will be used for date output. The remaining parameters are formatter objects. Further details on these objects can be found <a class="link" href="date_time_io.html#date_time.io_objects" title="Date Time Formatter/Parser Objects">here</a>. This constructor also provides default arguments for all parameters except the format. Therefore, <code class="computeroutput">date_facet("%m %d %Y")</code> will work.</td>
 540 </tr>
 541 </tbody>
 542 </table></div>
 543 <p>
 544   </p>
 545 <a name="date_facet_accessors"></a><h4>
 546 <a name="idp212956304"></a>Accessors</h4>
 547 <p>
 548     </p>
 549 <div class="informaltable"><table class="table">
 550 <colgroup>
 551 <col>
 552 <col>
 553 </colgroup>
 554 <thead>
 555 <tr>
 556 <th rowspan="2" valign="top">Syntax</th>
 557 <th>Description</th>
 558 </tr>
 559 <tr><th>Example</th></tr>
 560 </thead>
 561 <tbody>
 562 <tr>
 563 <td rowspan="2" valign="top"><pre class="screen">void format(char_type*)</pre></td>
 564 <td>Set the format for dates.</td>
 565 </tr>
 566 <tr><td><pre class="screen">date_facet* f = new date_facet();
 567 f-&gt;format("%m %d %Y");</pre></td></tr>
 568 <tr>
 569 <td rowspan="2" valign="top"><pre class="screen">void set_iso_format()</pre></td>
 570 <td>Sets the date format to ISO</td>
 571 </tr>
 572 <tr><td><pre class="screen">f-&gt;set_iso_format();
 573 // "%Y%m%d"</pre></td></tr>
 574 <tr>
 575 <td rowspan="2" valign="top"><pre class="screen">void set_iso_extended_format()</pre></td>
 576 <td>Sets the date format to ISO Extended</td>
 577 </tr>
 578 <tr><td><pre class="screen">f-&gt;set_iso_extended_format();
 579 // "%Y-%m-%d"</pre></td></tr>
 580 <tr>
 581 <td rowspan="2" valign="top"><pre class="screen">void month_format(char_type*)</pre></td>
 582 <td>Set the format for months when they are 'put' individually.</td>
 583 </tr>
 584 <tr><td><pre class="screen">f-&gt;month_format("%B");
 585 ss &lt;&lt; greg_month(12); // "December"</pre></td></tr>
 586 <tr>
 587 <td rowspan="2" valign="top"><pre class="screen">void weekday_format(char_type*)</pre></td>
 588 <td>Set the format for weekdays when they are 'put' individually.</td>
 589 </tr>
 590 <tr><td><pre class="screen">f-&gt;weekday_format("%a");
 591 ss &lt;&lt; greg_weekday(2); // "Tue"</pre></td></tr>
 592 <tr>
 593 <td rowspan="2" valign="top"><pre class="screen">void period_formatter(...)
 594   Parameter:
 595     period_formatter_type</pre></td>
 596 <td>Replaces the period formatter object with a user created one.</td>
 597 </tr>
 598 <tr><td>see the <a class="link" href="date_time_io.html#date_time.io_tutorial" title="Date Time IO Tutorial">tutorial</a> for a complete example.</td></tr>
 599 <tr>
 600 <td rowspan="2" valign="top"><pre class="screen">void special_values_formatter(...)
 601   Parameter:
 602     special_values_formatter_type</pre></td>
 603 <td>Replaces the special_values formatter object with a user created one.</td>
 604 </tr>
 605 <tr><td>see the <a class="link" href="date_time_io.html#date_time.io_tutorial" title="Date Time IO Tutorial">tutorial</a> for a complete example.</td></tr>
 606 <tr>
 607 <td rowspan="2" valign="top"><pre class="screen">void date_gen_phrase_strings(...)
 608   Parameters:
 609     input_collection_type
 610     date_gen_formatter_type::
 611       phrase_elements</pre></td>
 612 <td>Sets new date generator phrase strings in date_gen_formatter. The input collection is a vector of strings (for details on these strings see <a class="link" href="date_time_io.html#io_objects.date_generators">date generator formatter/parser documentation</a>). The phrase_elements parameter is an enum, defined in the date_generator_formatter object, that has a default value of 'first'. It is used to indicate what the position of the first string in the collection will be.</td>
 613 </tr>
 614 <tr><td><pre class="screen"></pre></td></tr>
 615 <tr>
 616 <td rowspan="2" valign="top"><pre class="screen">void short_weekday_names(...)
 617   Parameter:
 618     input_collection_type</pre></td>
 619 <td>Replace strings used when 'putting' short weekdays.</td>
 620 </tr>
 621 <tr><td>see the <a class="link" href="date_time_io.html#date_time.io_tutorial" title="Date Time IO Tutorial">tutorial</a> for a complete example.</td></tr>
 622 <tr>
 623 <td rowspan="2" valign="top"><pre class="screen">void long_weekday_names(...)
 624   Parameter:
 625     input_collection_type</pre></td>
 626 <td>Replace strings used when 'putting' long weekdays.</td>
 627 </tr>
 628 <tr><td>see the <a class="link" href="date_time_io.html#date_time.io_tutorial" title="Date Time IO Tutorial">tutorial</a> for a complete example.</td></tr>
 629 <tr>
 630 <td rowspan="2" valign="top"><pre class="screen">void short_month_names(...)
 631   Parameter:
 632     input_collection_type</pre></td>
 633 <td>Replace strings used when 'putting' short months.</td>
 634 </tr>
 635 <tr><td>see the <a class="link" href="date_time_io.html#date_time.io_tutorial" title="Date Time IO Tutorial">tutorial</a> for a complete example.</td></tr>
 636 <tr>
 637 <td rowspan="2" valign="top"><pre class="screen">void long_month_names(...)
 638   Parameter:
 639     input_collection_type</pre></td>
 640 <td>Replace strings used when 'putting' long months.</td>
 641 </tr>
 642 <tr><td>see the <a class="link" href="date_time_io.html#date_time.io_tutorial" title="Date Time IO Tutorial">tutorial</a> for a complete example.</td></tr>
 643 <tr>
 644 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(...)
 645   Common parameters for all
 646   'put' functions:
 647     OutItrT
 648     ios_base
 649     char_type
 650   Unique parameter for 'put' funcs:
 651     gregorian object</pre></td>
 652 <td>There are 12 put functions in the date_facet. The common paraeters are: an iterator pointing to the next item in the stream, an ios_base object, and the fill character. Each unique gregorian object has it's own put function. Each unique put function is described below.</td>
 653 </tr>
 654 <tr><td><pre class="screen"></pre></td></tr>
 655 <tr>
 656 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(..., date)</pre></td>
 657 <td>Puts a date object into the stream using the format set by <code class="computeroutput">format(...)</code> or the default.</td>
 658 </tr>
 659 <tr><td><pre class="screen"></pre></td></tr>
 660 <tr>
 661 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(..., days)</pre></td>
 662 <td>Puts a days object into the stream as a number.</td>
 663 </tr>
 664 <tr><td><pre class="screen"></pre></td></tr>
 665 <tr>
 666 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(..., month)</pre></td>
 667 <td>Puts a month object into the stream using the format set by <code class="computeroutput">month_format(...)</code> or the default.</td>
 668 </tr>
 669 <tr><td><pre class="screen"></pre></td></tr>
 670 <tr>
 671 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(..., day)</pre></td>
 672 <td>Puts a day of month object into the stream as a two digit number.</td>
 673 </tr>
 674 <tr><td><pre class="screen">"01" // January 1st</pre></td></tr>
 675 <tr>
 676 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(..., day_of_week)</pre></td>
 677 <td>Puts a day of week object into the stream using the format set by <code class="computeroutput">weekday_format(...)</code> or the default.</td>
 678 </tr>
 679 <tr><td><pre class="screen"></pre></td></tr>
 680 <tr>
 681 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(..., date_period)</pre></td>
 682 <td>Puts a date_period into the stream. The format of the dates will use the format set by <code class="computeroutput">format(..)</code> or the default date format. The type of period (open or closed range) and the delimiters used are those used by the period_formatter.</td>
 683 </tr>
 684 <tr><td><pre class="screen"></pre></td></tr>
 685 <tr>
 686 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(..., partial_date)</pre></td>
 687 <td>Puts a partial_date date_generator object into the stream. The month format used is set by <code class="computeroutput">month_format(..)</code> or the default. The day of month is represented as a two digit number.</td>
 688 </tr>
 689 <tr><td><pre class="screen">"01 Jan" // default formats
 690 "01 January" // long month format</pre></td></tr>
 691 <tr>
 692 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(..., date_generator)
 693   Date Generator Type:
 694     nth_day_of_the_week_in_month</pre></td>
 695 <td>Puts a nth_day_of_the_week_in_month object into the stream. The month format is set by <code class="computeroutput">month_format(...)</code> or the default. The weekday format is set by <code class="computeroutput">weekday_format(...)</code> or the default. The remaining phrase elements are set in the <a class="link" href="date_time_io.html#io_objects.date_generators">date_generator_formatter</a>.</td>
 696 </tr>
 697 <tr><td><pre class="screen">"third Fri in May" // defaults</pre></td></tr>
 698 <tr>
 699 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(..., date_generator)
 700   Date Generator Type:
 701     first_day_of_the_week_in_month</pre></td>
 702 <td>Puts a first_day_of_the_week_in_month object into the stream. The month format is set by <code class="computeroutput">month_format(...)</code> or the default. The weekday format is set by <code class="computeroutput">weekday_format(...)</code> or the default. The remaining phrase elements are set in the <a class="link" href="date_time_io.html#io_objects.date_generators">date_generator_formatter</a>.</td>
 703 </tr>
 704 <tr><td><pre class="screen">"first Wed of Jun" // defaults</pre></td></tr>
 705 <tr>
 706 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(..., date_generator)
 707   Date Generator Type:
 708     last_day_of_the_week_in_month</pre></td>
 709 <td>Puts a last_day_of_the_week_in_month object into the stream. The month format is set by <code class="computeroutput">month_format(...)</code> or the default. The weekday format is set by <code class="computeroutput">weekday_format(...)</code> or the default. The remaining phrase elements are set in the <a class="link" href="date_time_io.html#io_objects.date_generators">date_generator_formatter</a>.</td>
 710 </tr>
 711 <tr><td><pre class="screen">"last Tue of Mar" // defaults</pre></td></tr>
 712 <tr>
 713 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(..., date_generator)
 714   Date Generator Type:
 715     first_day_of_the_week_after</pre></td>
 716 <td>Puts a first_day_of_the_week_after object into the stream. The weekday format is set by <code class="computeroutput">weekday_format(...)</code> or the default. The remaining phrase elements are set in the <a class="link" href="date_time_io.html#io_objects.date_generators">date_generator_formatter</a>.</td>
 717 </tr>
 718 <tr><td><pre class="screen">"first Sat after" // defaults</pre></td></tr>
 719 <tr>
 720 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(..., date_generator)
 721   Date Generator Type:
 722     first_day_of_the_week_before</pre></td>
 723 <td>Puts a first_day_of_the_week_before object into the stream. The weekday format is set by <code class="computeroutput">weekday_format(...)</code> or the default. The remaining phrase elements are set in the <a class="link" href="date_time_io.html#io_objects.date_generators">date_generator_formatter</a>.</td>
 724 </tr>
 725 <tr><td><pre class="screen">"first Mon before" // defaults</pre></td></tr>
 726 </tbody>
 727 </table></div>
 728 <p>
 729   </p>
 730 </div>
 731 <div class="section">
 732 <div class="titlepage"><div><div><h3 class="title">
 733 <a name="date_time.date_input_facet"></a>Date Input Facet</h3></div></div></div>
 734 <a class="link" href="date_time_io.html#date_input_facet_intro">Introduction</a> -
 735   <a class="link" href="date_time_io.html#date_input_facet_constr">Construction</a> -
 736   <a class="link" href="date_time_io.html#date_input_facet_accessors">Accessors</a><a name="date_input_facet_intro"></a><h4>
 737 <a name="idp213069280"></a>Introduction</h4>
 738 <p>The <code class="computeroutput">boost::date_time::date_input_facet</code> enables users to have significant control how dates (and other gregorian objects) are streamed in. The date_input_facet is typedef'd in the <code class="computeroutput">gregorian</code> namespace as <code class="computeroutput">date_input_facet</code> and <code class="computeroutput">wdate_input_facet</code>.
 739   </p>
 740 <a name="date_input_facet_constr"></a><h4>
 741 <a name="idp213074048"></a>Construction</h4>
 742 <p>
 743     </p>
 744 <div class="informaltable"><table class="table">
 745 <colgroup>
 746 <col>
 747 <col>
 748 </colgroup>
 749 <thead><tr>
 750 <th>Syntax</th>
 751 <th>Description</th>
 752 </tr></thead>
 753 <tbody>
 754 <tr>
 755 <td valign="top"><pre class="screen">date_input_facet()</pre></td>
 756 <td>Default constructor</td>
 757 </tr>
 758 <tr>
 759 <td valign="top"><pre class="screen">date_input_facet(string_type format)</pre></td>
 760 <td>Format given will be used for date input. All other formats will use their defaults.</td>
 761 </tr>
 762 <tr>
 763 <td valign="top"><pre class="screen">date_input_facet(...)
 764   Parameters:
 765     string_type format
 766     format_date_parser_type
 767     special_values_parser_type
 768     period_parser_type
 769     date_gen_parser_type</pre></td>
 770 <td>Format given will be used for date input. The remaining parameters are parser objects. Further details on these objects can be found <a class="link" href="date_time_io.html#date_time.io_objects" title="Date Time Formatter/Parser Objects">here</a>.</td>
 771 </tr>
 772 </tbody>
 773 </table></div>
 774 <p>
 775   </p>
 776 <a name="date_input_facet_accessors"></a><h4>
 777 <a name="idp213085792"></a>Accessors</h4>
 778 <p>
 779     </p>
 780 <div class="informaltable"><table class="table">
 781 <colgroup>
 782 <col>
 783 <col>
 784 </colgroup>
 785 <thead>
 786 <tr>
 787 <th rowspan="2" valign="top">Syntax</th>
 788 <th>Description</th>
 789 </tr>
 790 <tr><th>Example</th></tr>
 791 </thead>
 792 <tbody>
 793 <tr>
 794 <td rowspan="2" valign="top"><pre class="screen">void format(char_type*)</pre></td>
 795 <td>Set the format for dates.</td>
 796 </tr>
 797 <tr><td><pre class="screen">date_input_facet* f =
 798     new date_input_facet();
 799 f-&gt;format("%m %d %Y");</pre></td></tr>
 800 <tr>
 801 <td rowspan="2" valign="top"><pre class="screen">void set_iso_format()</pre></td>
 802 <td>Sets the date format to ISO</td>
 803 </tr>
 804 <tr><td><pre class="screen">f-&gt;set_iso_format();
 805 // "%Y%m%d"</pre></td></tr>
 806 <tr>
 807 <td rowspan="2" valign="top"><pre class="screen">void set_iso_extended_format()</pre></td>
 808 <td>Sets the date format to ISO Extended</td>
 809 </tr>
 810 <tr><td><pre class="screen">f-&gt;set_iso_extended_format();
 811 // "%Y-%m-%d"</pre></td></tr>
 812 <tr>
 813 <td rowspan="2" valign="top"><pre class="screen">void month_format(char_type*)</pre></td>
 814 <td>Set the format when 'get'ing months individually.</td>
 815 </tr>
 816 <tr><td><pre class="screen">f-&gt;month_format("%B");
 817 ss.str("March");
 818 ss &gt;&gt; m; // March</pre></td></tr>
 819 <tr>
 820 <td rowspan="2" valign="top"><pre class="screen">void weekday_format(char_type*)</pre></td>
 821 <td>Set the format when 'get'ing weekdays individually.</td>
 822 </tr>
 823 <tr><td><pre class="screen">f-&gt;weekday_format("%a");
 824 ss.str("Sun");
 825 ss &gt;&gt; wd; // Sunday</pre></td></tr>
 826 <tr>
 827 <td rowspan="2" valign="top"><pre class="screen">void year_format(char_type*)</pre></td>
 828 <td>Set the format when 'get'ing years individually.</td>
 829 </tr>
 830 <tr><td><pre class="screen">f-&gt;weekday_format("%y");
 831 ss.str("04");
 832 ss &gt;&gt; year; // 2004</pre></td></tr>
 833 <tr>
 834 <td rowspan="2" valign="top"><pre class="screen">void period_parser(...)
 835   Parameter:
 836     period_parser_type</pre></td>
 837 <td>Replaces the period parser object with a user created one.</td>
 838 </tr>
 839 <tr><td>see the <a class="link" href="date_time_io.html#date_time.io_tutorial" title="Date Time IO Tutorial">tutorial</a> for a complete example.</td></tr>
 840 <tr>
 841 <td rowspan="2" valign="top"><pre class="screen">void special_values_parser(...)
 842   Parameter:
 843     special_values_parser_type</pre></td>
 844 <td>Replaces the special_values parser object with a user created one.</td>
 845 </tr>
 846 <tr><td>see the <a class="link" href="date_time_io.html#date_time.io_tutorial" title="Date Time IO Tutorial">tutorial</a> for a complete example.</td></tr>
 847 <tr>
 848 <td rowspan="2" valign="top"><pre class="screen">void date_gen_phrase_strings(...)
 849   Parameters:
 850     input_collection_type</pre></td>
 851 <td>Sets new date generator phrase strings in date_gen_parser. The input collection is a vector of strings (for details on these strings see <a class="link" href="date_time_io.html#io_objects.date_generators">date generator formatter/parser documentation</a>).</td>
 852 </tr>
 853 <tr><td><pre class="screen"></pre></td></tr>
 854 <tr>
 855 <td rowspan="2" valign="top"><pre class="screen">void short_weekday_names(...)
 856   Parameter:
 857     input_collection_type</pre></td>
 858 <td>Replace strings used when 'getting' short weekdays.</td>
 859 </tr>
 860 <tr><td>see the <a class="link" href="date_time_io.html#date_time.io_tutorial" title="Date Time IO Tutorial">tutorial</a> for a complete example.</td></tr>
 861 <tr>
 862 <td rowspan="2" valign="top"><pre class="screen">void long_weekday_names(...)
 863   Parameter:
 864     input_collection_type</pre></td>
 865 <td>Replace strings used when 'getting' long weekdays.</td>
 866 </tr>
 867 <tr><td>see the <a class="link" href="date_time_io.html#date_time.io_tutorial" title="Date Time IO Tutorial">tutorial</a> for a complete example.</td></tr>
 868 <tr>
 869 <td rowspan="2" valign="top"><pre class="screen">void short_month_names(...)
 870   Parameter:
 871     input_collection_type</pre></td>
 872 <td>Replace strings used when 'getting' short months.</td>
 873 </tr>
 874 <tr><td>see the <a class="link" href="date_time_io.html#date_time.io_tutorial" title="Date Time IO Tutorial">tutorial</a> for a complete example.</td></tr>
 875 <tr>
 876 <td rowspan="2" valign="top"><pre class="screen">void long_month_names(...)
 877   Parameter:
 878     input_collection_type</pre></td>
 879 <td>Replace strings used when 'getting' long months.</td>
 880 </tr>
 881 <tr><td>see the <a class="link" href="date_time_io.html#date_time.io_tutorial" title="Date Time IO Tutorial">tutorial</a> for a complete example.</td></tr>
 882 <tr>
 883 <td rowspan="2" valign="top"><pre class="screen">InItrT get(...)
 884   Common parameters for all
 885   'get' functions:
 886     InItrT from
 887     InItrT to
 888     ios_base
 889   Unique parameter for 'get' funcs:
 890     gregorian object</pre></td>
 891 <td>There are 13 get functions in the date_input_facet. The common parameters are: an iterator pointing to the begining of the stream, an iterator pointing to the end of the stream, and an ios_base object. Each unique gregorian object has it's own get function. Each unique get function is described below.</td>
 892 </tr>
 893 <tr><td><pre class="screen"></pre></td></tr>
 894 <tr>
 895 <td rowspan="2" valign="top"><pre class="screen">InItrT get(..., date)</pre></td>
 896 <td>Gets a date object from the stream using the format set by <code class="computeroutput">format(...)</code> or the default.</td>
 897 </tr>
 898 <tr><td><pre class="screen">ss.str("2005-Jan-01");
 899 ss &gt;&gt; d; // default format</pre></td></tr>
 900 <tr>
 901 <td rowspan="2" valign="top"><pre class="screen">InItrT get(..., month)</pre></td>
 902 <td>Gets a month object from the stream using the format set by <code class="computeroutput">month_format(...)</code> or the default.</td>
 903 </tr>
 904 <tr><td><pre class="screen">ss.str("Feb");
 905 ss &gt;&gt; m; // default format</pre></td></tr>
 906 <tr>
 907 <td rowspan="2" valign="top"><pre class="screen">InItrT get(..., day_of_week)</pre></td>
 908 <td>Gets a day of week object from the stream using the format set by <code class="computeroutput">weekday_format(...)</code> or the default.</td>
 909 </tr>
 910 <tr><td><pre class="screen">ss.str("Sun");
 911 ss &gt;&gt; dow; // default format</pre></td></tr>
 912 <tr>
 913 <td rowspan="2" valign="top"><pre class="screen">InItrT get(..., day)</pre></td>
 914 <td>Gets a day of month object from the stream as a two digit number.</td>
 915 </tr>
 916 <tr><td><pre class="screen">"01" // January 1st</pre></td></tr>
 917 <tr>
 918 <td rowspan="2" valign="top"><pre class="screen">InItrT get(..., year)</pre></td>
 919 <td>Gets a year object from the stream as a number. The number of expected digits depends on the year format.</td>
 920 </tr>
 921 <tr><td><pre class="screen">ss/str("2005");
 922 ss &gt;&gt; y; // default format</pre></td></tr>
 923 <tr>
 924 <td rowspan="2" valign="top"><pre class="screen">InItrT get(..., days)</pre></td>
 925 <td>Gets a days object from the stream as a number.</td>
 926 </tr>
 927 <tr><td><pre class="screen">ss.str("356");
 928 ss &gt;&gt; dys; // a full year</pre></td></tr>
 929 <tr>
 930 <td rowspan="2" valign="top"><pre class="screen">InItrT get(..., date_period)</pre></td>
 931 <td>Gets a date_period from the stream. The format of the dates will use the format set by <code class="computeroutput">format(..)</code> or the default date format. The type of period (open or closed range) and the delimiters used are those used by the period_parser.</td>
 932 </tr>
 933 <tr><td>see the <a class="link" href="date_time_io.html#date_time.io_tutorial" title="Date Time IO Tutorial">tutorial</a> for a complete example.</td></tr>
 934 <tr>
 935 <td rowspan="2" valign="top"><pre class="screen">InItrT get(..., partial_date)</pre></td>
 936 <td>Gets a partial_date date_generator object from the stream. The month format used is set by <code class="computeroutput">month_format(..)</code> or the default. The day of month is represented as a two digit number.</td>
 937 </tr>
 938 <tr><td><pre class="screen">"01 Jan" // default formats
 939 "01 January" // long month format</pre></td></tr>
 940 <tr>
 941 <td rowspan="2" valign="top"><pre class="screen">InItrT get(..., date_generator)
 942   Date Generator Type:
 943     nth_day_of_the_week_in_month</pre></td>
 944 <td>Gets a nth_day_of_the_week_in_month object from the stream. The month format is set by <code class="computeroutput">month_format(...)</code> or the default. The weekday format is set by <code class="computeroutput">weekday_format(...)</code> or the default. The remaining phrase elements are set in the <a class="link" href="date_time_io.html#io_objects.date_generators">date_generator_parser</a>.</td>
 945 </tr>
 946 <tr><td><pre class="screen">"third Fri in May" // defaults</pre></td></tr>
 947 <tr>
 948 <td rowspan="2" valign="top"><pre class="screen">InItrT get(..., date_generator)
 949   Date Generator Type:
 950     first_day_of_the_week_in_month</pre></td>
 951 <td>Gets a first_day_of_the_week_in_month object from the stream. The month format is set by <code class="computeroutput">month_format(...)</code> or the default. The weekday format is set by <code class="computeroutput">weekday_format(...)</code> or the default. The remaining phrase elements are set in the <a class="link" href="date_time_io.html#io_objects.date_generators">date_generator_parser</a>.</td>
 952 </tr>
 953 <tr><td><pre class="screen">"first Wed of Jun" // defaults</pre></td></tr>
 954 <tr>
 955 <td rowspan="2" valign="top"><pre class="screen">InItrT get(..., date_generator)
 956   Date Generator Type:
 957     last_day_of_the_week_in_month</pre></td>
 958 <td>Gets a last_day_of_the_week_in_month object from the stream. The month format is set by <code class="computeroutput">month_format(...)</code> or the default. The weekday format is set by <code class="computeroutput">weekday_format(...)</code> or the default. The remaining phrase elements are set in the <a class="link" href="date_time_io.html#io_objects.date_generators">date_generator_parser</a>.</td>
 959 </tr>
 960 <tr><td><pre class="screen">"last Tue of Mar" // defaults</pre></td></tr>
 961 <tr>
 962 <td rowspan="2" valign="top"><pre class="screen">InItrT get(..., date_generator)
 963   Date Generator Type:
 964     first_day_of_the_week_after</pre></td>
 965 <td>Gets a first_day_of_the_week_after object from the stream. The weekday format is set by <code class="computeroutput">weekday_format(...)</code> or the default. The remaining phrase elements are set in the <a class="link" href="date_time_io.html#io_objects.date_generators">date_generator_parser</a>.</td>
 966 </tr>
 967 <tr><td><pre class="screen">"first Sat after" // defaults</pre></td></tr>
 968 <tr>
 969 <td rowspan="2" valign="top"><pre class="screen">InItrT get(..., date_generator)
 970   Date Generator Type:
 971     first_day_of_the_week_before</pre></td>
 972 <td>Gets a first_day_of_the_week_before object from the stream. The weekday format is set by <code class="computeroutput">weekday_format(...)</code> or the default. The remaining phrase elements are set in the <a class="link" href="date_time_io.html#io_objects.date_generators">date_generator_parser</a>.</td>
 973 </tr>
 974 <tr><td><pre class="screen">"first Mon before" // defaults</pre></td></tr>
 975 </tbody>
 976 </table></div>
 977 <p>
 978   </p>
 979 </div>
 980 <div class="section">
 981 <div class="titlepage"><div><div><h3 class="title">
 982 <a name="date_time.time_facet"></a>Time Facet</h3></div></div></div>
 983 <a class="link" href="date_time_io.html#time_facet_intro">Introduction</a> -
 984   <a class="link" href="date_time_io.html#time_facet_constr">Construction</a> -
 985   <a class="link" href="date_time_io.html#time_facet_accessors">Accessors</a><a name="time_facet_intro"></a><h4>
 986 <a name="idp213206560"></a>Introduction</h4>
 987 <p>The <code class="computeroutput">boost::date_time::time_facet</code> is an extension of the <code class="computeroutput">boost::date_time::date_facet</code>. The time_facet is typedef'ed in the <code class="computeroutput">posix_time</code> namespace as <code class="computeroutput">time_facet</code> and <code class="computeroutput">wtime_facet</code>. It is typedef'd in the <code class="computeroutput">local_time</code> namespace as <code class="computeroutput">local_time_facet</code> and <code class="computeroutput">wlocal_time_facet</code>.
 988   </p>
 989 <a name="time_facet_constr"></a><h4>
 990 <a name="idp213214192"></a>Construction</h4>
 991 <p>
 992     </p>
 993 <div class="informaltable"><table class="table">
 994 <colgroup>
 995 <col>
 996 <col>
 997 </colgroup>
 998 <thead><tr>
 999 <th>Syntax</th>
1000 <th>Description</th>
1001 </tr></thead>
1002 <tbody>
1003 <tr>
1004 <td valign="top"><pre class="screen">time_facet()</pre></td>
1005 <td>Default constructor</td>
1006 </tr>
1007 <tr>
1008 <td valign="top"><pre class="screen">time_facet(...)
1009   Parameters:
1010     char_type* format
1011     period_formatter_type
1012     special_values_formatter_type
1013     date_gen_formatter_type</pre></td>
1014 <td>Format given will be used for time output. The remaining parameters are formatter objects. Further details on these objects can be found <a class="link" href="date_time_io.html#date_time.io_objects" title="Date Time Formatter/Parser Objects">here</a>. This constructor also provides default arguments for all parameters except the format. Therefore, <code class="computeroutput">time_facet("%H:%M:S %m %d %Y")</code> will work.</td>
1015 </tr>
1016 </tbody>
1017 </table></div>
1018 <p>
1019   </p>
1020 <a name="time_facet_accessors"></a><h4>
1021 <a name="idp213224800"></a>Accessors</h4>
1022 <p>
1023     The time_facet inherits all the public date_facet methods. Therefore, the date_facet methods are not listed here. Instead, they can be found by following <a class="link" href="date_time_io.html#date_time.date_facet" title="Date Facet">this</a> link.
1024     </p>
1025 <div class="informaltable"><table class="table">
1026 <colgroup>
1027 <col>
1028 <col>
1029 </colgroup>
1030 <thead>
1031 <tr>
1032 <th rowspan="2" valign="top">Syntax</th>
1033 <th>Description</th>
1034 </tr>
1035 <tr><th>Example</th></tr>
1036 </thead>
1037 <tbody>
1038 <tr>
1039 <td rowspan="2" valign="top"><pre class="screen">void time_duration_format(...)
1040   Parameter:
1041     char_type*</pre></td>
1042 <td>Sets the time_duration format. The time_duration format has the ability to display the sign of the duration. The <code class="computeroutput">'%+'</code> flag will always display the sign. The <code class="computeroutput">'%-'</code> will only display if the sign is negative. Currently the '-' and '+' characters are used to denote the sign.</td>
1043 </tr>
1044 <tr><td><pre class="screen">f-&gt;time_duration_format("%+%H:%M");
1045 // hours and minutes only w/ sign always displayed
1046 time_duration td1(3, 15, 56);
1047 time_duration td2(-12, 25, 32);
1048 ss &lt;&lt; td1; // "+03:15:56"
1049 ss &lt;&lt; td2; // "-12:25:56"
1050             </pre></td></tr>
1051 <tr>
1052 <td rowspan="2" valign="top"><pre class="screen">void set_iso_format()</pre></td>
1053 <td>Sets the date and time format to ISO.</td>
1054 </tr>
1055 <tr><td><pre class="screen">f-&gt;set_iso_format();
1056 // "%Y%m%dT%H%M%S%F%q"</pre></td></tr>
1057 <tr>
1058 <td rowspan="2" valign="top"><pre class="screen">void set_iso_extended_format()</pre></td>
1059 <td>Sets the date and time format to ISO Extended</td>
1060 </tr>
1061 <tr><td><pre class="screen">f-&gt;set_iso_extended_format();
1062 // "%Y-%m-%d %H:%M:%S%F%Q"</pre></td></tr>
1063 <tr>
1064 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(...)
1065   Common parameters for all
1066   'put' functions:
1067     OutItrT
1068     ios_base
1069     char_type
1070   Unique parameter for 'put' funcs:
1071     posix_time object</pre></td>
1072 <td>There are 3 put functions in the time_facet. The common parameters are: an iterator pointing to the next item in the stream, an ios_base object, and the fill character. Each unique posix_time object has it's own put function. Each unique put function is described below.</td>
1073 </tr>
1074 <tr><td><pre class="screen"></pre></td></tr>
1075 <tr>
1076 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(..., ptime)</pre></td>
1077 <td>Puts a ptime object into the stream using the format set by <code class="computeroutput">format(...)</code> or the default.</td>
1078 </tr>
1079 <tr><td><pre class="screen"></pre></td></tr>
1080 <tr>
1081 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(..., time_duration)</pre></td>
1082 <td>Puts a time_duration object into the stream using the format set by <code class="computeroutput">time_duration_format(...)</code> or the default.</td>
1083 </tr>
1084 <tr><td><pre class="screen"></pre></td></tr>
1085 <tr>
1086 <td rowspan="2" valign="top"><pre class="screen">OutItrT put(..., time_period)</pre></td>
1087 <td>Puts a time_period into the stream. The format of the dates and times will use the format set by <code class="computeroutput">format(..)</code> or the default date/time format. The type of period (open or closed range) and the delimiters used are those used by the period_formatter.</td>
1088 </tr>
1089 <tr><td><pre class="screen"></pre></td></tr>
1090 </tbody>
1091 </table></div>
1092 <p>
1093   </p>
1094 </div>
1095 <div class="section">
1096 <div class="titlepage"><div><div><h3 class="title">
1097 <a name="date_time.time_input_facet"></a>Time Input Facet</h3></div></div></div>
1098 <a class="link" href="date_time_io.html#time_input_facet_intro">Introduction</a> -
1099   <a class="link" href="date_time_io.html#time_input_facet_constr">Construction</a> -
1100   <a class="link" href="date_time_io.html#time_input_facet_accessors">Accessors</a><a name="time_input_facet_intro"></a><h4>
1101 <a name="idp213264208"></a>Introduction</h4>
1102 <p>The <code class="computeroutput">boost::date_time::time_input_facet</code> is an extension of the <code class="computeroutput">date_input_facet</code>. It is typedef'ed in the <code class="computeroutput">boost::posix_time</code> namespace as <code class="computeroutput">time_input_facet</code> and <code class="computeroutput">wtime_input_facet</code>. It is typedef'ed in the <code class="computeroutput">boost::local_time</code> namespace as <code class="computeroutput">local_time_input_facet</code> and <code class="computeroutput">wlocal_time_input_facet</code>.
1103   </p>
1104 <a name="time_input_facet_constr"></a><h4>
1105 <a name="idp213271776"></a>Construction</h4>
1106 <p>
1107     </p>
1108 <div class="informaltable"><table class="table">
1109 <colgroup>
1110 <col>
1111 <col>
1112 </colgroup>
1113 <thead><tr>
1114 <th>Syntax</th>
1115 <th>Description</th>
1116 </tr></thead>
1117 <tbody>
1118 <tr>
1119 <td valign="top"><pre class="screen">time_input_facet()</pre></td>
1120 <td>Default constructor</td>
1121 </tr>
1122 <tr>
1123 <td valign="top"><pre class="screen">time_input_facet(string_type)</pre></td>
1124 <td>Format given will be used for date/time input. All other formats will use their defaults.</td>
1125 </tr>
1126 <tr>
1127 <td valign="top"><pre class="screen">time_input_facet(...)
1128   Parameters:
1129     string_type format
1130     format_date_parser_type
1131     special_values_parser_type
1132     period_parser_type
1133     date_gen_parser_type</pre></td>
1134 <td>Format given will be used for date/time input. The remaining parameters are parser objects. Further details on these objects can be found <a class="link" href="date_time_io.html#date_time.io_objects" title="Date Time Formatter/Parser Objects">here</a>.</td>
1135 </tr>
1136 </tbody>
1137 </table></div>
1138 <p>
1139   </p>
1140 <a name="time_input_facet_accessors"></a><h4>
1141 <a name="idp213283552"></a>Accessors</h4>
1142 <p>
1143     The time_input_facet inherits all the public date_input_facet methods. Therefore, the date_input_facet methods are not listed here. Instead, they can be found by following <a class="link" href="date_time_io.html#date_time.date_input_facet" title="Date Input Facet">this</a> link.
1144     </p>
1145 <div class="informaltable"><table class="table">
1146 <colgroup>
1147 <col>
1148 <col>
1149 </colgroup>
1150 <thead>
1151 <tr>
1152 <th rowspan="2" valign="top">Syntax</th>
1153 <th>Description</th>
1154 </tr>
1155 <tr><th>Example</th></tr>
1156 </thead>
1157 <tbody>
1158 <tr>
1159 <td rowspan="2" valign="top"><pre class="screen">void set_iso_format()</pre></td>
1160 <td>Sets the time format to ISO</td>
1161 </tr>
1162 <tr><td><pre class="screen">f-&gt;set_iso_format();
1163 // "%Y%m%dT%H%M%S%F%q"
1164 "20051225T132536.789-0700"</pre></td></tr>
1165 <tr>
1166 <td rowspan="2" valign="top"><pre class="screen">void set_iso_extended_format()</pre></td>
1167 <td>Sets the date format to ISO Extended</td>
1168 </tr>
1169 <tr><td><pre class="screen">f-&gt;set_iso_extended_format();
1170 // "%Y-%m-%d %H:%M:%S%F %Q"
1171 "2005-12-25 13:25:36.789 -07:00"</pre></td></tr>
1172 <tr>
1173 <td rowspan="2" valign="top"><pre class="screen">void time_duration_format(...)
1174   Parameter:
1175     char_type*</pre></td>
1176 <td>Sets the time_duration format.</td>
1177 </tr>
1178 <tr><td><pre class="screen">f-&gt;time_duration_format("%H:%M");
1179 // hours and minutes only</pre></td></tr>
1180 <tr>
1181 <td rowspan="2" valign="top"><pre class="screen">InItrT get(...)
1182   Common parameters for all
1183   'get' functions:
1184     InItrT from
1185     InItrT to
1186     ios_base
1187   Unique parameter for 'get' funcs:
1188     gregorian object</pre></td>
1189 <td>There are 3 get functions in the time_input_facet. The common parameters are: an iterator pointing to the begining of the stream, an iterator pointing to the end of the stream, and an ios_base object. Each unique gregorian object has it's own get function. Each unique get function is described below.</td>
1190 </tr>
1191 <tr><td><pre class="screen"></pre></td></tr>
1192 <tr>
1193 <td rowspan="2" valign="top"><pre class="screen">InItrT get(..., ptime)</pre></td>
1194 <td>Gets a ptime object from the stream using the format set by <code class="computeroutput">format(...)</code> or the default.</td>
1195 </tr>
1196 <tr><td><pre class="screen">ss.str("2005-Jan-01 13:12:01");
1197 ss &gt;&gt; pt; // default format</pre></td></tr>
1198 <tr>
1199 <td rowspan="2" valign="top"><pre class="screen">InItrT get(..., time_duration)</pre></td>
1200 <td>Gets a time_duration object from the stream using the format set by <code class="computeroutput">time_duration_format(...)</code> or the default.</td>
1201 </tr>
1202 <tr><td><pre class="screen">ss.str("01:25:15.000123000");
1203 ss &gt;&gt; td; // default format</pre></td></tr>
1204 <tr>
1205 <td rowspan="2" valign="top"><pre class="screen">InItrT get(..., time_period)</pre></td>
1206 <td>Gets a time_period from the stream. The format of the dates/times will use the format set by <code class="computeroutput">format(..)</code> or the default date and time format. The type of period (open or closed range) and the delimiters used are those used by the period_parser.</td>
1207 </tr>
1208 <tr><td>see the <a class="link" href="date_time_io.html#date_time.io_tutorial" title="Date Time IO Tutorial">tutorial</a> for a complete example.</td></tr>
1209 </tbody>
1210 </table></div>
1211 <p>
1212   </p>
1213 </div>
1214 <div class="section">
1215 <div class="titlepage"><div><div><h3 class="title">
1216 <a name="date_time.io_objects"></a>Date Time Formatter/Parser Objects</h3></div></div></div>
1217 <h3>
1218 <a name="idp213318528"></a>Date Time Formatter/Parser Objects</h3>
1219 <a class="link" href="date_time_io.html#io_objects.periods">Periods</a> |
1220   <a class="link" href="date_time_io.html#io_objects.date_generators">Date Generators</a> |
1221   <a class="link" href="date_time_io.html#io_objects.special_values">Special Values</a> |
1222   <a class="link" href="date_time_io.html#io_objects.format_date_parser">Format Date Parser</a><a name="io_objects.periods"></a><h4>
1223 <a name="idp213323888"></a>Periods</h4>
1224 <p>The period_formatter and period_parser provide a uniform interface for the input and output of date_periods, time_periods, and in a future release, local_date_time_periods. The user has control over the delimiters, formats of the date/time components, and the form the period takes. The format of the date/time components is controlled via the date_time input and output facets.</p>
1225 <h5>
1226 <a name="idp213325328"></a>Period Form</h5>
1227 <p>Periods are constructed with open ranged parameters. The first value is the starting point, and is included in the period. The end value is not included but immediately follows the last value: [begin/end). However, a period can be streamed as either an open range or a closed range.</p>
1228 <pre class="screen">[2003-Jan-01/2003-Dec-31] &lt;-- period holding 365 days
1229 [2003-Jan-01/2004-Jan-01) &lt;-- period holding 365 days</pre>
1230 <h5>
1231 <a name="idp213327600"></a>Delimiters</h5>
1232 <p>There are four delimiters. The default values are</p>
1233 <table border="0" summary="Simple list" class="simplelist">
1234 <tr><td>"\" - separator</td></tr>
1235 <tr><td>"[" - start delimiter</td></tr>
1236 <tr><td>")" - open range end delimiter</td></tr>
1237 <tr><td>"]" - closed range end delimiter</td></tr>
1238 </table>
1239 <p>A user can provide a custom set of delimiters. Custom delimiters may contain spaces.</p>
1240 <h5>
1241 <a name="idp213331376"></a>Customization</h5>
1242 <p>The period form and delimiters can be set as construction parameters or by means of accessor functions. A custom period parser/formatter can then be used as a construction parameter to a new facet, or can be set in an existing facet via an accessor function.</p>
1243 <h5>
1244 <a name="idp213332720"></a>Period Formatter/Parser Reference</h5>
1245   The complete class reference can be found here: <code class="computeroutput"><a class="link" href="../boost/date_time/period_formatter.html" title="Class template period_formatter">Period Formatter Doxygen Reference</a></code> and here: <code class="computeroutput"><a class="link" href="../boost/date_time/period_parser.html" title="Class template period_parser">Period Parser Doxygen Reference</a></code><p>
1246     </p>
1247 <h5>
1248 <a name="idp213336272"></a>Period Formatter Construction</h5>
1249 <p>
1250     </p>
1251 <div class="informaltable"><table class="table">
1252 <colgroup>
1253 <col>
1254 <col>
1255 </colgroup>
1256 <thead><tr>
1257 <th valign="top">Syntax</th>
1258 <th>Description</th>
1259 </tr></thead>
1260 <tbody><tr>
1261 <td valign="top"><pre class="screen">period_formatter(...)
1262   Parameters:
1263     range_display_options
1264     char_type*
1265     char_type*
1266     char_type*
1267     char_type*</pre></td>
1268 <td>NOTE: All five construction parameters have default values so this constructor also doubles as the default constructor. The <code class="computeroutput">range_display_options</code> is a public type enum of the <code class="computeroutput">period_formatter</code> class. The possible choices are AS_OPEN_RANGE or AS_CLOSED_RANGE. The closed range is the default. A period has three significant points: the begining, the last, and the end. A closed range period takes the form [begin,end), where an open range period takes the form [begin,last]. The four char_type* parameters are: the period separator, the start delimiter, the open range end delimiter, and the closed range end delimiter.</td>
1269 </tr></tbody>
1270 </table></div>
1271 <p>
1272     </p>
1273 <h5>
1274 <a name="idp213344400"></a>Period Formatter Accessors</h5>
1275 <p>
1276     </p>
1277 <div class="informaltable"><table class="table">
1278 <colgroup>
1279 <col>
1280 <col>
1281 </colgroup>
1282 <thead>
1283 <tr>
1284 <th rowspan="2" valign="top">Syntax</th>
1285 <th>Description</th>
1286 </tr>
1287 <tr><th>Example</th></tr>
1288 </thead>
1289 <tbody>
1290 <tr>
1291 <td rowspan="2" valign="top"><pre class="screen">range_display_options range_option()</pre></td>
1292 <td>Returns the current setting for the range display (either AS_OPEN_RANGE or AS_CLOSED_RANGE).</td>
1293 </tr>
1294 <tr><td><pre class="screen"></pre></td></tr>
1295 <tr>
1296 <td rowspan="2" valign="top"><pre class="screen">void range_option(...)
1297   Parameter:
1298     range_display_options</pre></td>
1299 <td>Sets the option for range display (either AS_OPEN_RANGE or AS_CLOSED_RANGE).</td>
1300 </tr>
1301 <tr><td><pre class="screen"></pre></td></tr>
1302 <tr>
1303 <td rowspan="2" valign="top"><pre class="screen">void delimiter_strings(...)
1304   Parameters:
1305     string_type
1306     string_type
1307     string_type
1308     string_type</pre></td>
1309 <td>Set new delimiter strings in the formatter.</td>
1310 </tr>
1311 <tr><td><pre class="screen">string beg("-&gt;| ");
1312 string sep(" || ");
1313 string opn(" -&gt;|");
1314 string clo(" |&lt;-");
1315 pf.delimiter_strings(beg, sep,
1316                      opn, clo);</pre></td></tr>
1317 <tr>
1318 <td rowspan="2" valign="top"><pre class="screen">put_period_start_delimeter(...)
1319   Return Type:
1320     OutItrT
1321   Parameter:
1322     OutItrT</pre></td>
1323 <td>Puts the start delimiter into the stream at position pointed to by OutItrT parameter.</td>
1324 </tr>
1325 <tr><td><pre class="screen"></pre></td></tr>
1326 <tr>
1327 <td rowspan="2" valign="top"><pre class="screen">put_period_sepatator(...)
1328   Return Type:
1329     OutItrT
1330   Parameter:
1331     OutItrT</pre></td>
1332 <td>Puts the separator into the stream at position pointed to by OutItrT parameter.</td>
1333 </tr>
1334 <tr><td><pre class="screen"></pre></td></tr>
1335 <tr>
1336 <td rowspan="2" valign="top"><pre class="screen">put_period_end_delimeter(...)
1337   Return Type:
1338     OutItrT
1339   Parameter:
1340     OutItrT</pre></td>
1341 <td>Puts the end delimiter into the stream at position pointed to by OutItrT parameter.</td>
1342 </tr>
1343 <tr><td><pre class="screen"></pre></td></tr>
1344 <tr>
1345 <td rowspan="2" valign="top"><pre class="screen">OutItrT put_period(...)
1346   Parameters:
1347     OutItrT
1348     ios_base
1349     char_type
1350     period_type
1351     facet_type</pre></td>
1352 <td>Puts a period into the stream using the set values for delimiters, separator, and range display. The facet parameter is used to put the date (or time) objects of the period.</td>
1353 </tr>
1354 <tr><td><pre class="screen"></pre></td></tr>
1355 </tbody>
1356 </table></div>
1357 <p>
1358   </p>
1359 <p>
1360     </p>
1361 <h5>
1362 <a name="idp213373488"></a>Period Parser Construction</h5>
1363 <p>
1364     </p>
1365 <div class="informaltable"><table class="table">
1366 <colgroup>
1367 <col>
1368 <col>
1369 </colgroup>
1370 <thead><tr>
1371 <th valign="top">Syntax</th>
1372 <th>Description</th>
1373 </tr></thead>
1374 <tbody>
1375 <tr>
1376 <td valign="top"><pre class="screen">period_parser(...)
1377   Parameters:
1378     period_range_option
1379     char_type*
1380     char_type*
1381     char_type*
1382     char_type*</pre></td>
1383 <td>NOTE: All five construction parameters have default values so this constructor also doubles as the default constructor. The <code class="computeroutput">period_range_option</code> is a public type enum of the <code class="computeroutput">period_parser</code> class. The possible choices are AS_OPEN_RANGE or AS_CLOSED_RANGE. The closed range is the default. A period has three significant points: the begining, the last, and the end. A closed range period takes the form [begin,end), where an open range period takes the form [begin,last]. The four char_type* parameters are: the period separator, the start delimiter, the open range end delimiter, and the closed range end delimiter.</td>
1384 </tr>
1385 <tr>
1386 <td valign="top"><pre class="screen">period_parser(period_parser)</pre></td>
1387 <td>Copy constructor</td>
1388 </tr>
1389 </tbody>
1390 </table></div>
1391 <p>
1392     </p>
1393 <h5>
1394 <a name="idp213383472"></a>Period Parser Accessors</h5>
1395 <p>
1396     </p>
1397 <div class="informaltable"><table class="table">
1398 <colgroup>
1399 <col>
1400 <col>
1401 </colgroup>
1402 <thead>
1403 <tr>
1404 <th rowspan="2" valign="top">Syntax</th>
1405 <th>Description</th>
1406 </tr>
1407 <tr><th>Example</th></tr>
1408 </thead>
1409 <tbody>
1410 <tr>
1411 <td rowspan="2" valign="top"><pre class="screen">period_range_option range_option()</pre></td>
1412 <td>Returns the current setting for the period range (either AS_OPEN_RANGE or AS_CLOSED_RANGE).</td>
1413 </tr>
1414 <tr><td><pre class="screen"></pre></td></tr>
1415 <tr>
1416 <td rowspan="2" valign="top"><pre class="screen">void range_option(...)
1417   Parameter:
1418     period_range_option </pre></td>
1419 <td>Sets the option for period range (either AS_OPEN_RANGE or AS_CLOSED_RANGE).</td>
1420 </tr>
1421 <tr><td><pre class="screen"></pre></td></tr>
1422 <tr>
1423 <td rowspan="2" valign="top"><pre class="screen">void delimiter_strings(...)
1424   Parameters:
1425     string_type
1426     string_type
1427     string_type
1428     string_type</pre></td>
1429 <td>Set new delimiter strings in the parser.</td>
1430 </tr>
1431 <tr><td><pre class="screen">string beg("-&gt;| ");
1432 string sep(" || ");
1433 string opn(" -&gt;|");
1434 string clo(" |&lt;-");
1435 pp.delimiter_strings(beg, sep,
1436                      opn, clo);</pre></td></tr>
1437 <tr>
1438 <td rowspan="2" valign="top"><pre class="screen">collection_type delimiter_strings()</pre></td>
1439 <td>Returns the set of delimiter strings currently held in the parser.</td>
1440 </tr>
1441 <tr><td><pre class="screen"></pre></td></tr>
1442 <tr>
1443 <td rowspan="2" valign="top"><pre class="screen">period_type get_period(...)
1444   Parameters:
1445     stream_itr_type
1446     stream_itr_type
1447     ios_base
1448     period_type
1449     duration_type
1450     facet_type</pre></td>
1451 <td>Parses a period from the stream. The iterator parameters point to the begining and end of the stream. The duration_type is relevant to the period type, for example: A <code class="computeroutput">date_period</code> would use <code class="computeroutput">days</code> as a duration_type. The period will be parsed according to the formats and strings found in the facet parameter.</td>
1452 </tr>
1453 <tr><td><pre class="screen"></pre></td></tr>
1454 </tbody>
1455 </table></div>
1456 <p>
1457   </p>
1458 <p>_____________________________________________________</p>
1459 <a name="io_objects.date_generators"></a><h4>
1460 <a name="idp213408464"></a>Date Generators</h4>
1461 <p>The date_generator formatter and parser provide flexibility by allowing the user to use custom "phrase elements". These phrase elements are the "in-between" words in the date_generators. For example, in the date_generator "Second Monday of March", "Second" and "of" are the phrase elements, where "Monday" and "March" are the date elements. Customization of the date elements is done with the facet. The order of the date and phrase elements cannot be changed. When parsing, all elements of the date_generator phrase must parse correctly or an ios_base::failure exception will be thrown.</p>
1462 <h5>
1463 <a name="idp213410144"></a>Customization</h5>
1464 <p>The default "phrase_strings" are:
1465     </p>
1466 <table border="0" summary="Simple list" class="simplelist"><tr>
1467 <td>"first"</td>
1468 <td>"second"</td>
1469 <td>"third"</td>
1470 <td>"fourth"</td>
1471 <td>"fifth"</td>
1472 <td>"last"</td>
1473 <td>"before"</td>
1474 <td>"after"</td>
1475 <td>"of"</td>
1476 </tr></table>
1477 <p>
1478     A custom set of phrase_strings must maintain this order of occurance (Ex: "1st", "2nd", "3rd", "4th", "5th", "last", "prior", "past", "in").</p>
1479 <p> Examples using default phrase_strings and default facet formats for weekday &amp; month: </p>
1480 <pre class="screen">"first Tue of Mar"</pre>
1481 <p>And using custom phrase_strings: </p>
1482 <pre class="screen">"1st Tue in Mar"</pre>
1483 <p>
1484   </p>
1485 <p>The custom set of phrase elements can be set as construction parameters or through an accessor function.A custom date_generator parser/formatter can then be used as a construction parameter to a new facet, or can be set in an existing facet via an accessor function.</p>
1486 <p>IMPORTANT NOTE: Prior to 1.33, partial_date was output as "1 Jan" with a single *or* double digit number for the day. The new behavior is to *always* place a double digit number for the day - "01 Jan".</p>
1487 <h5>
1488 <a name="idp213419280"></a>Date Generator Reference</h5>
1489   The complete class references can be found here: <code class="computeroutput"><a class="link" href="../boost/date_time/date_generator_formatter.html" title="Class template date_generator_formatter">Date Generator Formatter Doxygen Reference</a></code> and here: <code class="computeroutput"><a class="link" href="../boost/date_time/date_generator_parser.html" title="Class template date_generator_parser">Date Generator Parser Doxygen Reference</a></code><p>
1490     </p>
1491 <h5>
1492 <a name="idp213422880"></a>Date Generator Formatter Construction</h5>
1493 <p>
1494     </p>
1495 <div class="informaltable"><table class="table">
1496 <colgroup>
1497 <col>
1498 <col>
1499 </colgroup>
1500 <thead><tr>
1501 <th valign="top">Syntax</th>
1502 <th>Description</th>
1503 </tr></thead>
1504 <tbody>
1505 <tr>
1506 <td valign="top"><pre class="screen">date_generator_formatter()</pre></td>
1507 <td>Uses the default date generator elements.</td>
1508 </tr>
1509 <tr>
1510 <td valign="top"><pre class="screen">date_generator_formatter(...)
1511   Parameters:
1512     string_type first_element
1513     string_type second_element
1514     string_type third_element
1515     string_type fourth_element
1516     string_type fifth_element
1517     string_type last_element
1518     string_type before_element
1519     string_type after_element
1520     string_type of_element</pre></td>
1521 <td>Constructs a date_generator_formatter using the given element strings.</td>
1522 </tr>
1523 </tbody>
1524 </table></div>
1525 <p>
1526     </p>
1527 <h5>
1528 <a name="idp213431168"></a>Date Generator Formatter Accessors</h5>
1529 <p>
1530     </p>
1531 <div class="informaltable"><table class="table">
1532 <colgroup>
1533 <col>
1534 <col>
1535 </colgroup>
1536 <thead>
1537 <tr>
1538 <th rowspan="2" valign="top">Syntax</th>
1539 <th>Description</th>
1540 </tr>
1541 <tr><th>Example</th></tr>
1542 </thead>
1543 <tbody>
1544 <tr>
1545 <td rowspan="2" valign="top"><pre class="screen">void elements(...)
1546   Parameters:
1547     collection_type
1548     phrase_elements</pre></td>
1549 <td>Replace the current phrase elements with a collection of new ones. The <code class="computeroutput">phrase_elements</code> parameter is an enum that indicates what the first element in the new collection is (defaults to first).</td>
1550 </tr>
1551 <tr><td><pre class="screen">// col is a collection holding
1552 // "final", "prior", "following",
1553 // and "in"
1554 typedef date_generator_formatter dgf;
1555 dgf formatter();
1556 formatter.elements(col, dgf::last);
1557 // complete elements in dgf are now:
1558 "first", "second", "third",
1559 "fourth", "fifth", "final",
1560 "prior", "following", and "in"</pre></td></tr>
1561 <tr>
1562 <td rowspan="2" valign="top"><pre class="screen">put_partial_date(...)
1563   Return Type:
1564     facet_type::OutItrT
1565   Parameters:
1566     OutItrT next
1567     ios_base
1568     char_type fill
1569     partial_date
1570     facet_type</pre></td>
1571 <td>A put function for partial_date. This is a templated function that takes a facet_type as a parameter.</td>
1572 </tr>
1573 <tr><td>Put a partial_date =&gt; "dd Month".</td></tr>
1574 <tr>
1575 <td rowspan="2" valign="top"><pre class="screen">put_nth_kday(...)
1576   Return Type:
1577     facet_type::OutItrT
1578   Parameters:
1579     OutItrT next
1580     ios_base
1581     char_type fill
1582     nth_kday_type
1583     facet_type</pre></td>
1584 <td>A put function for nth_kday_type. This is a templated function that takes a facet_type as a parameter.</td>
1585 </tr>
1586 <tr><td>Put an nth_day_of_the_week_in_month =&gt; "nth weekday of month".</td></tr>
1587 <tr>
1588 <td rowspan="2" valign="top"><pre class="screen">put_first_kday(...)
1589   Return Type:
1590     facet_type::OutItrT
1591   Parameters:
1592     OutItrT next
1593     ios_base
1594     char_type fill
1595     first_kday_type
1596     facet_type</pre></td>
1597 <td>A put function for first_kday_type. This is a templated function that takes a facet_type as a parameter.</td>
1598 </tr>
1599 <tr><td>Put a first_day_of_the_week_in_month =&gt; "first weekday of month".</td></tr>
1600 <tr>
1601 <td rowspan="2" valign="top"><pre class="screen">put_last_kday(...)
1602   Return Type:
1603     facet_type::OutItrT
1604   Parameters:
1605     OutItrT next
1606     ios_base
1607     char_type fill
1608     last_kday_type
1609     facet_type</pre></td>
1610 <td>A put function for last_kday_type. This is a templated function that takes a facet_type as a parameter.</td>
1611 </tr>
1612 <tr><td>Put a last_day_of_the_week_in_month =&gt; "last weekday of month".</td></tr>
1613 <tr>
1614 <td rowspan="2" valign="top"><pre class="screen">put_kday_before(...)
1615   Return Type:
1616     facet_type::OutItrT
1617   Parameters:
1618     OutItrT next
1619     ios_base
1620     char_type fill
1621     kday_before_type
1622     facet_type</pre></td>
1623 <td>A put function for kday_before_type. This is a templated function that takes a facet_type as a parameter.</td>
1624 </tr>
1625 <tr><td>Put a first_day_of_the_week_before =&gt; "weekday before"</td></tr>
1626 <tr>
1627 <td rowspan="2" valign="top"><pre class="screen">put_kday_after(...)
1628   Return Type:
1629     facet_type::OutItrT
1630   Parameters:
1631     OutItrT next
1632     ios_base
1633     char_type fill
1634     kday_after_type
1635     facet_type</pre></td>
1636 <td>A put function for kday_after_type. This is a templated function that takes a facet_type as a parameter.</td>
1637 </tr>
1638 <tr><td>Put a first_day_of_the_week_after =&gt; "weekday after".</td></tr>
1639 </tbody>
1640 </table></div>
1641 <p>
1642   </p>
1643 <p>
1644     </p>
1645 <h5>
1646 <a name="idp213460432"></a>Date Generator Parser Construction</h5>
1647 <p>
1648     </p>
1649 <div class="informaltable"><table class="table">
1650 <colgroup>
1651 <col>
1652 <col>
1653 </colgroup>
1654 <thead><tr>
1655 <th valign="top">Syntax</th>
1656 <th>Description</th>
1657 </tr></thead>
1658 <tbody>
1659 <tr>
1660 <td valign="top"><pre class="screen">date_generator_parser()</pre></td>
1661 <td>Uses the default date generator elements.</td>
1662 </tr>
1663 <tr>
1664 <td valign="top"><pre class="screen">date_generator_parser(...)
1665   Parameter:
1666     date_generator_parser</pre></td>
1667 <td>Copy Constructor</td>
1668 </tr>
1669 <tr>
1670 <td valign="top"><pre class="screen">date_generator_parser(...)
1671   Parameters:
1672     string_type first_element
1673     string_type second_element
1674     string_type third_element
1675     string_type fourth_element
1676     string_type fifth_element
1677     string_type last_element
1678     string_type before_element
1679     string_type after_element
1680     string_type of_element</pre></td>
1681 <td>Constructs a date_generator_parser using the given element strings.</td>
1682 </tr>
1683 </tbody>
1684 </table></div>
1685 <p>
1686     </p>
1687 <h5>
1688 <a name="idp213470592"></a>Date Generator Parser Accessors</h5>
1689 <p>
1690     </p>
1691 <div class="informaltable"><table class="table">
1692 <colgroup>
1693 <col>
1694 <col>
1695 </colgroup>
1696 <thead>
1697 <tr>
1698 <th rowspan="2" valign="top">Syntax</th>
1699 <th>Description</th>
1700 </tr>
1701 <tr><th>Example</th></tr>
1702 </thead>
1703 <tbody>
1704 <tr>
1705 <td rowspan="2" valign="top"><pre class="screen">void element_strings(...)
1706   Parameter:
1707     collection_type</pre></td>
1708 <td>Replace the set of date generator element string with a new set.</td>
1709 </tr>
1710 <tr><td><pre class="screen"></pre></td></tr>
1711 <tr>
1712 <td rowspan="2" valign="top"><pre class="screen">void element_strings(...)
1713   Parameters:
1714     string_type first
1715     string_type second
1716     string_type third
1717     string_type fourth
1718     string_type fifth
1719     string_type last
1720     string_type before
1721     string_type after
1722     string_type of</pre></td>
1723 <td>Replace the set of date generator elements with new values.</td>
1724 </tr>
1725 <tr><td><pre class="screen"></pre></td></tr>
1726 <tr>
1727 <td rowspan="2" valign="top"><pre class="screen">get_partial_date_type(...)
1728   Return Type:
1729     facet_type::partial_date_type
1730   Parameters:
1731     stream_itr_type next
1732     stream_itr_type str_end
1733     ios_base
1734     facet_type</pre></td>
1735 <td>A templated function that parses a date_generator from the stream.</td>
1736 </tr>
1737 <tr><td>Parses a partial_date =&gt; "dd Month".</td></tr>
1738 <tr>
1739 <td rowspan="2" valign="top"><pre class="screen">get_nth_kday_type(...)
1740   Return Type:
1741     facet_type::nth_kday_type
1742   Parameters:
1743     stream_itr_type next
1744     stream_itr_type str_end
1745     ios_base
1746     facet_type</pre></td>
1747 <td>A templated function that parses a date_generator from the stream.</td>
1748 </tr>
1749 <tr><td>Parses an nth_day_of_the_week_in_month =&gt; "nth weekday of month".</td></tr>
1750 <tr>
1751 <td rowspan="2" valign="top"><pre class="screen">get_first_kday_type(...)
1752   Return Type:
1753     facet_type::firat_kday_type
1754   Parameters:
1755     stream_itr_type next
1756     stream_itr_type str_end
1757     ios_base
1758     facet_type</pre></td>
1759 <td>A templated function that parses a date_generator from the stream.</td>
1760 </tr>
1761 <tr><td>Parses a first_day_of_the_week_in_month =&gt; "first weekday of month".</td></tr>
1762 <tr>
1763 <td rowspan="2" valign="top"><pre class="screen">get_last_kday_type(...)
1764   Return Type:
1765     facet_type::last_kday_type
1766   Parameters:
1767     stream_itr_type next
1768     stream_itr_type str_end
1769     ios_base
1770     facet_type</pre></td>
1771 <td>A templated function that parses a date_generator from the stream.</td>
1772 </tr>
1773 <tr><td>Parses a last_day_of_the_week_in_month =&gt; "last weekday of month".</td></tr>
1774 <tr>
1775 <td rowspan="2" valign="top"><pre class="screen">get_kday_before_type(...)
1776   Return Type:
1777     facet_type::kday_before_type
1778   Parameters:
1779     stream_itr_type next
1780     stream_itr_type str_end
1781     ios_base
1782     facet_type</pre></td>
1783 <td>A templated function that parses a date_generator from the stream.</td>
1784 </tr>
1785 <tr><td>Parses a first_day_of_the_week_before =&gt; "weekday before"</td></tr>
1786 <tr>
1787 <td rowspan="2" valign="top"><pre class="screen">get_kday_after_type(...)
1788   Return Type:
1789     facet_type::kday_after_type
1790   Parameters:
1791     stream_itr_type next
1792     stream_itr_type str_end
1793     ios_base
1794     facet_type</pre></td>
1795 <td>A templated function that parses a date_generator from the stream.</td>
1796 </tr>
1797 <tr><td>Parses a first_day_of_the_week_after =&gt; "weekday after".</td></tr>
1798 </tbody>
1799 </table></div>
1800 <p>
1801   </p>
1802 <p>_____________________________________________________</p>
1803 <a name="io_objects.special_values"></a><h4>
1804 <a name="idp213502704"></a>Special Values</h4>
1805 <p>The date_time library uses five special_values. They are:
1806     </p>
1807 <table border="0" summary="Simple list" class="simplelist"><tr>
1808 <td>not_a_date_time</td>
1809 <td>neg_infin</td>
1810 <td>pos_infin</td>
1811 <td>min_date_time</td>
1812 <td>max_date_time</td>
1813 </tr></table>
1814 <p>
1815   </p>
1816 <p>The default set of strings used to represent these types are: "not-a-date-time", "-infinity", "+infinity", "minimum-date-time", "maximum-date-time". When output, the min_date-time and max_date_time appear as normal date/time representations: "1400-Jan-01" and "9999-Dec-31" repectively.</p>
1817 <h5>
1818 <a name="idp213507520"></a>Customization</h5>
1819 <p>The special values parser/formatter allows the user to set custom strings for these special values. These strings can be set as construction parameters to a new facet, or can be set in an existing facet via an accessor function.</p>
1820 <h5>
1821 <a name="idp213508832"></a>Special Values Formatter/Parser Reference</h5>
1822   The complete class references can be found here: <code class="computeroutput"><a class="link" href="../boost/date_time/special_values_formatter.html" title="Class template special_values_formatter">Special Values Formatter Doxygen Reference</a></code> and here: <code class="computeroutput"><a class="link" href="../boost/date_time/special_values_parser.html" title="Class template special_values_parser">Special Values Parser Doxygen Reference</a></code><p>
1823     </p>
1824 <h5>
1825 <a name="idp213512400"></a>Special Values Formatter Constructor</h5>
1826 <p>
1827     </p>
1828 <div class="informaltable"><table class="table">
1829 <colgroup>
1830 <col>
1831 <col>
1832 </colgroup>
1833 <thead><tr>
1834 <th valign="top">Syntax</th>
1835 <th>Description</th>
1836 </tr></thead>
1837 <tbody>
1838 <tr>
1839 <td valign="top"><pre class="screen">special_values_formatter()</pre></td>
1840 <td>Constructor uses defaults for special value strings.</td>
1841 </tr>
1842 <tr>
1843 <td valign="top"><pre class="screen">special_values_formatter(...)
1844   Parameters:
1845     collection_type::iterator
1846     collection_type::iterator</pre></td>
1847 <td>Constructs using values in collection. NOTE: Only the first three strings of the collection will be used. Strings for minimum_date_time and maximum_date_time are ignored as those special values are output as normal dates/times.</td>
1848 </tr>
1849 <tr>
1850 <td valign="top"><pre class="screen">special_values_formatter(...)
1851   Parameters:
1852     char_type*
1853     char_type*</pre></td>
1854 <td>Constructs special values formatter from an array of strings.</td>
1855 </tr>
1856 </tbody>
1857 </table></div>
1858 <p>
1859   </p>
1860 <p>
1861     </p>
1862 <h5>
1863 <a name="idp213522976"></a>Special Values Formatter Accessors</h5>
1864 <p>
1865     </p>
1866 <div class="informaltable"><table class="table">
1867 <colgroup>
1868 <col>
1869 <col>
1870 </colgroup>
1871 <thead>
1872 <tr>
1873 <th rowspan="2" valign="top">Syntax</th>
1874 <th>Description</th>
1875 </tr>
1876 <tr><th>Example</th></tr>
1877 </thead>
1878 <tbody>
1879 <tr>
1880 <td rowspan="2" valign="top"><pre class="screen">OutItrT put_special(...)
1881   Parameters:
1882     OutItrT next
1883     special_values value</pre></td>
1884 <td>Puts the given special value into the stream.</td>
1885 </tr>
1886 <tr><td><pre class="screen">date d1(not_a_date_time);
1887 date d2(minimum_date_time);
1888 special_values_formatter formatter;
1889 formatter.put_special(itr, d1);
1890 // Puts: "not-a-date-time"
1891 formatter.put_special(itr, d2);
1892 // Puts: "1400-Jan-01"</pre></td></tr>
1893 </tbody>
1894 </table></div>
1895 <p>
1896   </p>
1897 <p>
1898     </p>
1899 <h5>
1900 <a name="idp213532160"></a>Special Values Parser Constructor</h5>
1901 <p>
1902     </p>
1903 <div class="informaltable"><table class="table">
1904 <colgroup>
1905 <col>
1906 <col>
1907 </colgroup>
1908 <thead><tr>
1909 <th valign="top">Syntax</th>
1910 <th>Description</th>
1911 </tr></thead>
1912 <tbody>
1913 <tr>
1914 <td valign="top"><pre class="screen">special_values_parser()</pre></td>
1915 <td>&#160;</td>
1916 </tr>
1917 <tr>
1918 <td valign="top"><pre class="screen">special_values_parser(...)
1919   Parameters:
1920     collection_type::iterator
1921     collection_type::iterator</pre></td>
1922 <td>Constructs a special values parser using the strings in the collection.</td>
1923 </tr>
1924 <tr>
1925 <td valign="top"><pre class="screen">special_values_parser(...)
1926   Parameter:
1927     scpecial_values_parser</pre></td>
1928 <td>Copy constructor.</td>
1929 </tr>
1930 <tr>
1931 <td valign="top"><pre class="screen">special_values_parser(...)
1932   Parameters:
1933     string_type nadt_str
1934     string_type neg_inf_str
1935     string_type pos_inf_str
1936     string_type min_dt_str
1937     string_type max_dt_str</pre></td>
1938 <td>Constructs a special values parser using the supplied strings.</td>
1939 </tr>
1940 </tbody>
1941 </table></div>
1942 <p>
1943   </p>
1944 <p>
1945     </p>
1946 <h5>
1947 <a name="idp213544368"></a>Special Values Parser Accessors</h5>
1948 <p>
1949     </p>
1950 <div class="informaltable"><table class="table">
1951 <colgroup>
1952 <col>
1953 <col>
1954 </colgroup>
1955 <thead>
1956 <tr>
1957 <th rowspan="2" valign="top">Syntax</th>
1958 <th>Description</th>
1959 </tr>
1960 <tr><th>Example</th></tr>
1961 </thead>
1962 <tbody>
1963 <tr>
1964 <td rowspan="2" valign="top"><pre class="screen">void sv_strings(...)
1965   Parameters:
1966     string_type nadt_str
1967     string_type neg_inf_str
1968     string_type pos_inf_str
1969     string_type min_dt_str
1970     string_type max_dt_str</pre></td>
1971 <td>Replace the set of special value strings with the given ones.</td>
1972 </tr>
1973 <tr><td><pre class="screen"></pre></td></tr>
1974 <tr>
1975 <td rowspan="2" valign="top"><pre class="screen">bool match(...)
1976   Parameters:
1977     stream_itr_type beg
1978     stream_itr_type end
1979     match_results</pre></td>
1980 <td>Returns true if parse was successful. Upon a successful parse, <code class="computeroutput">mr.current_match</code> will be set an int values corresponding to the equivalent special_value.</td>
1981 </tr>
1982 <tr><td><pre class="screen">// stream holds "maximum_date_time"
1983 typedef special_values_parser svp;
1984 svp parser;
1985 svp::match_results mr;
1986 if(parser.match(itr, str_end, mr)) {
1987   d = date(static_cast&lt;special_values&gt;(
1988            mr.match_results))
1989 } else {
1990   // error, failed parse
1991 }
1992 // d == "9999-Dec-31"</pre></td></tr>
1993 </tbody>
1994 </table></div>
1995 <p>
1996   </p>
1997 <p>_____________________________________________________</p>
1998 <a name="io_objects.format_date_parser"></a><h4>
1999 <a name="idp213558800"></a>Format Date Parser</h4>
2000 <p>The format date parser is the object that holds the strings for months and weekday names, as well as their abbreviations. Custom sets of strings can be set at construction time, or, the strings in an existing format_date_parser can be replaced through accessor functions. Both the constructor and the accessor functions take a vector of strings as their arguments.</p>
2001 <h5>
2002 <a name="idp213560256"></a>Format Date Parser Reference</h5>
2003   The complete class reference can be found here: <code class="computeroutput"><a class="link" href="../boost/date_time/format_date_parser.html" title="Class template format_date_parser">Doxygen Reference</a></code><p>
2004     </p>
2005 <h5>
2006 <a name="idp213562512"></a>Format Date Parser Constructor</h5>
2007 <p>
2008     </p>
2009 <div class="informaltable"><table class="table">
2010 <colgroup>
2011 <col>
2012 <col>
2013 </colgroup>
2014 <thead><tr>
2015 <th valign="top">Syntax</th>
2016 <th>Description</th>
2017 </tr></thead>
2018 <tbody>
2019 <tr>
2020 <td valign="top"><pre class="screen">format_date_parser(...)
2021                 Parameters:
2022                 string_type format
2023                 std::locale</pre></td>
2024 <td>Creates a parser that uses the given format for parsing dates (in those functions where there is no format parameter). The names and abbreviations used are extracted from the given locale.</td>
2025 </tr>
2026 <tr>
2027 <td valign="top"><pre class="screen">format_date_parser(...)
2028   Parameters:
2029     string_type format
2030     input_collection_type
2031     input_collection_type
2032     input_collection_type
2033     input_collection_type</pre></td>
2034 <td>Creates a parser from using the given components. The input_collection_type parameters are for: short month names, long month names, short weekday names, and long weekday names (in that order). These collections must contain values for every month and every weekday (begining with January and Sunday).</td>
2035 </tr>
2036 <tr>
2037 <td valign="top"><pre class="screen">format_date_parser(...)
2038   Parameters:
2039     format_date_parser</pre></td>
2040 <td>Copy Constructor</td>
2041 </tr>
2042 </tbody>
2043 </table></div>
2044 <p>
2045   </p>
2046 <p>
2047     </p>
2048 <h5>
2049 <a name="idp213573344"></a>Format Date Parser Accessors</h5>
2050 <p>
2051     </p>
2052 <div class="informaltable"><table class="table">
2053 <colgroup>
2054 <col>
2055 <col>
2056 </colgroup>
2057 <thead>
2058 <tr>
2059 <th rowspan="2" valign="top">Syntax</th>
2060 <th>Description</th>
2061 </tr>
2062 <tr><th>Example</th></tr>
2063 </thead>
2064 <tbody>
2065 <tr>
2066 <td rowspan="2" valign="top"><pre class="screen">string_type format()</pre></td>
2067 <td>Returns the format that will be used when parsing dates in those functions where there is no format parameter.</td>
2068 </tr>
2069 <tr><td><pre class="screen"></pre></td></tr>
2070 <tr>
2071 <td rowspan="2" valign="top"><pre class="screen">void format(string_type)</pre></td>
2072 <td>Sets the format that will be used when parsing dates in those functions where there is no format parameter.</td>
2073 </tr>
2074 <tr><td><pre class="screen"></pre></td></tr>
2075 <tr>
2076 <td rowspan="2" valign="top"><pre class="screen">void short_month_names(...)
2077   Parameter:
2078     input_collection_type names</pre></td>
2079 <td>Replace the short month names used by the parser. The collection must contain values for each month, starting with January.</td>
2080 </tr>
2081 <tr><td><pre class="screen"></pre></td></tr>
2082 <tr>
2083 <td rowspan="2" valign="top"><pre class="screen">void long_month_names(...)
2084   Parameter:
2085     input_collection_type names</pre></td>
2086 <td>Replace the long month names used by the parser. The collection must contain values for each month, starting with January.</td>
2087 </tr>
2088 <tr><td><pre class="screen"></pre></td></tr>
2089 <tr>
2090 <td rowspan="2" valign="top"><pre class="screen">void short_weekday_names(...)
2091   Parameter:
2092     input_collection_type names</pre></td>
2093 <td>Replace the short weekday names used by the parser. The collection must contain values for each weekday, starting with Sunday.</td>
2094 </tr>
2095 <tr><td><pre class="screen"></pre></td></tr>
2096 <tr>
2097 <td rowspan="2" valign="top"><pre class="screen">void long_weekday_names(...)
2098   Parameter:
2099     input_collection_type names</pre></td>
2100 <td>Replace the long weekday names used by the parser. The collection must contain values for each weekday, starting with Sunday.</td>
2101 </tr>
2102 <tr><td><pre class="screen"></pre></td></tr>
2103 <tr>
2104 <td rowspan="2" valign="top"><pre class="screen">date_type parse_date(...)
2105   Parameters:
2106     string_type input
2107     string_type format
2108     special_values_parser</pre></td>
2109 <td>Parse a date from the given input using the given format.</td>
2110 </tr>
2111 <tr><td><pre class="screen">string inp("2005-Apr-15");
2112 string format("%Y-%b-%d");
2113 date d;
2114 d = parser.parse_date(inp,
2115                       format,
2116                       svp);
2117 // d == 2005-Apr-15</pre></td></tr>
2118 <tr>
2119 <td rowspan="2" valign="top"><pre class="screen">date_type parse_date(...)
2120   Parameters:
2121     istreambuf_iterator input
2122     istreambuf_iterator str_end
2123     special_values_parser</pre></td>
2124 <td>Parse a date from stream using the parser's format.</td>
2125 </tr>
2126 <tr><td><pre class="screen"></pre></td></tr>
2127 <tr>
2128 <td rowspan="2" valign="top"><pre class="screen">date_type parse_date(...)
2129   Parameters:
2130     istreambuf_iterator input
2131     istreambuf_iterator str_end
2132     string_type format
2133     special_values_parser</pre></td>
2134 <td>Parse a date from stream using the given format.</td>
2135 </tr>
2136 <tr><td><pre class="screen">// stream holds "2005-04-15"
2137 string format("%Y-%m-%d");
2138 date d;
2139 d = parser.parse_date(itr,
2140                       str_end,
2141                       format,
2142                       svp);
2143 // d == 2005-Apr-15</pre></td></tr>
2144 <tr>
2145 <td rowspan="2" valign="top"><pre class="screen">month_type parse_month(...)
2146   Parameters:
2147     istreambuf_iterator input
2148     istreambuf_iterator str_end
2149     string_type format</pre></td>
2150 <td>Parses a month from stream using given format. Throws bad_month if unable to parse.</td>
2151 </tr>
2152 <tr><td><pre class="screen">// stream holds "March"
2153 string format("%B");
2154 greg_month m;
2155 m = parser.parse_month(itr,
2156                        str_end,
2157                        format);
2158 // m == March</pre></td></tr>
2159 <tr>
2160 <td rowspan="2" valign="top"><pre class="screen">day_type parse_day_of_month(...)
2161   Parameters:
2162     istreambuf_iterator input
2163     istreambuf_iterator str_end</pre></td>
2164 <td>Parses a day_of_month from stream. The day must appear as a two digit number (01-31), or a bad_day_of_month will be thrown.</td>
2165 </tr>
2166 <tr><td><pre class="screen">// stream holds "01"
2167 greg_day d;
2168 d = parser.parse_day_of_month(itr,
2169                        str_end);
2170 // d == 1st</pre></td></tr>
2171 <tr>
2172 <td rowspan="2" valign="top"><pre class="screen">day_type parse_var_day_of_month(...)
2173   Parameters:
2174     istreambuf_iterator input
2175     istreambuf_iterator str_end</pre></td>
2176 <td>Parses a day_of_month from stream. The day must appear as a one or two digit number (1-31), or a bad_day_of_month will be thrown.</td>
2177 </tr>
2178 <tr><td><pre class="screen">// stream holds "1"
2179 greg_day d;
2180 d = parser.parse_var_day_of_month(itr,
2181                        str_end);
2182 // d == 1st</pre></td></tr>
2183 <tr>
2184 <td rowspan="2" valign="top"><pre class="screen">day_of_week_type parse_weekday(...)
2185   Parameters:
2186     istreambuf_iterator input
2187     istreambuf_iterator str_end
2188     string_type format</pre></td>
2189 <td>Parse a weekday from stream according to the given format. Throws a bad_weekday if unable to parse.</td>
2190 </tr>
2191 <tr><td><pre class="screen">// stream holds "Tue"
2192 string format("%a");
2193 greg_weekday wd;
2194 wd = parser.parse_weekday(itr,
2195                           str_end,
2196                           format);
2197 // wd == Tuesday</pre></td></tr>
2198 <tr>
2199 <td rowspan="2" valign="top"><pre class="screen">year_type parse_year(...)
2200   Parameters:
2201     istreambuf_iterator input
2202     istreambuf_iterator str_end
2203     string_type format</pre></td>
2204 <td>Parse a year from stream according to given format. Throws bad year if unable to parse.</td>
2205 </tr>
2206 <tr><td><pre class="screen">// stream holds "98"
2207 string format("%y");
2208 greg_year y;
2209 y = parser.parse_year(itr,
2210                       str_end,
2211                       format);
2212 // y == 1998</pre></td></tr>
2213 </tbody>
2214 </table></div>
2215 <p>
2216   </p>
2217 </div>
2218 <div class="section">
2219 <div class="titlepage"><div><div><h3 class="title">
2220 <a name="date_time.io_tutorial"></a>Date Time IO Tutorial</h3></div></div></div>
2221 <h3>
2222 <a name="idp213628224"></a>Date Time IO Tutorial</h3>
2223 <a class="link" href="date_time_io.html#basic_use">Basic Use</a> |
2224   <a class="link" href="date_time_io.html#format_strings">Format Strings</a> |
2225   <a class="link" href="date_time_io.html#content_strings">Content Strings</a> |
2226   <a class="link" href="date_time_io.html#tut_sv">Special Values</a> |
2227   <a class="link" href="date_time_io.html#tut_dper">Date/Time Periods</a> |
2228   <a class="link" href="date_time_io.html#tut_dgen">Date Generators</a><a name="basic_use"></a><h5>
2229 <a name="idp213635600"></a>Basic Use</h5>
2230 <p>Facets are automatically imbued when operators '&gt;&gt;' and '&lt;&lt;' are called. The list of date_time objects that can be streamed are:</p>
2231 <h6>
2232 <a name="idp213636992"></a>Gregorian</h6>
2233 <p>
2234     <code class="computeroutput">date</code>,
2235     <code class="computeroutput">days</code>,
2236     <code class="computeroutput">date_period</code>,
2237     <code class="computeroutput">greg_month</code>,
2238     <code class="computeroutput">greg_weekday</code>,
2239     <code class="computeroutput">greg_year</code>,
2240     <code class="computeroutput">partial_date</code>,
2241     <code class="computeroutput">nth_day_of_the_week_in_month</code>,
2242     <code class="computeroutput">first_day_of_the_week_in_month</code>,
2243     <code class="computeroutput">last_day_of_the_week_in_month</code>,
2244     <code class="computeroutput">first_day_of_the_week_after</code>,
2245     <code class="computeroutput">first_day_of_the_week_before</code>
2246   </p>
2247 <h6>
2248 <a name="idp213646752"></a>Posix_time</h6>
2249 <p>
2250     <code class="computeroutput">ptime</code>,
2251     <code class="computeroutput">time_period</code>,
2252     <code class="computeroutput">time_duration</code>
2253   </p>
2254 <h6>
2255 <a name="idp213649952"></a>Local_time</h6>
2256 <p>
2257     <code class="computeroutput">local_date_time</code>
2258   </p>
2259 <p>
2260     The following example is of the basic use of the new IO code, utilizing all the defaults. (this example can be found in the <code class="computeroutput">libs/date_time/examples/tutorial</code> directory)
2261   </p>
2262 <pre class="programlisting">
2263
2264   date d(2004, Feb, 29);
2265   time_duration td(12,34,56,789);
2266   stringstream ss;
2267   ss &lt;&lt; d &lt;&lt; ' ' &lt;&lt; td;
2268   ptime pt(not_a_date_time);
2269   cout &lt;&lt; pt &lt;&lt; endl; // "not-a-date-time"
2270   ss &gt;&gt; pt;
2271   cout &lt;&lt; pt &lt;&lt; endl; // "2004-Feb-29 12:34:56.000789"
2272   ss.str("");
2273   ss &lt;&lt; pt &lt;&lt; " EDT-05EDT,M4.1.0,M10.5.0";
2274   local_date_time ldt(not_a_date_time);
2275   ss &gt;&gt; ldt;
2276   cout &lt;&lt; ldt &lt;&lt; endl; // "2004-Feb-29 12:34:56.000789 EDT"
2277
2278   </pre>
2279 <p>This example used the default settings for the input and output facets. The default formats are such that interoperability like that shown in the example is possible. NOTE: Input streaming of local_date_time can only be done with a <a class="link" href="local_time.html#date_time.local_time.posix_time_zone" title="Posix Time Zone">posix time zone string</a>. The default output format uses a time zone abbreviation. The format can be changed so out and in match (as we will see later in this tutorial).</p>
2280 <a name="format_strings"></a><h5>
2281 <a name="idp213656480"></a>Format Strings</h5>
2282 <p>The format strings control the order, type, and style of the date/time elements used. The facets provide some predefined formats (iso_format_specifier, iso_format_extended_specifier, and default_date_format) but the user can easily create their own.</p>
2283   (continued from previous example)
2284   <pre class="programlisting">
2285
2286   local_time_facet* output_facet = new local_time_facet();
2287   local_time_input_facet* input_facet = new local_time_input_facet();
2288   ss.imbue(locale(locale::classic(), output_facet));
2289   ss.imbue(locale(ss.getloc(), input_facet));
2290
2291   output_facet-&gt;format("%a %b %d, %H:%M %z");
2292   ss.str("");
2293   ss &lt;&lt; ldt;
2294   cout &lt;&lt; ss.str() &lt;&lt; endl; // "Sun Feb 29, 12:34 EDT"
2295
2296   output_facet-&gt;format(local_time_facet::iso_time_format_specifier);
2297   ss.str("");
2298   ss &lt;&lt; ldt;
2299   cout &lt;&lt; ss.str() &lt;&lt; endl; // "20040229T123456.000789-0500"
2300
2301   output_facet-&gt;format(local_time_facet::iso_time_format_extended_specifier);
2302   ss.str("");
2303   ss &lt;&lt; ldt;
2304   cout &lt;&lt; ss.str() &lt;&lt; endl; // "2004-02-29 12:34:56.000789-05:00"
2305
2306   </pre>
2307 <p>Format strings are not limited to date/time elements. Extra verbiage can be placed in a format string. NOTE: When extra verbiage is present in an input format, the data being input must also contain the exact verbiage.</p>
2308   (continued from previous example)
2309   <pre class="programlisting">
2310
2311   // extra words in format
2312   string my_format("The extended ordinal time %Y-%jT%H:%M can also be \
2313   represented as %A %B %d, %Y");
2314   output_facet-&gt;format(my_format.c_str());
2315   input_facet-&gt;format(my_format.c_str());
2316   ss.str("");
2317   ss &lt;&lt; ldt;
2318   cout &lt;&lt; ss.str() &lt;&lt; endl;
2319
2320   // matching extra words in input
2321   ss.str("The extended ordinal time 2005-128T12:15 can also be \
2322   represented as Sunday May 08, 2005");
2323   ss &gt;&gt; ldt;
2324   cout &lt;&lt; ldt &lt;&lt; endl;
2325
2326   </pre>
2327 <a name="content_strings"></a><h5>
2328 <a name="idp213662592"></a>Content Strings</h5>
2329 <p>So far we've shown how a user can achieve a great deal of customization with very little effort by using formats. Further customization can be achieved through user defined elements (ie strings). The elements that can be customized are: Special value names, month names, month abbreviations, weekday names, weekday abbreviations, delimiters of the date/time periods, and the phrase elements of the date_generators.</p>
2330 <p>The default values for these are as follows:</p>
2331 <h6>
2332 <a name="idp213664512"></a>Special values</h6>
2333 <p>
2334     <code class="computeroutput">not-a-date-time</code>,
2335     <code class="computeroutput">-infinity</code>,
2336     <code class="computeroutput">+infinity</code>,
2337     <code class="computeroutput">minimum-date-time</code>,
2338     <code class="computeroutput">maximum-date-time</code>
2339   </p>
2340 <h6>
2341 <a name="idp213669152"></a>Months</h6>
2342 <p>
2343     <code class="computeroutput">English calendar and three letter abbreviations</code>
2344   </p>
2345 <h6>
2346 <a name="idp213670944"></a>Weekdays</h6>
2347 <p>
2348     <code class="computeroutput">English calendar and three letter abbreviations</code>
2349   </p>
2350 <h6>
2351 <a name="idp213672736"></a>Date generator phrase elements</h6>
2352 <p>
2353     <code class="computeroutput">first</code>,
2354     <code class="computeroutput">second</code>,
2355     <code class="computeroutput">third</code>,
2356     <code class="computeroutput">fourth</code>,
2357     <code class="computeroutput">fifth</code>,
2358     <code class="computeroutput">last</code>,
2359     <code class="computeroutput">before</code>,
2360     <code class="computeroutput">after</code>,
2361     <code class="computeroutput">of</code>
2362   </p>
2363 <p>NOTE: We've shown earlier that the components of a date/time representation can be re-ordered via the format string. This is not the case with date_generators. The elements themselves can be customized but their order cannot be changed.</p>
2364 <h5>
2365 <a name="idp213680880"></a>Content Strings</h5>
2366 <p>To illustrate the customization possibilities we will use custom strings for months and weekdays (we will only use long names, is all lowercase, for this example).</p>
2367   (continued from previous example)
2368   <pre class="programlisting">
2369
2370   // set up the collections of custom strings.
2371   // only the full names are altered for the sake of brevity
2372   string month_names[12] = { "january", "february", "march",
2373                              "april", "may", "june",
2374                              "july", "august", "september",
2375                              "october", "november", "december" };
2376   vector&lt;string&gt; long_months(&amp;month_names[0], &amp;month_names[12]);
2377   string day_names[7] = { "sunday", "monday", "tuesday", "wednesday",
2378                           "thursday", "friday", "saturday" };
2379   vector&lt;string&gt; long_days(&amp;day_names[0], &amp;day_names[7]);
2380
2381   //  create date_facet and date_input_facet using all defaults
2382   date_facet* date_output = new date_facet();
2383   date_input_facet* date_input = new date_input_facet();
2384   ss.imbue(locale(ss.getloc(), date_output));
2385   ss.imbue(locale(ss.getloc(), date_input));
2386
2387   // replace names in the output facet
2388   date_output-&gt;long_month_names(long_months);
2389   date_output-&gt;long_weekday_names(long_days);
2390
2391   // replace names in the input facet
2392   date_input-&gt;long_month_names(long_months);
2393   date_input-&gt;long_weekday_names(long_days);
2394
2395   // customize month, weekday and date formats
2396   date_output-&gt;format("%Y-%B-%d");
2397   date_input-&gt;format("%Y-%B-%d");
2398   date_output-&gt;month_format("%B"); // full name
2399   date_input-&gt;month_format("%B"); // full name
2400   date_output-&gt;weekday_format("%A"); // full name
2401   date_input-&gt;weekday_format("%A"); // full name
2402
2403   ss.str("");
2404   ss &lt;&lt; greg_month(3);
2405   cout &lt;&lt; ss.str() &lt;&lt; endl; // "march"
2406   ss.str("");
2407   ss &lt;&lt; greg_weekday(3);
2408   cout &lt;&lt; ss.str() &lt;&lt; endl; // "tuesday"
2409   ss.str("");
2410   ss &lt;&lt; date(2005,Jul,4);
2411   cout &lt;&lt; ss.str() &lt;&lt; endl; // "2005-july-04"
2412
2413   </pre>
2414 <a name="tut_sv"></a><h5>
2415 <a name="idp213685696"></a>Special Values</h5>
2416 <p>Customizing the input and output of special values is best done by creating a new special_values_parser and special_values_formatter. The new strings can be set at construction time (as in the example below).</p>
2417   (continued from previous example)
2418   <pre class="programlisting">
2419
2420   // reset the formats to defaults
2421   output_facet-&gt;format(local_time_facet::default_time_format);
2422   input_facet-&gt;format(local_time_input_facet::default_time_input_format);
2423
2424   // create custom special_values parser and formatter objects
2425   // and add them to the facets
2426   string sv[5] = {"nadt","neg_inf", "pos_inf", "min_dt", "max_dt" };
2427   vector&lt;string&gt; sv_names(&amp;sv[0], &amp;sv[5]);
2428   special_values_parser sv_parser(sv_names.begin(), sv_names.end());
2429   special_values_formatter sv_formatter(sv_names.begin(), sv_names.end());
2430   output_facet-&gt;special_values_formatter(sv_formatter);
2431   input_facet-&gt;special_values_parser(sv_parser);
2432
2433   ss.str("");
2434   ldt = local_date_time(not_a_date_time);
2435   ss &lt;&lt; ldt;
2436   cout &lt;&lt; ss.str() &lt;&lt; endl; // "nadt"
2437
2438   ss.str("min_dt");
2439   ss &gt;&gt; ldt;
2440   ss.str("");
2441   ss &lt;&lt; ldt;
2442   cout &lt;&lt; ss.str() &lt;&lt; endl; // "1400-Jan-01 00:00:00 UTC"
2443
2444   </pre>
2445 <p>NOTE: even though we sent in strings for min and max to the formatter, they are ignored because those special values construct to actual dates (as shown above).</p>
2446 <a name="tut_dper"></a><h5>
2447 <a name="idp213690416"></a>Date/Time Periods</h5>
2448 <p>Customizing the input and output of periods is best done by creating a new period_parser and period_formatter. The new strings can be set at construction time (as in the example below).</p>
2449   (continued from previous example)
2450   <pre class="programlisting">
2451
2452   // all formats set back to defaults (not shown for brevity)
2453
2454   // create our date_period
2455   date_period dp(date(2005,Mar,1), days(31)); // month of march
2456
2457   // custom period formatter and parser
2458   period_formatter per_formatter(period_formatter::AS_OPEN_RANGE,
2459                                  " to ", "from ", " exclusive", " inclusive" );
2460   period_parser per_parser(period_parser::AS_OPEN_RANGE,
2461                            " to ", "from ", " exclusive" , "inclusive" );
2462
2463   // default output
2464   ss.str("");
2465   ss &lt;&lt; dp;
2466   cout &lt;&lt; ss.str() &lt;&lt; endl; // "[2005-Mar-01/2005-Mar-31]"
2467
2468   // add out custom parser and formatter to  the facets
2469   date_output-&gt;period_formatter(per_formatter);
2470   date_input-&gt;period_parser(per_parser);
2471
2472   // custom output
2473   ss.str("");
2474   ss &lt;&lt; dp;
2475   cout &lt;&lt; ss.str() &lt;&lt; endl; // "from 2005-Feb-01 to 2005-Apr-01 exclusive"
2476
2477   </pre>
2478 <a name="tut_dgen"></a><h5>
2479 <a name="idp213694144"></a>Date Generators</h5>
2480 <p>Customizing the input and output of date_generators is done by replacing the existing strings (in the facet) with new strings.</p>
2481 <p>NOTE: We've shown earlier that the components of a date/time representation can be re-ordered via the format string. This is not the case with date_generators. The elements themselves can be customized but their order cannot be changed.</p>
2482   (continued from previous example)
2483   <pre class="programlisting">
2484
2485   // custom date_generator phrases
2486   string dg_phrases[9] = { "1st", "2nd", "3rd", "4th", "5th",
2487                            "final", "prior to", "following", "in" };
2488   vector&lt;string&gt; phrases(&amp;dg_phrases[0], &amp;dg_phrases[9]);
2489
2490   // create our date_generator
2491   first_day_of_the_week_before d_gen(Monday);
2492
2493   // default output
2494   ss.str("");
2495   ss &lt;&lt; d_gen;
2496   cout &lt;&lt; ss.str() &lt;&lt; endl; // "Mon before"
2497
2498   // add our custom strings to the date facets
2499   date_output-&gt;date_gen_phrase_strings(phrases);
2500   date_input-&gt;date_gen_element_strings(phrases);
2501
2502   // custom output
2503   ss.str("");
2504   ss &lt;&lt; d_gen;
2505   cout &lt;&lt; ss.str() &lt;&lt; endl; // "Mon prior to"
2506
2507   </pre>
2508 </div>
2509 </div>
2510 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
2511 <td align="left"></td>
2512 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2005 CrystalClear Software, Inc<p>Subject to the Boost Software License, Version 1.0. (See accompanying file
2513     <code class="filename">LICENSE_1_0.txt</code> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
2514 </div></td>
2515 </tr></table>
2516 <hr>
2517 <div class="spirit-nav">
2518 <a accesskey="p" href="local_time.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../date_time.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="serialization.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
2519 </div>
2520 </body>
2521 </html>