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.format_flags"> 11 <title>Format Flags</title> 12 13 <para>Many of the format flags this new system uses for output are those used by <code>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).</para> 14 15 <para>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. 16 </para> 17 18 <para> 19 <anchor id="date_time_io.date_format_flags" /> 20 Date Facet Format Flags 21 <informaltable frame="all"> 22 <tgroup cols="2"> 23 <thead> 24 <row> 25 <entry valign="top" morerows="1">Format Specifier</entry> 26 <entry>Description</entry> 27 </row> 28 <row> 29 <entry>Example</entry> 30 </row> 31 </thead> 32 <tbody> 33 <row> 34 <entry valign="top" morerows="1"><screen>%a</screen></entry> 35 <entry>Abbreviated weekday name</entry> 36 </row> 37 <row> 38 <entry><screen>"Mon" => Monday</screen></entry> 39 </row> 40 41 <row> 42 <entry valign="top" morerows="1"><screen>%A</screen></entry> 43 <entry>Long weekday name</entry> 44 </row> 45 <row> 46 <entry><screen>"Monday"</screen></entry> 47 </row> 48 49 <row> 50 <entry valign="top" morerows="1"><screen>%b</screen></entry> 51 <entry>Abbreviated month name</entry> 52 </row> 53 <row> 54 <entry><screen>"Feb" => February</screen></entry> 55 </row> 56 57 <row> 58 <entry valign="top" morerows="1"><screen>%B</screen></entry> 59 <entry>Full month name</entry> 60 </row> 61 <row> 62 <entry><screen>"February"</screen></entry> 63 </row> 64 65 <row> 66 <entry valign="top" morerows="1"><screen>%c !</screen></entry> 67 <entry>The preferred date and time representation for the current locale.</entry> 68 </row> 69 <row> 70 <entry><screen></screen></entry> 71 </row> 72 73 <row> 74 <entry valign="top" morerows="1"><screen>%C !#</screen></entry> 75 <entry>The century number (year/100) as a 2-digit integer.</entry> 76 </row> 77 <row> 78 <entry><screen></screen></entry> 79 </row> 80 81 <row> 82 <entry valign="top" morerows="1"><screen>%d</screen></entry> 83 <entry> 84 Day of the month as decimal 01 to 31. When used to parse input, the leading zero is optional. 85 </entry> 86 </row> 87 <row> 88 <entry><screen></screen></entry> 89 </row> 90 91 <row> 92 <entry valign="top" morerows="1"><screen>%D !#</screen></entry> 93 <entry>Equivalent to %m/%d/%y</entry> 94 </row> 95 <row> 96 <entry><screen></screen></entry> 97 </row> 98 99 <row> 100 <entry valign="top" morerows="1"><screen>%e #</screen></entry> 101 <entry> 102 Like %d, the day of the month as a decimal number, but a leading zero is replaced by a space. 103 When used to parse input, the leading space is optional. 104 </entry> 105 </row> 106 <row> 107 <entry><screen></screen></entry> 108 </row> 109 110 <row> 111 <entry valign="top" morerows="1"><screen>%G !</screen></entry> 112 <entry>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.</entry> 113 </row> 114 <row> 115 <entry><screen></screen></entry> 116 </row> 117 118 <row> 119 <entry valign="top" morerows="1"><screen>%g !</screen></entry> 120 <entry>Like %G, but without century.</entry> 121 </row> 122 <row> 123 <entry><screen></screen></entry> 124 </row> 125 126 <row> 127 <entry valign="top" morerows="1"><screen>%h !#</screen></entry> 128 <entry> Equivalent to %b</entry> 129 </row> 130 <row> 131 <entry><screen></screen></entry> 132 </row> 133 134 <row> 135 <entry valign="top" morerows="1"><screen>%j</screen></entry> 136 <entry>Day of year as decimal from 001 to 366 for leap years, 001 - 365 for non-leap years.</entry> 137 </row> 138 <row> 139 <entry><screen>"060" => Feb-29</screen></entry> 140 </row> 141 142 <row> 143 <entry valign="top" morerows="1"><screen>%m</screen></entry> 144 <entry>Month name as a decimal 01 to 12</entry> 145 </row> 146 <row> 147 <entry><screen>"01" => January</screen></entry> 148 </row> 149 150 <row> 151 <entry valign="top" morerows="1"><screen>%u !</screen></entry> 152 <entry>The day of the week as a decimal, range 1 to 7, Monday being 1.</entry> 153 </row> 154 <row> 155 <entry><screen></screen></entry> 156 </row> 157 158 <row> 159 <entry valign="top" morerows="1"><screen>%U</screen></entry> 160 <entry>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).</entry> 161 </row> 162 <row> 163 <entry><screen>date d(2005, Jan, 1); // Saturday 164// with format %U 165ss << d; // "00" 166d += day(1); // Sunday 167ss << d; // "01" beginning of week 1</screen></entry> 168 </row> 169 170 <row> 171 <entry valign="top" morerows="1"><screen>%V !#</screen></entry> 172 <entry>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.</entry> 173 </row> 174 <row> 175 <entry><screen></screen></entry> 176 </row> 177 178 <row> 179 <entry valign="top" morerows="1"><screen>%w</screen></entry> 180 <entry>Weekday as decimal number 0 to 6</entry> 181 </row> 182 <row> 183 <entry><screen>"0" => Sunday</screen></entry> 184 </row> 185 186 <row> 187 <entry valign="top" morerows="1"><screen>%W</screen></entry> 188 <entry>Week number 00 to 53 where Monday is first day of week 1</entry> 189 </row> 190 <row> 191 <entry><screen>date d(2005, Jan, 2); // Sunday 192// with format %W 193ss << d; // "00" 194d += day(1); // Monday 195ss << d; // "01" beginning of week 1</screen></entry> 196 </row> 197 198 <row> 199 <entry valign="top" morerows="1"><screen>%x</screen></entry> 200 <entry>Implementation defined date format from the locale.</entry> 201 </row> 202 <row> 203 <entry><screen>date d(2005,Oct,31); 204date_facet* f = new date_facet("%x"); 205 206locale loc = locale(locale("en_US"), f); 207cout.imbue(loc); 208cout << d; // "10/31/2005" 209 210loc = locale(locale("de_DE"), f); 211cout.imbue(loc); 212cout << d; // "31.10.2005"</screen></entry> 213 </row> 214 215 <row> 216 <entry valign="top" morerows="1"><screen>%y</screen></entry> 217 <entry>Two digit year</entry> 218 </row> 219 <row> 220 <entry><screen>"05" => 2005</screen></entry> 221 </row> 222 223 <row> 224 <entry valign="top" morerows="1"><screen>%Y</screen></entry> 225 <entry>Four digit year</entry> 226 </row> 227 <row> 228 <entry><screen>"2005"</screen></entry> 229 </row> 230 231 <row> 232 <entry valign="top" morerows="1"><screen>%Y-%b-%d</screen></entry> 233 <entry>Default date format</entry> 234 </row> 235 <row> 236 <entry><screen>"2005-Apr-01"</screen></entry> 237 </row> 238 239 <row> 240 <entry valign="top" morerows="1"><screen>%Y%m%d</screen></entry> 241 <entry>ISO format</entry> 242 </row> 243 <row> 244 <entry><screen>"20050401"</screen></entry> 245 </row> 246 247 <row> 248 <entry valign="top" morerows="1"><screen>%Y-%m-%d</screen></entry> 249 <entry>ISO extended format</entry> 250 </row> 251 <row> 252 <entry><screen>"2005-04-01"</screen></entry> 253 </row> 254 255 </tbody> 256 </tgroup> 257 </informaltable> 258 259 260 <anchor id="date_time_io.time_format_flags" /> 261 Time Facet Format Flags 262 <informaltable frame="all"> 263 <tgroup cols="2"> 264 <thead> 265 <row> 266 <entry valign="top" morerows="1">Format Specifier</entry> 267 <entry>Description</entry> 268 </row> 269 <row> 270 <entry>Example</entry> 271 </row> 272 </thead> 273 <tbody> 274 <row> 275 <entry valign="top" morerows="1"><screen>%- *!</screen></entry> 276 <entry>Placeholder for the sign of a duration. Only displays when the duration is negative.</entry> 277 </row> 278 <row> 279 <entry><screen>"-13:15:16"</screen></entry> 280 </row> 281 282 <row> 283 <entry valign="top" morerows="1"><screen>%+ *!</screen></entry> 284 <entry>Placeholder for the sign of a duration. Always displays for both positive and negative.</entry> 285 </row> 286 <row> 287 <entry><screen>"+13:15:16"</screen></entry> 288 </row> 289 290 <row> 291 <entry valign="top" morerows="1"><screen>%f</screen></entry> 292 <entry>Fractional seconds are always used, even when their value is zero</entry> 293 </row> 294 <row> 295 <entry><screen>"13:15:16.000000"</screen></entry> 296 </row> 297 298 <row> 299 <entry valign="top" morerows="1"><screen>%F *</screen></entry> 300 <entry>Fractional seconds are used only when their value is not zero.</entry> 301 </row> 302 <row> 303 <entry><screen>"13:15:16" 304"05:04:03.001234"</screen></entry> 305 </row> 306 307 <row> 308 <entry valign="top" morerows="1"><screen>%H</screen></entry> 309 <entry>The hour as a decimal number using a 24-hour clock (range 00 to 23).</entry> 310 </row> 311 <row> 312 <entry></entry> 313 </row> 314 315 <row> 316 <entry valign="top" morerows="1"><screen>%I !</screen></entry> 317 <entry>The hour as a decimal number using a 12-hour clock (range 01 to 12).</entry> 318 </row> 319 <row> 320 <entry></entry> 321 </row> 322 323 <row> 324 <entry valign="top" morerows="1"><screen>%k !</screen></entry> 325 <entry>The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank.</entry> 326 </row> 327 <row> 328 <entry></entry> 329 </row> 330 331 <row> 332 <entry valign="top" morerows="1"><screen>%l !</screen></entry> 333 <entry>The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank.</entry> 334 </row> 335 <row> 336 <entry></entry> 337 </row> 338 339 <row> 340 <entry valign="top" morerows="1"><screen>%M</screen></entry> 341 <entry>The minute as a decimal number (range 00 to 59).</entry> 342 </row> 343 <row> 344 <entry></entry> 345 </row> 346 347 <row> 348 <entry valign="top" morerows="1"><screen>%O</screen></entry> 349 <entry>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.</entry> 350 </row> 351 <row> 352 <entry></entry> 353 </row> 354 355 <row> 356 <entry valign="top" morerows="1"><screen>%p !</screen></entry> 357 <entry>Either `AM' or `PM' according to the given time value, or the corresponding strings for the current locale.</entry> 358 </row> 359 <row> 360 <entry></entry> 361 </row> 362 363 <row> 364 <entry valign="top" morerows="1"><screen>%P !#</screen></entry> 365 <entry>Like %p but in lowercase: `am' or `pm' or a corresponding string for the current locale.</entry> 366 </row> 367 <row> 368 <entry></entry> 369 </row> 370 371 <row> 372 <entry valign="top" morerows="1"><screen>%r !#</screen></entry> 373 <entry>The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to `%I:%M:%S %p'</entry> 374 </row> 375 <row> 376 <entry></entry> 377 </row> 378 379 <row> 380 <entry valign="top" morerows="1"><screen>%R !</screen></entry> 381 <entry>The time in 24-hour notation (%H:%M)</entry> 382 </row> 383 <row> 384 <entry></entry> 385 </row> 386 387 <row> 388 <entry valign="top" morerows="1"><screen>%s *</screen></entry> 389 <entry>Seconds with fractional seconds.</entry> 390 </row> 391 <row> 392 <entry><screen>"59.000000"</screen></entry> 393 </row> 394 395 <row> 396 <entry valign="top" morerows="1"><screen>%S</screen></entry> 397 <entry>Seconds only</entry> 398 </row> 399 <row> 400 <entry><screen>"59"</screen></entry> 401 </row> 402 403 <row> 404 <entry valign="top" morerows="1"><screen>%T !</screen></entry> 405 <entry>The time in 24-hour notation (%H:%M:%S)</entry> 406 </row> 407 <row> 408 <entry></entry> 409 </row> 410 411 <row> 412 <entry valign="top" morerows="1"><screen>%q</screen></entry> 413 <entry>ISO time zone (output only). This flag is ignored when using the time_facet with a ptime.</entry> 414 </row> 415 <row> 416 <entry><screen>"-0700" // Mountain Standard Time</screen></entry> 417 </row> 418 419 <row> 420 <entry valign="top" morerows="1"><screen>%Q</screen></entry> 421 <entry>ISO extended time zone (output only). This flag is ignored when using the time_facet with a ptime.</entry> 422 </row> 423 <row> 424 <entry><screen>"-05:00" // Eastern Standard Time</screen></entry> 425 </row> 426 427 <row> 428 <entry valign="top" morerows="1"><screen>%z *!</screen></entry> 429 <entry>Abbreviated time zone (output only). This flag is ignored when using the time_facet with a ptime.</entry> 430 </row> 431 <row> 432 <entry><screen>"MST" // Mountain Standard Time</screen></entry> 433 </row> 434 435 <row> 436 <entry valign="top" morerows="1"><screen>%Z *!</screen></entry> 437 <entry>Full time zone name (output only). This flag is ignored when using the time_facet with a ptime.</entry> 438 </row> 439 <row> 440 <entry><screen>"EDT" // Eastern Daylight Time</screen></entry> 441 </row> 442 443 <row> 444 <entry valign="top" morerows="1"><screen>%ZP *</screen></entry> 445 <entry>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 <link linkend="date_time.local_time.posix_time_zone">posix_time_zone class</link>.</entry> 446 </row> 447 <row> 448 <entry><screen>"EST-05EDT+01,M4.1.0/02:00,M10.5.0/02:00"</screen></entry> 449 </row> 450 451 <row> 452 <entry valign="top" morerows="1"><screen>%x %X</screen></entry> 453 <entry>Implementation defined date/time format from the locale.</entry> 454 </row> 455 <row> 456 <entry><screen>date d(2005,Oct,31); 457ptime pt(d, hours(20)); 458time_facet* f = new time_facet("%x %X"); 459 460locale loc = locale(locale("en_US"), f); 461cout.imbue(loc); 462cout << pt; // "10/31/2005 08:00:00 PM" 463 464loc = locale(locale("de_DE"), f); 465cout.imbue(loc); 466cout << pt; // "31.10.2005 20:00:00"</screen></entry> 467 </row> 468 469 <row> 470 <entry valign="top" morerows="1"><screen>%Y%m%dT%H%M%S%F%q</screen></entry> 471 <entry>ISO format</entry> 472 </row> 473 <row> 474 <entry><screen>"20051015T131211-0700" // Oct 15, 2005 13:12:11 MST</screen></entry> 475 </row> 476 477 <row> 478 <entry valign="top" morerows="1"><screen>%Y-%m-%d %H:%M:%S%F%Q</screen></entry> 479 <entry>Extended ISO format</entry> 480 </row> 481 <row> 482 <entry><screen>"2005-10-15 13:12:11-07:00"</screen></entry> 483 </row> 484 485 <row> 486 <entry valign="top" morerows="1"><screen>%Y-%b-%d %H:%M:%S%F %z</screen></entry> 487 <entry>Default format used when outputting ptime and local_date_time.</entry> 488 </row> 489 <row> 490 <entry><screen>"2005-Oct-15 13:12:11 MST"</screen></entry> 491 </row> 492 493 <row> 494 <entry valign="top" morerows="1"><screen>%Y-%b-%d %H:%M:%S%F %ZP</screen></entry> 495 <entry>Default format used when inputting ptime and local_date_time.</entry> 496 </row> 497 <row> 498 <entry><screen>"2005-Oct-15 13:12:11 MST-07"</screen></entry> 499 </row> 500 501 <row> 502 <entry valign="top" morerows="1"><screen>%-%H:%M:%S%F !</screen></entry> 503 <entry>Default time_duration format for output. Sign will only be displayed for negative durations.</entry> 504 </row> 505 <row> 506 <entry><screen>"-13:14:15.003400"</screen></entry> 507 </row> 508 509 <row> 510 <entry valign="top" morerows="1"><screen>%H:%M:%S%F</screen></entry> 511 <entry>Default time_duration format for input.</entry> 512 </row> 513 <row> 514 <entry><screen>"13:14:15.003400"</screen></entry> 515 </row> 516 517 </tbody> 518 </tgroup> 519 </informaltable> 520 </para> 521 <para>* Signifies flags that have a behavior unique to <code>date_time</code>.</para> 522 <para># Signifies flags that have a platform-dependent behavior. These may not be supported everywhere.</para> 523 <para>! Signifies flags that currently do not work for input.</para> 524</section> 525