ceph/src/boost/libs/date_time/xmldoc/format_flags.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.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
 165 ss &lt;&lt; d; // "00"
 166 d += day(1); // Sunday
 167 ss &lt;&lt; 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
 193 ss &lt;&lt; d; // "00"
 194 d += day(1); // Monday
 195 ss &lt;&lt; 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);
 204 date_facet* f = new date_facet("%x");
 205
 206 locale loc = locale(locale("en_US"), f);
 207 cout.imbue(loc);
 208 cout &lt;&lt; d; // "10/31/2005"
 209
 210 loc = locale(locale("de_DE"), f);
 211 cout.imbue(loc);
 212 cout &lt;&lt; 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);
 457 ptime pt(d, hours(20));
 458 time_facet* f = new time_facet("%x %X");
 459
 460 locale loc = locale(locale("en_US"), f);
 461 cout.imbue(loc);
 462 cout &lt;&lt; pt; // "10/31/2005 08:00:00 PM"
 463
 464 loc = locale(locale("de_DE"), f);
 465 cout.imbue(loc);
 466 cout &lt;&lt; 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>