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(); 79f->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"); 106ss.str("March"); 107ss >> 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"); 116ss.str("Sun"); 117ss >> 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"); 126ss.str("04"); 127ss >> 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"); 221ss >> 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"); 230ss >> 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"); 239ss >> 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"); 256ss >> 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"); 265ss >> 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> 341