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

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
   3 "../../../tools/boostbook/dtd/boostbook.dtd">
   4
   5 <!-- Copyright (c) 2005 CrystalClear Software, Inc.
   6      Subject to the Boost Software License, Version 1.0.
   7      (See accompanying file LICENSE_1_0.txt or  http://www.boost.org/LICENSE_1_0.txt)
   8 -->
   9
  10 <section id="date_time.date_input_facet">
  11   <title>Date Input Facet</title>
  12
  13   <link linkend="date_input_facet_intro">Introduction</link> -
  14   <link linkend="date_input_facet_constr">Construction</link> -
  15   <link linkend="date_input_facet_accessors">Accessors</link>
  16
  17   <anchor id="date_input_facet_intro" />
  18   <bridgehead renderas="sect3">Introduction</bridgehead>
  19   <para>The <code>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>gregorian</code> namespace as <code>date_input_facet</code> and <code>wdate_input_facet</code>.
  20   </para>
  21
  22   <anchor id="date_input_facet_constr" />
  23   <bridgehead renderas="sect3">Construction</bridgehead>
  24   <para>
  25     <informaltable frame="all">
  26       <tgroup cols="2">
  27         <thead>
  28           <row>
  29             <entry>Syntax</entry>
  30             <entry>Description</entry>
  31           </row>
  32         </thead>
  33         <tbody>
  34           <row>
  35             <entry valign="top"><screen>date_input_facet()</screen></entry>
  36             <entry>Default constructor</entry>
  37           </row>
  38           <row>
  39             <entry valign="top"><screen>date_input_facet(string_type format)</screen></entry>
  40             <entry>Format given will be used for date input. All other formats will use their defaults.</entry>
  41           </row>
  42           <row>
  43             <entry valign="top"><screen>date_input_facet(...)
  44   Parameters:
  45     string_type format
  46     format_date_parser_type
  47     special_values_parser_type
  48     period_parser_type
  49     date_gen_parser_type</screen></entry>
  50             <entry>Format given will be used for date input. The remaining parameters are parser objects. Further details on these objects can be found <link linkend="date_time.io_objects">here</link>.</entry>
  51           </row>
  52         </tbody>
  53       </tgroup>
  54     </informaltable>
  55   </para>
  56
  57   <anchor id="date_input_facet_accessors" />
  58   <bridgehead renderas="sect3">Accessors</bridgehead>
  59   <para>
  60     <informaltable frame="all">
  61       <tgroup cols="2">
  62         <thead>
  63           <row>
  64             <entry valign="top" morerows="1">Syntax</entry>
  65             <entry>Description</entry>
  66           </row>
  67           <row>
  68               <entry>Example</entry>
  69           </row>
  70         </thead>
  71         <tbody>
  72           <row>
  73             <entry valign="top" morerows="1"><screen>void format(char_type*)</screen></entry>
  74             <entry>Set the format for dates.</entry>
  75           </row>
  76           <row>
  77             <entry><screen>date_input_facet* f =
  78     new date_input_facet();
  79 f->format("%m %d %Y");</screen></entry>
  80           </row>
  81
  82           <row>
  83             <entry valign="top" morerows="1"><screen>void set_iso_format()</screen></entry>
  84             <entry>Sets the date format to ISO</entry>
  85           </row>
  86           <row>
  87             <entry><screen>f->set_iso_format();
  88 // "%Y%m%d"</screen></entry>
  89           </row>
  90
  91           <row>
  92             <entry valign="top" morerows="1"><screen>void set_iso_extended_format()</screen></entry>
  93             <entry>Sets the date format to ISO Extended</entry>
  94           </row>
  95           <row>
  96             <entry><screen>f->set_iso_extended_format();
  97 // "%Y-%m-%d"</screen></entry>
  98           </row>
  99
 100           <row>
 101             <entry valign="top" morerows="1"><screen>void month_format(char_type*)</screen></entry>
 102             <entry>Set the format when 'get'ing months individually.</entry>
 103           </row>
 104           <row>
 105             <entry><screen>f->month_format("%B");
 106 ss.str("March");
 107 ss >> m; // March</screen></entry>
 108           </row>
 109
 110           <row>
 111             <entry valign="top" morerows="1"><screen>void weekday_format(char_type*)</screen></entry>
 112             <entry>Set the format when 'get'ing weekdays individually.</entry>
 113           </row>
 114           <row>
 115             <entry><screen>f->weekday_format("%a");
 116 ss.str("Sun");
 117 ss >> wd; // Sunday</screen></entry>
 118           </row>
 119
 120           <row>
 121             <entry valign="top" morerows="1"><screen>void year_format(char_type*)</screen></entry>
 122             <entry>Set the format when 'get'ing years individually.</entry>
 123           </row>
 124           <row>
 125             <entry><screen>f->weekday_format("%y");
 126 ss.str("04");
 127 ss >> year; // 2004</screen></entry>
 128           </row>
 129
 130           <row>
 131             <entry valign="top" morerows="1"><screen>void period_parser(...)
 132   Parameter:
 133     period_parser_type</screen></entry>
 134             <entry>Replaces the period parser object with a user created one.</entry>
 135           </row>
 136           <row>
 137             <entry>see the <link linkend="date_time.io_tutorial">tutorial</link> for a complete example.</entry>
 138           </row>
 139
 140           <row>
 141             <entry valign="top" morerows="1"><screen>void special_values_parser(...)
 142   Parameter:
 143     special_values_parser_type</screen></entry>
 144             <entry>Replaces the special_values parser object with a user created one.</entry>
 145           </row>
 146           <row>
 147             <entry>see the <link linkend="date_time.io_tutorial">tutorial</link> for a complete example.</entry>
 148           </row>
 149
 150           <row>
 151             <entry valign="top" morerows="1"><screen>void date_gen_phrase_strings(...)
 152   Parameters:
 153     input_collection_type</screen></entry>
 154             <entry>Sets new date generator phrase strings in date_gen_parser. The input collection is a vector of strings (for details on these strings see <link linkend="io_objects.date_generators">date generator formatter/parser documentation</link>).</entry>
 155           </row>
 156           <row>
 157             <entry><screen></screen></entry>
 158           </row>
 159
 160           <row>
 161             <entry valign="top" morerows="1"><screen>void short_weekday_names(...)
 162   Parameter:
 163     input_collection_type</screen></entry>
 164             <entry>Replace strings used when 'getting' short weekdays.</entry>
 165           </row>
 166           <row>
 167             <entry>see the <link linkend="date_time.io_tutorial">tutorial</link> for a complete example.</entry>
 168           </row>
 169
 170           <row>
 171             <entry valign="top" morerows="1"><screen>void long_weekday_names(...)
 172   Parameter:
 173     input_collection_type</screen></entry>
 174             <entry>Replace strings used when 'getting' long weekdays.</entry>
 175           </row>
 176           <row>
 177             <entry>see the <link linkend="date_time.io_tutorial">tutorial</link> for a complete example.</entry>
 178           </row>
 179
 180           <row>
 181             <entry valign="top" morerows="1"><screen>void short_month_names(...)
 182   Parameter:
 183     input_collection_type</screen></entry>
 184             <entry>Replace strings used when 'getting' short months.</entry>
 185           </row>
 186           <row>
 187             <entry>see the <link linkend="date_time.io_tutorial">tutorial</link> for a complete example.</entry>
 188           </row>
 189
 190           <row>
 191             <entry valign="top" morerows="1"><screen>void long_month_names(...)
 192   Parameter:
 193     input_collection_type</screen></entry>
 194             <entry>Replace strings used when 'getting' long months.</entry>
 195           </row>
 196           <row>
 197             <entry>see the <link linkend="date_time.io_tutorial">tutorial</link> for a complete example.</entry>
 198           </row>
 199
 200           <row>
 201             <entry valign="top" morerows="1"><screen>InItrT get(...)
 202   Common parameters for all
 203   'get' functions:
 204     InItrT from
 205     InItrT to
 206     ios_base
 207   Unique parameter for 'get' funcs:
 208     gregorian object</screen></entry>
 209             <entry>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.</entry>
 210           </row>
 211           <row>
 212             <entry><screen></screen></entry>
 213           </row>
 214
 215           <row>
 216             <entry valign="top" morerows="1"><screen>InItrT get(..., date)</screen></entry>
 217             <entry>Gets a date object from the stream using the format set by <code>format(...)</code> or the default.</entry>
 218           </row>
 219           <row>
 220             <entry><screen>ss.str("2005-Jan-01");
 221 ss >> d; // default format</screen></entry>
 222           </row>
 223
 224           <row>
 225             <entry valign="top" morerows="1"><screen>InItrT get(..., month)</screen></entry>
 226             <entry>Gets a month object from the stream using the format set by <code>month_format(...)</code> or the default.</entry>
 227           </row>
 228           <row>
 229             <entry><screen>ss.str("Feb");
 230 ss >> m; // default format</screen></entry>
 231           </row>
 232
 233           <row>
 234             <entry valign="top" morerows="1"><screen>InItrT get(..., day_of_week)</screen></entry>
 235             <entry>Gets a day of week object from the stream using the format set by <code>weekday_format(...)</code> or the default.</entry>
 236           </row>
 237           <row>
 238             <entry><screen>ss.str("Sun");
 239 ss >> dow; // default format</screen></entry>
 240           </row>
 241
 242           <row>
 243             <entry valign="top" morerows="1"><screen>InItrT get(..., day)</screen></entry>
 244             <entry>Gets a day of month object from the stream as a two digit number.</entry>
 245           </row>
 246           <row>
 247             <entry><screen>"01" // January 1st</screen></entry>
 248           </row>
 249
 250           <row>
 251             <entry valign="top" morerows="1"><screen>InItrT get(..., year)</screen></entry>
 252             <entry>Gets a year object from the stream as a number. The number of expected digits depends on the year format.</entry>
 253           </row>
 254           <row>
 255             <entry><screen>ss/str("2005");
 256 ss >> y; // default format</screen></entry>
 257           </row>
 258
 259           <row>
 260             <entry valign="top" morerows="1"><screen>InItrT get(..., days)</screen></entry>
 261             <entry>Gets a days object from the stream as a number.</entry>
 262           </row>
 263           <row>
 264             <entry><screen>ss.str("356");
 265 ss >> dys; // a full year</screen></entry>
 266           </row>
 267
 268           <row>
 269             <entry valign="top" morerows="1"><screen>InItrT get(..., date_period)</screen></entry>
 270             <entry>Gets a date_period from the stream. The format of the dates will use the format set by <code>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.</entry>
 271           </row>
 272           <row>
 273             <entry>see the <link linkend="date_time.io_tutorial">tutorial</link> for a complete example.</entry>
 274           </row>
 275
 276           <row>
 277             <entry valign="top" morerows="1"><screen>InItrT get(..., partial_date)</screen></entry>
 278             <entry>Gets a partial_date date_generator object from the stream. The month format used is set by <code>month_format(..)</code> or the default. The day of month is represented as a two digit number.</entry>
 279           </row>
 280           <row>
 281             <entry><screen>"01 Jan" // default formats
 282 "01 January" // long month format</screen></entry>
 283           </row>
 284
 285           <row>
 286             <entry valign="top" morerows="1"><screen>InItrT get(..., date_generator)
 287   Date Generator Type:
 288     nth_day_of_the_week_in_month</screen></entry>
 289             <entry>Gets a nth_day_of_the_week_in_month object from the stream. The month format is set by <code>month_format(...)</code> or the default. The weekday format is set by <code>weekday_format(...)</code> or the default. The remaining phrase elements are set in the <link linkend ="io_objects.date_generators">date_generator_parser</link>.</entry>
 290           </row>
 291           <row>
 292             <entry><screen>"third Fri in May" // defaults</screen></entry>
 293           </row>
 294
 295           <row>
 296             <entry valign="top" morerows="1"><screen>InItrT get(..., date_generator)
 297   Date Generator Type:
 298     first_day_of_the_week_in_month</screen></entry>
 299             <entry>Gets a first_day_of_the_week_in_month object from the stream. The month format is set by <code>month_format(...)</code> or the default. The weekday format is set by <code>weekday_format(...)</code> or the default. The remaining phrase elements are set in the <link linkend ="io_objects.date_generators">date_generator_parser</link>.</entry>
 300           </row>
 301           <row>
 302             <entry><screen>"first Wed of Jun" // defaults</screen></entry>
 303           </row>
 304
 305           <row>
 306             <entry valign="top" morerows="1"><screen>InItrT get(..., date_generator)
 307   Date Generator Type:
 308     last_day_of_the_week_in_month</screen></entry>
 309             <entry>Gets a last_day_of_the_week_in_month object from the stream. The month format is set by <code>month_format(...)</code> or the default. The weekday format is set by <code>weekday_format(...)</code> or the default. The remaining phrase elements are set in the <link linkend ="io_objects.date_generators">date_generator_parser</link>.</entry>
 310           </row>
 311           <row>
 312             <entry><screen>"last Tue of Mar" // defaults</screen></entry>
 313           </row>
 314
 315           <row>
 316             <entry valign="top" morerows="1"><screen>InItrT get(..., date_generator)
 317   Date Generator Type:
 318     first_day_of_the_week_after</screen></entry>
 319             <entry>Gets a first_day_of_the_week_after object from the stream. The weekday format is set by <code>weekday_format(...)</code> or the default. The remaining phrase elements are set in the <link linkend ="io_objects.date_generators">date_generator_parser</link>.</entry>
 320           </row>
 321           <row>
 322             <entry><screen>"first Sat after" // defaults</screen></entry>
 323           </row>
 324
 325           <row>
 326             <entry valign="top" morerows="1"><screen>InItrT get(..., date_generator)
 327   Date Generator Type:
 328     first_day_of_the_week_before</screen></entry>
 329             <entry>Gets a first_day_of_the_week_before object from the stream. The weekday format is set by <code>weekday_format(...)</code> or the default. The remaining phrase elements are set in the <link linkend ="io_objects.date_generators">date_generator_parser</link>.</entry>
 330           </row>
 331           <row>
 332             <entry><screen>"first Mon before" // defaults</screen></entry>
 333           </row>
 334
 335         </tbody>
 336       </tgroup>
 337     </informaltable>
 338   </para>
 339
 340 </section>