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_facet"> 11 <title>Date Facet</title> 12 13 <link linkend="date_facet_intro">Introduction</link> - 14 <link linkend="date_facet_constr">Construction</link> - 15 <link linkend="date_facet_accessors">Accessors</link> 16 17 <anchor id="date_facet_intro" /> 18 <bridgehead renderas="sect3">Introduction</bridgehead> 19 <para>The <code>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>gregorian</code> namespace as <code>date_facet</code> and <code>wdate_facet</code>. 20 </para> 21 22 <anchor id="date_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_facet()</screen></entry> 36 <entry>Default constructor</entry> 37 </row> 38 <row> 39 <entry valign="top"><screen>date_facet(...) 40 Parameters: 41 char_type* format 42 input_collection_type</screen></entry> 43 <entry>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.</entry> 44 </row> 45 <row> 46 <entry valign="top"><screen>date_facet(...) 47 Parameters: 48 char_type* format 49 period_formatter_type 50 special_values_formatter_type 51 date_gen_formatter_type</screen></entry> 52 <entry>Format given will be used for date output. The remaining parameters are formatter objects. Further details on these objects can be found <link linkend="date_time.io_objects">here</link>. This constructor also provides default arguments for all parameters except the format. Therefore, <code>date_facet("%m %d %Y")</code> will work.</entry> 53 </row> 54 </tbody> 55 </tgroup> 56 </informaltable> 57 </para> 58 59 <anchor id="date_facet_accessors" /> 60 <bridgehead renderas="sect3">Accessors</bridgehead> 61 <para> 62 <informaltable frame="all"> 63 <tgroup cols="2"> 64 <thead> 65 <row> 66 <entry valign="top" morerows="1">Syntax</entry> 67 <entry>Description</entry> 68 </row> 69 <row> 70 <entry>Example</entry> 71 </row> 72 </thead> 73 <tbody> 74 <row> 75 <entry valign="top" morerows="1"><screen>void format(char_type*)</screen></entry> 76 <entry>Set the format for dates.</entry> 77 </row> 78 <row> 79 <entry><screen>date_facet* f = new date_facet(); 80f->format("%m %d %Y");</screen></entry> 81 </row> 82 83 <row> 84 <entry valign="top" morerows="1"><screen>void set_iso_format()</screen></entry> 85 <entry>Sets the date format to ISO</entry> 86 </row> 87 <row> 88 <entry><screen>f->set_iso_format(); 89// "%Y%m%d"</screen></entry> 90 </row> 91 92 <row> 93 <entry valign="top" morerows="1"><screen>void set_iso_extended_format()</screen></entry> 94 <entry>Sets the date format to ISO Extended</entry> 95 </row> 96 <row> 97 <entry><screen>f->set_iso_extended_format(); 98// "%Y-%m-%d"</screen></entry> 99 </row> 100 101 <row> 102 <entry valign="top" morerows="1"><screen>void month_format(char_type*)</screen></entry> 103 <entry>Set the format for months when they are 'put' individually.</entry> 104 </row> 105 <row> 106 <entry><screen>f->month_format("%B"); 107ss << greg_month(12); // "December"</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 for weekdays when they are 'put' individually.</entry> 113 </row> 114 <row> 115 <entry><screen>f->weekday_format("%a"); 116ss << greg_weekday(2); // "Tue"</screen></entry> 117 </row> 118 119 <row> 120 <entry valign="top" morerows="1"><screen>void period_formatter(...) 121 Parameter: 122 period_formatter_type</screen></entry> 123 <entry>Replaces the period formatter object with a user created one.</entry> 124 </row> 125 <row> 126 <entry>see the <link linkend="date_time.io_tutorial">tutorial</link> for a complete example.</entry> 127 </row> 128 129 <row> 130 <entry valign="top" morerows="1"><screen>void special_values_formatter(...) 131 Parameter: 132 special_values_formatter_type</screen></entry> 133 <entry>Replaces the special_values formatter object with a user created one.</entry> 134 </row> 135 <row> 136 <entry>see the <link linkend="date_time.io_tutorial">tutorial</link> for a complete example.</entry> 137 </row> 138 139 <row> 140 <entry valign="top" morerows="1"><screen>void date_gen_phrase_strings(...) 141 Parameters: 142 input_collection_type 143 date_gen_formatter_type:: 144 phrase_elements</screen></entry> 145 <entry>Sets new date generator phrase strings in date_gen_formatter. 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>). 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.</entry> 146 </row> 147 <row> 148 <entry><screen></screen></entry> 149 </row> 150 151 <row> 152 <entry valign="top" morerows="1"><screen>void short_weekday_names(...) 153 Parameter: 154 input_collection_type</screen></entry> 155 <entry>Replace strings used when 'putting' short weekdays.</entry> 156 </row> 157 <row> 158 <entry>see the <link linkend="date_time.io_tutorial">tutorial</link> for a complete example.</entry> 159 </row> 160 161 <row> 162 <entry valign="top" morerows="1"><screen>void long_weekday_names(...) 163 Parameter: 164 input_collection_type</screen></entry> 165 <entry>Replace strings used when 'putting' long weekdays.</entry> 166 </row> 167 <row> 168 <entry>see the <link linkend="date_time.io_tutorial">tutorial</link> for a complete example.</entry> 169 </row> 170 171 <row> 172 <entry valign="top" morerows="1"><screen>void short_month_names(...) 173 Parameter: 174 input_collection_type</screen></entry> 175 <entry>Replace strings used when 'putting' short months.</entry> 176 </row> 177 <row> 178 <entry>see the <link linkend="date_time.io_tutorial">tutorial</link> for a complete example.</entry> 179 </row> 180 181 <row> 182 <entry valign="top" morerows="1"><screen>void long_month_names(...) 183 Parameter: 184 input_collection_type</screen></entry> 185 <entry>Replace strings used when 'putting' long months.</entry> 186 </row> 187 <row> 188 <entry>see the <link linkend="date_time.io_tutorial">tutorial</link> for a complete example.</entry> 189 </row> 190 191 <row> 192 <entry valign="top" morerows="1"><screen>OutItrT put(...) 193 Common parameters for all 194 'put' functions: 195 OutItrT 196 ios_base 197 char_type 198 Unique parameter for 'put' funcs: 199 gregorian object</screen></entry> 200 <entry>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.</entry> 201 </row> 202 <row> 203 <entry><screen></screen></entry> 204 </row> 205 206 <row> 207 <entry valign="top" morerows="1"><screen>OutItrT put(..., date)</screen></entry> 208 <entry>Puts a date object into the stream using the format set by <code>format(...)</code> or the default.</entry> 209 </row> 210 <row> 211 <entry><screen></screen></entry> 212 </row> 213 214 <row> 215 <entry valign="top" morerows="1"><screen>OutItrT put(..., days)</screen></entry> 216 <entry>Puts a days object into the stream as a number.</entry> 217 </row> 218 <row> 219 <entry><screen></screen></entry> 220 </row> 221 222 <row> 223 <entry valign="top" morerows="1"><screen>OutItrT put(..., month)</screen></entry> 224 <entry>Puts a month object into the stream using the format set by <code>month_format(...)</code> or the default.</entry> 225 </row> 226 <row> 227 <entry><screen></screen></entry> 228 </row> 229 230 <row> 231 <entry valign="top" morerows="1"><screen>OutItrT put(..., day)</screen></entry> 232 <entry>Puts a day of month object into the stream as a two digit number.</entry> 233 </row> 234 <row> 235 <entry><screen>"01" // January 1st</screen></entry> 236 </row> 237 238 <row> 239 <entry valign="top" morerows="1"><screen>OutItrT put(..., day_of_week)</screen></entry> 240 <entry>Puts a day of week object into the stream using the format set by <code>weekday_format(...)</code> or the default.</entry> 241 </row> 242 <row> 243 <entry><screen></screen></entry> 244 </row> 245 246 <row> 247 <entry valign="top" morerows="1"><screen>OutItrT put(..., date_period)</screen></entry> 248 <entry>Puts a date_period into 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_formatter.</entry> 249 </row> 250 <row> 251 <entry><screen></screen></entry> 252 </row> 253 254 <row> 255 <entry valign="top" morerows="1"><screen>OutItrT put(..., partial_date)</screen></entry> 256 <entry>Puts a partial_date date_generator object into 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> 257 </row> 258 <row> 259 <entry><screen>"01 Jan" // default formats 260"01 January" // long month format</screen></entry> 261 </row> 262 263 <row> 264 <entry valign="top" morerows="1"><screen>OutItrT put(..., date_generator) 265 Date Generator Type: 266 nth_day_of_the_week_in_month</screen></entry> 267 <entry>Puts a nth_day_of_the_week_in_month object into 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_formatter</link>.</entry> 268 </row> 269 <row> 270 <entry><screen>"third Fri in May" // defaults</screen></entry> 271 </row> 272 273 <row> 274 <entry valign="top" morerows="1"><screen>OutItrT put(..., date_generator) 275 Date Generator Type: 276 first_day_of_the_week_in_month</screen></entry> 277 <entry>Puts a first_day_of_the_week_in_month object into 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_formatter</link>.</entry> 278 </row> 279 <row> 280 <entry><screen>"first Wed of Jun" // defaults</screen></entry> 281 </row> 282 283 <row> 284 <entry valign="top" morerows="1"><screen>OutItrT put(..., date_generator) 285 Date Generator Type: 286 last_day_of_the_week_in_month</screen></entry> 287 <entry>Puts a last_day_of_the_week_in_month object into 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_formatter</link>.</entry> 288 </row> 289 <row> 290 <entry><screen>"last Tue of Mar" // defaults</screen></entry> 291 </row> 292 293 <row> 294 <entry valign="top" morerows="1"><screen>OutItrT put(..., date_generator) 295 Date Generator Type: 296 first_day_of_the_week_after</screen></entry> 297 <entry>Puts a first_day_of_the_week_after object into 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_formatter</link>.</entry> 298 </row> 299 <row> 300 <entry><screen>"first Sat after" // defaults</screen></entry> 301 </row> 302 303 <row> 304 <entry valign="top" morerows="1"><screen>OutItrT put(..., date_generator) 305 Date Generator Type: 306 first_day_of_the_week_before</screen></entry> 307 <entry>Puts a first_day_of_the_week_before object into 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_formatter</link>.</entry> 308 </row> 309 <row> 310 <entry><screen>"first Mon before" // defaults</screen></entry> 311 </row> 312 313 </tbody> 314 </tgroup> 315 </informaltable> 316 </para> 317</section> 318 319 320