js/strftime.js

   1 /*
   2  strftime for Javascript
   3  Copyright (c) 2008, Philip S Tellis <philip@bluesmoon.info>
   4  All rights reserved.
   5
   6  This code is distributed under the terms of the BSD licence
   7
   8  Redistribution and use of this software in source and binary forms, with or without modification,
   9  are permitted provided that the following conditions are met:
  10
  11    * Redistributions of source code must retain the above copyright notice, this list of conditions
  12      and the following disclaimer.
  13    * Redistributions in binary form must reproduce the above copyright notice, this list of
  14      conditions and the following disclaimer in the documentation and/or other materials provided
  15      with the distribution.
  16    * The names of the contributors to this file may not be used to endorse or promote products
  17      derived from this software without specific prior written permission.
  18
  19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
  20 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  21 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
  22 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  23 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
  25 TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  26 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27  */
  28
  29 /**
  30  * \file strftime.js
  31  * \author Philip S Tellis \<philip@bluesmoon.info\>
  32  * \version 1.3
  33  * \date 2008/06
  34  * \brief Javascript implementation of strftime
  35  *
  36  * Implements strftime for the Date object in javascript based on the PHP implementation described at
  37  * http://www.php.net/strftime  This is in turn based on the Open Group specification defined
  38  * at http://www.opengroup.org/onlinepubs/007908799/xsh/strftime.html This implementation does not
  39  * include modified conversion specifiers (i.e., Ex and Ox)
  40  *
  41  * The following format specifiers are supported:
  42  *
  43  * \copydoc formats
  44  *
  45  * \%a, \%A, \%b and \%B should be localised for non-English locales.
  46  *
  47  * \par Usage:
  48  * This library may be used as follows:
  49  * \code
  50  *     var d = new Date();
  51  *
  52  *     var ymd = d.strftime('%Y/%m/%d');
  53  *     var iso = d.strftime('%Y-%m-%dT%H:%M:%S%z');
  54  *
  55  * \endcode
  56  *
  57  * \sa \link Date.prototype.strftime Date.strftime \endlink for a description of each of the supported format specifiers
  58  * \sa Date.ext.locales for localisation information
  59  * \sa http://www.php.net/strftime for the PHP implementation which is the basis for this
  60  * \sa http://tech.bluesmoon.info/2008/04/strftime-in-javascript.html for feedback
  61  */
  62
  63 //! Date extension object - all supporting objects go in here.
  64 Date.ext = {};
  65
  66 //! Utility methods
  67 Date.ext.util = {};
  68
  69 /**
  70 \brief Left pad a number with something
  71 \details Takes a number and pads it to the left with the passed in pad character
  72 \param x        The number to pad
  73 \param pad      The string to pad with
  74 \param r        [optional] Upper limit for pad.  A value of 10 pads to 2 digits, a value of 100 pads to 3 digits.
  75                 Default is 10.
  76
  77 \return The number left padded with the pad character.  This function returns a string and not a number.
  78 */
  79 Date.ext.util.xPad=function(x, pad, r)
  80 {
  81         if(typeof(r) == 'undefined')
  82         {
  83                 r=10;
  84         }
  85         for( ; parseInt(x, 10)<r && r>1; r/=10)
  86                 x = pad.toString() + x;
  87         return x.toString();
  88 };
  89
  90 /**
  91 \brief Currently selected locale.
  92 \details
  93 The locale for a specific date object may be changed using \code Date.locale = "new-locale"; \endcode
  94 The default will be based on the lang attribute of the HTML tag of your document
  95 */
  96 Date.prototype.locale = 'en-GB';
  97 //! \cond FALSE
  98 if(document.getElementsByTagName('html') && document.getElementsByTagName('html')[0].lang)
  99 {
 100         Date.prototype.locale = document.getElementsByTagName('html')[0].lang;
 101 }
 102 //! \endcond
 103
 104 /**
 105 \brief Localised strings for days of the week and months of the year.
 106 \details
 107 To create your own local strings, add a locale object to the locales object.
 108 The key of your object should be the same as your locale name.  For example:
 109    en-US,
 110    fr,
 111    fr-CH,
 112    de-DE
 113 Names are case sensitive and are described at http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
 114 Your locale object must contain the following keys:
 115 \param a        Short names of days of week starting with Sunday
 116 \param A        Long names days of week starting with Sunday
 117 \param b        Short names of months of the year starting with January
 118 \param B        Long names of months of the year starting with February
 119 \param c        The preferred date and time representation in your locale
 120 \param p        AM or PM in your locale
 121 \param P        am or pm in your locale
 122 \param x        The  preferred date representation for the current locale without the time.
 123 \param X        The preferred time representation for the current locale without the date.
 124
 125 \sa Date.ext.locales.en for a sample implementation
 126 \sa \ref localisation for detailed documentation on localising strftime for your own locale
 127 */
 128 Date.ext.locales = { };
 129
 130 /**
 131  * \brief Localised strings for English (British).
 132  * \details
 133  * This will be used for any of the English dialects unless overridden by a country specific one.
 134  * This is the default locale if none specified
 135  */
 136 Date.ext.locales.en = {
 137         a: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
 138         A: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
 139         b: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
 140         B: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
 141         c: '%a %d %b %Y %T %Z',
 142         p: ['AM', 'PM'],
 143         P: ['am', 'pm'],
 144         x: '%d/%m/%y',
 145         X: '%T'
 146 };
 147
 148 //! \cond FALSE
 149 // Localised strings for US English
 150 Date.ext.locales['en-US'] = Date.ext.locales.en;
 151 Date.ext.locales['en-US'].c = '%a %d %b %Y %r %Z';
 152 Date.ext.locales['en-US'].x = '%D';
 153 Date.ext.locales['en-US'].X = '%r';
 154
 155 // Localised strings for British English
 156 Date.ext.locales['en-GB'] = Date.ext.locales.en;
 157
 158 // Localised strings for Australian English
 159 Date.ext.locales['en-AU'] = Date.ext.locales['en-GB'];
 160 //! \endcond
 161
 162 //! \brief List of supported format specifiers.
 163 /**
 164  * \details
 165  * \arg \%a - abbreviated weekday name according to the current locale
 166  * \arg \%A - full weekday name according to the current locale
 167  * \arg \%b - abbreviated month name according to the current locale
 168  * \arg \%B - full month name according to the current locale
 169  * \arg \%c - preferred date and time representation for the current locale
 170  * \arg \%C - century number (the year divided by 100 and truncated to an integer, range 00 to 99)
 171  * \arg \%d - day of the month as a decimal number (range 01 to 31)
 172  * \arg \%D - same as %m/%d/%y
 173  * \arg \%e - day of the month as a decimal number, a single digit is preceded by a space (range ' 1' to '31')
 174  * \arg \%g - like %G, but without the century
 175  * \arg \%G - The 4-digit year corresponding to the ISO week number
 176  * \arg \%h - same as %b
 177  * \arg \%H - hour as a decimal number using a 24-hour clock (range 00 to 23)
 178  * \arg \%I - hour as a decimal number using a 12-hour clock (range 01 to 12)
 179  * \arg \%j - day of the year as a decimal number (range 001 to 366)
 180  * \arg \%m - month as a decimal number (range 01 to 12)
 181  * \arg \%M - minute as a decimal number
 182  * \arg \%n - newline character
 183  * \arg \%p - either `AM' or `PM' according to the given time value, or the corresponding strings for the current locale
 184  * \arg \%P - like %p, but lower case
 185  * \arg \%r - time in a.m. and p.m. notation equal to %I:%M:%S %p
 186  * \arg \%R - time in 24 hour notation equal to %H:%M
 187  * \arg \%S - second as a decimal number
 188  * \arg \%t - tab character
 189  * \arg \%T - current time, equal to %H:%M:%S
 190  * \arg \%u - weekday as a decimal number [1,7], with 1 representing Monday
 191  * \arg \%U - week number of the current year as a decimal number, starting with
 192  *            the first Sunday as the first day of the first week
 193  * \arg \%V - The ISO 8601:1988 week number of the current year as a decimal number,
 194  *            range 01 to 53, where week 1 is the first week that has at least 4 days
 195  *            in the current year, and with Monday as the first day of the week.
 196  * \arg \%w - day of the week as a decimal, Sunday being 0
 197  * \arg \%W - week number of the current year as a decimal number, starting with the
 198  *            first Monday as the first day of the first week
 199  * \arg \%x - preferred date representation for the current locale without the time
 200  * \arg \%X - preferred time representation for the current locale without the date
 201  * \arg \%y - year as a decimal number without a century (range 00 to 99)
 202  * \arg \%Y - year as a decimal number including the century
 203  * \arg \%z - numerical time zone representation
 204  * \arg \%Z - time zone name or abbreviation
 205  * \arg \%% - a literal `\%' character
 206  */
 207 Date.ext.formats = {
 208         a: function(d) { return Date.ext.locales[d.locale].a[d.getDay()]; },
 209         A: function(d) { return Date.ext.locales[d.locale].A[d.getDay()]; },
 210         b: function(d) { return Date.ext.locales[d.locale].b[d.getMonth()]; },
 211         B: function(d) { return Date.ext.locales[d.locale].B[d.getMonth()]; },
 212         c: 'toLocaleString',
 213         C: function(d) { return Date.ext.util.xPad(parseInt(d.getFullYear()/100, 10), 0); },
 214         d: ['getDate', '0'],
 215         e: ['getDate', ' '],
 216         g: function(d) { return Date.ext.util.xPad(parseInt(Date.ext.util.G(d)/100, 10), 0); },
 217         G: function(d) {
 218                         var y = d.getFullYear();
 219                         var V = parseInt(Date.ext.formats.V(d), 10);
 220                         var W = parseInt(Date.ext.formats.W(d), 10);
 221
 222                         if(W > V) {
 223                                 y++;
 224                         } else if(W===0 && V>=52) {
 225                                 y--;
 226                         }
 227
 228                         return y;
 229                 },
 230         H: ['getHours', '0'],
 231         I: function(d) { var I=d.getHours()%12; return Date.ext.util.xPad(I===0?12:I, 0); },
 232         j: function(d) {
 233                         var ms = d - new Date('' + d.getFullYear() + '/1/1 GMT');
 234                         ms += d.getTimezoneOffset()*60000;
 235                         var doy = parseInt(ms/60000/60/24, 10)+1;
 236                         return Date.ext.util.xPad(doy, 0, 100);
 237                 },
 238         m: function(d) { return Date.ext.util.xPad(d.getMonth()+1, 0); },
 239         M: ['getMinutes', '0'],
 240         p: function(d) { return Date.ext.locales[d.locale].p[d.getHours() >= 12 ? 1 : 0 ]; },
 241         P: function(d) { return Date.ext.locales[d.locale].P[d.getHours() >= 12 ? 1 : 0 ]; },
 242         S: ['getSeconds', '0'],
 243         u: function(d) { var dow = d.getDay(); return dow===0?7:dow; },
 244         U: function(d) {
 245                         var doy = parseInt(Date.ext.formats.j(d), 10);
 246                         var rdow = 6-d.getDay();
 247                         var woy = parseInt((doy+rdow)/7, 10);
 248                         return Date.ext.util.xPad(woy, 0);
 249                 },
 250         V: function(d) {
 251                         var woy = parseInt(Date.ext.formats.W(d), 10);
 252                         var dow1_1 = (new Date('' + d.getFullYear() + '/1/1')).getDay();
 253                         // First week is 01 and not 00 as in the case of %U and %W,
 254                         // so we add 1 to the final result except if day 1 of the year
 255                         // is a Monday (then %W returns 01).
 256                         // We also need to subtract 1 if the day 1 of the year is
 257                         // Friday-Sunday, so the resulting equation becomes:
 258                         var idow = woy + (dow1_1 > 4 || dow1_1 <= 1 ? 0 : 1);
 259                         if(idow == 53 && (new Date('' + d.getFullYear() + '/12/31')).getDay() < 4)
 260                         {
 261                                 idow = 1;
 262                         }
 263                         else if(idow === 0)
 264                         {
 265                                 idow = Date.ext.formats.V(new Date('' + (d.getFullYear()-1) + '/12/31'));
 266                         }
 267
 268                         return Date.ext.util.xPad(idow, 0);
 269                 },
 270         w: 'getDay',
 271         W: function(d) {
 272                         var doy = parseInt(Date.ext.formats.j(d), 10);
 273                         var rdow = 7-Date.ext.formats.u(d);
 274                         var woy = parseInt((doy+rdow)/7, 10);
 275                         return Date.ext.util.xPad(woy, 0, 10);
 276                 },
 277         y: function(d) { return Date.ext.util.xPad(d.getFullYear()%100, 0); },
 278         Y: 'getFullYear',
 279         z: function(d) {
 280                         var o = d.getTimezoneOffset();
 281                         var H = Date.ext.util.xPad(parseInt(Math.abs(o/60), 10), 0);
 282                         var M = Date.ext.util.xPad(o%60, 0);
 283                         return (o>0?'-':'+') + H + M;
 284                 },
 285         Z:
 286           // does not work reliably (for example on Windows with CP1251), using numeric representations
 287           //function(d) { return d.toString().replace(/^.*\(([^)]+)\)$/, '$1'); },
 288         function(d) {
 289       var o = d.getTimezoneOffset();
 290       var H = Date.ext.util.xPad(parseInt(Math.abs(o/60), 10), 0);
 291       var M = Date.ext.util.xPad(o%60, 0);
 292       return (o>0?'-':'+') + H + M;
 293     },
 294         '%': function(d) { return '%'; }
 295 };
 296
 297 /**
 298 \brief List of aggregate format specifiers.
 299 \details
 300 Aggregate format specifiers map to a combination of basic format specifiers.
 301 These are implemented in terms of Date.ext.formats.
 302
 303 A format specifier that maps to 'locale' is read from Date.ext.locales[current-locale].
 304
 305 \sa Date.ext.formats
 306 */
 307 Date.ext.aggregates = {
 308         c: 'locale',
 309         D: '%m/%d/%y',
 310         h: '%b',
 311         n: '\n',
 312         r: '%I:%M:%S %p',
 313         R: '%H:%M',
 314         t: '\t',
 315         T: '%H:%M:%S',
 316         x: 'locale',
 317         X: 'locale'
 318 };
 319
 320 //! \cond FALSE
 321 // Cache timezone values because they will never change for a given JS instance
 322 Date.ext.aggregates.z = Date.ext.formats.z(new Date());
 323 Date.ext.aggregates.Z = Date.ext.formats.Z(new Date());
 324 //! \endcond
 325
 326 //! List of unsupported format specifiers.
 327 /**
 328  * \details
 329  * All format specifiers supported by the PHP implementation are supported by
 330  * this javascript implementation.
 331  */
 332 Date.ext.unsupported = { };
 333
 334
 335 /**
 336  * \brief Formats the date according to the specified format.
 337  * \param fmt   The format to format the date in.  This may be a combination of the following:
 338  * \copydoc formats
 339  *
 340  * \return      A string representation of the date formatted based on the passed in parameter
 341  * \sa http://www.php.net/strftime for documentation on format specifiers
 342 */
 343 Date.prototype.strftime=function(fmt)
 344 {
 345         // Fix locale if declared locale hasn't been defined
 346         // After the first call this condition should never be entered unless someone changes the locale
 347         if(!(this.locale in Date.ext.locales))
 348         {
 349                 if(this.locale.replace(/-[a-zA-Z]+$/, '') in Date.ext.locales)
 350                 {
 351                         this.locale = this.locale.replace(/-[a-zA-Z]+$/, '');
 352                 }
 353                 else
 354                 {
 355                         this.locale = 'en-GB';
 356                 }
 357         }
 358
 359         var d = this;
 360         // First replace aggregates
 361         while(fmt.match(/%[cDhnrRtTxXzZ]/))
 362         {
 363                 fmt = fmt.replace(/%([cDhnrRtTxXzZ])/g, function(m0, m1)
 364                                 {
 365                                         var f = Date.ext.aggregates[m1];
 366                                         return (f == 'locale' ? Date.ext.locales[d.locale][m1] : f);
 367                                 });
 368         }
 369
 370
 371         // Now replace formats - we need a closure so that the date object gets passed through
 372         var str = fmt.replace(/%([aAbBCdegGHIjmMpPSuUVwWyY%])/g, function(m0, m1)
 373                         {
 374                                 var f = Date.ext.formats[m1];
 375                                 if(typeof(f) == 'string') {
 376                                         return d[f]();
 377                                 } else if(typeof(f) == 'function') {
 378                                         return f.call(d, d);
 379                                 } else if(typeof(f) == 'object' && typeof(f[0]) == 'string') {
 380                                         return Date.ext.util.xPad(d[f[0]](), f[1]);
 381                                 } else {
 382                                         return m1;
 383                                 }
 384                         });
 385         d=null;
 386         return str;
 387 };
 388
 389 /**
 390  * \mainpage strftime for Javascript
 391  *
 392  * \section toc Table of Contents
 393  * - \ref intro_sec
 394  * - <a class="el" href="strftime.js">Download full source</a> / <a class="el" href="strftime-min.js">minified</a>
 395  * - \subpage usage
 396  * - \subpage format_specifiers
 397  * - \subpage localisation
 398  * - \link strftime.js API Documentation \endlink
 399  * - \subpage demo
 400  * - \subpage changelog
 401  * - \subpage faq
 402  * - <a class="el" href="http://tech.bluesmoon.info/2008/04/strftime-in-javascript.html">Feedback</a>
 403  * - \subpage copyright_licence
 404  *
 405  * \section intro_sec Introduction
 406  *
 407  * C and PHP developers have had access to a built in strftime function for a long time.
 408  * This function is an easy way to format dates and times for various display needs.
 409  *
 410  * This library brings the flexibility of strftime to the javascript Date object
 411  *
 412  * Use this library if you frequently need to format dates in javascript in a variety of ways.  For example,
 413  * if you have PHP code that writes out formatted dates, and want to mimic the functionality using
 414  * progressively enhanced javascript, then this library can do exactly what you want.
 415  *
 416  *
 417  *
 418  *
 419  * \page usage Example usage
 420  *
 421  * \section usage_sec Usage
 422  * This library may be used as follows:
 423  * \code
 424  *     var d = new Date();
 425  *
 426  *     var ymd = d.strftime('%Y/%m/%d');
 427  *     var iso = d.strftime('%Y-%m-%dT%H:%M:%S%z');
 428  *
 429  * \endcode
 430  *
 431  * \subsection examples Examples
 432  *
 433  * To get the current time in hours and minutes:
 434  * \code
 435  *      var d = new Date();
 436  *      d.strftime("%H:%M");
 437  * \endcode
 438  *
 439  * To get the current time with seconds in AM/PM notation:
 440  * \code
 441  *      var d = new Date();
 442  *      d.strftime("%r");
 443  * \endcode
 444  *
 445  * To get the year and day of the year for August 23, 2009:
 446  * \code
 447  *      var d = new Date('2009/8/23');
 448  *      d.strftime("%Y-%j");
 449  * \endcode
 450  *
 451  * \section demo_sec Demo
 452  *
 453  * Try your own examples on the \subpage demo page.  You can use any of the supported
 454  * \subpage format_specifiers.
 455  *
 456  *
 457  *
 458  *
 459  * \page localisation Localisation
 460  * You can localise strftime by implementing the short and long forms for days of the
 461  * week and months of the year, and the localised aggregates for the preferred date
 462  * and time representation for your locale.  You need to add your locale to the
 463  * Date.ext.locales object.
 464  *
 465  * \section localising_fr Localising for french
 466  *
 467  * For example, this is how we'd add French language strings to the locales object:
 468  * \dontinclude index.html
 469  * \skip Generic french
 470  * \until };
 471  * The % format specifiers are all defined in \ref formats.  You can use any of those.
 472  *
 473  * This locale definition may be included in your own source file, or in the HTML file
 474  * including \c strftime.js, however it must be defined \em after including \c strftime.js
 475  *
 476  * The above definition includes generic french strings and formats that are used in France.
 477  * Other french speaking countries may have other representations for dates and times, so we
 478  * need to override this for them.  For example, Canadian french uses a Y-m-d date format,
 479  * while French french uses d.m.Y.  We fix this by defining Canadian french to be the same
 480  * as generic french, and then override the format specifiers for \c x for the \c fr-CA locale:
 481  * \until End french
 482  *
 483  * You can now use any of the French locales at any time by setting \link Date.prototype.locale Date.locale \endlink
 484  * to \c "fr", \c "fr-FR", \c "fr-CA", or any other french dialect:
 485  * \code
 486  *     var d = new Date("2008/04/22");
 487  *     d.locale = "fr";
 488  *
 489  *     d.strftime("%A, %d %B == %x");
 490  * \endcode
 491  * will return:
 492  * \code
 493  *     mardi, 22 avril == 22.04.2008
 494  * \endcode
 495  * While changing the locale to "fr-CA":
 496  * \code
 497  *     d.locale = "fr-CA";
 498  *
 499  *     d.strftime("%A, %d %B == %x");
 500  * \endcode
 501  * will return:
 502  * \code
 503  *     mardi, 22 avril == 2008-04-22
 504  * \endcode
 505  *
 506  * You can use any of the format specifiers defined at \ref formats
 507  *
 508  * The locale for all dates defaults to the value of the \c lang attribute of your HTML document if
 509  * it is set, or to \c "en" otherwise.
 510  * \note
 511  * Your locale definitions \b MUST be added to the locale object before calling
 512  * \link Date.prototype.strftime Date.strftime \endlink.
 513  *
 514  * \sa \ref formats for a list of format specifiers that can be used in your definitions
 515  * for c, x and X.
 516  *
 517  * \section locale_names Locale names
 518  *
 519  * Locale names are defined in RFC 1766. Typically, a locale would be a two letter ISO639
 520  * defined language code and an optional ISO3166 defined country code separated by a -
 521  *
 522  * eg: fr-FR, de-DE, hi-IN
 523  *
 524  * \sa http://www.ietf.org/rfc/rfc1766.txt
 525  * \sa http://www.loc.gov/standards/iso639-2/php/code_list.php
 526  * \sa http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm
 527  *
 528  * \section locale_fallback Locale fallbacks
 529  *
 530  * If a locale object corresponding to the fully specified locale isn't found, an attempt will be made
 531  * to fall back to the two letter language code.  If a locale object corresponding to that isn't found
 532  * either, then the locale will fall back to \c "en".  No warning will be issued.
 533  *
 534  * For example, if we define a locale for de:
 535  * \until };
 536  * Then set the locale to \c "de-DE":
 537  * \code
 538  *     d.locale = "de-DE";
 539  *
 540  *     d.strftime("%a, %d %b");
 541  * \endcode
 542  * In this case, the \c "de" locale will be used since \c "de-DE" has not been defined:
 543  * \code
 544  *     Di, 22 Apr
 545  * \endcode
 546  *
 547  * Swiss german will return the same since it will also fall back to \c "de":
 548  * \code
 549  *     d.locale = "de-CH";
 550  *
 551  *     d.strftime("%a, %d %b");
 552  * \endcode
 553  * \code
 554  *     Di, 22 Apr
 555  * \endcode
 556  *
 557  * We need to override the \c a specifier for Swiss german, since it's different from German german:
 558  * \until End german
 559  * We now get the correct results:
 560  * \code
 561  *     d.locale = "de-CH";
 562  *
 563  *     d.strftime("%a, %d %b");
 564  * \endcode
 565  * \code
 566  *     Die, 22 Apr
 567  * \endcode
 568  *
 569  * \section builtin_locales Built in locales
 570  *
 571  * This library comes with pre-defined locales for en, en-GB, en-US and en-AU.
 572  *
 573  *
 574  *
 575  *
 576  * \page format_specifiers Format specifiers
 577  *
 578  * \section specifiers Format specifiers
 579  * strftime has several format specifiers defined by the Open group at
 580  * http://www.opengroup.org/onlinepubs/007908799/xsh/strftime.html
 581  *
 582  * PHP added a few of its own, defined at http://www.php.net/strftime
 583  *
 584  * This javascript implementation supports all the PHP specifiers
 585  *
 586  * \subsection supp Supported format specifiers:
 587  * \copydoc formats
 588  *
 589  * \subsection unsupportedformats Unsupported format specifiers:
 590  * \copydoc unsupported
 591  *
 592  *
 593  *
 594  *
 595  * \page demo strftime demo
 596  * <div style="float:right;width:45%;">
 597  * \copydoc formats
 598  * </div>
 599  * \htmlinclude index.html
 600  *
 601  *
 602  *
 603  *
 604  * \page faq FAQ
 605  *
 606  * \section how_tos Usage
 607  *
 608  * \subsection howtouse Is there a manual on how to use this library?
 609  *
 610  * Yes, see \ref usage
 611  *
 612  * \subsection wheretoget Where can I get a minified version of this library?
 613  *
 614  * The minified version is available <a href="strftime-min.js" title="Minified strftime.js">here</a>.
 615  *
 616  * \subsection which_specifiers Which format specifiers are supported?
 617  *
 618  * See \ref format_specifiers
 619  *
 620  * \section whys Why?
 621  *
 622  * \subsection why_lib Why this library?
 623  *
 624  * I've used the strftime function in C, PHP and the Unix shell, and found it very useful
 625  * to do date formatting.  When I needed to do date formatting in javascript, I decided
 626  * that it made the most sense to just reuse what I'm already familiar with.
 627  *
 628  * \subsection why_another Why another strftime implementation for Javascript?
 629  *
 630  * Yes, there are other strftime implementations for Javascript, but I saw problems with
 631  * all of them that meant I couldn't use them directly.  Some implementations had bad
 632  * designs.  For example, iterating through all possible specifiers and scanning the string
 633  * for them.  Others were tied to specific libraries like prototype.
 634  *
 635  * Trying to extend any of the existing implementations would have required only slightly
 636  * less effort than writing this from scratch.  In the end it took me just about 3 hours
 637  * to write the code and about 6 hours battling with doxygen to write these docs.
 638  *
 639  * I also had an idea of how I wanted to implement this, so decided to try it.
 640  *
 641  * \subsection why_extend_date Why extend the Date class rather than subclass it?
 642  *
 643  * I tried subclassing Date and failed.  I didn't want to waste time on figuring
 644  * out if there was a problem in my code or if it just wasn't possible.  Adding to the
 645  * Date.prototype worked well, so I stuck with it.
 646  *
 647  * I did have some worries because of the way for..in loops got messed up after json.js added
 648  * to the Object.prototype, but that isn't an issue here since {} is not a subclass of Date.
 649  *
 650  * My last doubt was about the Date.ext namespace that I created.  I still don't like this,
 651  * but I felt that \c ext at least makes clear that this is external or an extension.
 652  *
 653  * It's quite possible that some future version of javascript will add an \c ext or a \c locale
 654  * or a \c strftime property/method to the Date class, but this library should probably
 655  * check for capabilities before doing what it does.
 656  *
 657  * \section curiosity Curiosity
 658  *
 659  * \subsection how_big How big is the code?
 660  *
 661  * \arg 26K bytes with documentation
 662  * \arg 4242 bytes minified using <a href="http://developer.yahoo.com/yui/compressor/">YUI Compressor</a>
 663  * \arg 1477 bytes minified and gzipped
 664  *
 665  * \subsection how_long How long did it take to write this?
 666  *
 667  * 15 minutes for the idea while I was composing this blog post:
 668  * http://tech.bluesmoon.info/2008/04/javascript-date-functions.html
 669  *
 670  * 3 hours in one evening to write v1.0 of the code and 6 hours the same
 671  * night to write the docs and this manual.  As you can tell, I'm fairly
 672  * sleepy.
 673  *
 674  * Versions 1.1 and 1.2 were done in a couple of hours each, and version 1.3
 675  * in under one hour.
 676  *
 677  * \section contributing Contributing
 678  *
 679  * \subsection how_to_rfe How can I request features or make suggestions?
 680  *
 681  * You can leave a comment on my blog post about this library here:
 682  * http://tech.bluesmoon.info/2008/04/strftime-in-javascript.html
 683  *
 684  * \subsection how_to_contribute Can I/How can I contribute code to this library?
 685  *
 686  * Yes, that would be very nice, thank you.  You can do various things.  You can make changes
 687  * to the library, and make a diff against the current file and mail me that diff at
 688  * philip@bluesmoon.info, or you could just host the new file on your own servers and add
 689  * your name to the copyright list at the top stating which parts you've added.
 690  *
 691  * If you do mail me a diff, let me know how you'd like to be listed in the copyright section.
 692  *
 693  * \subsection copyright_signover Who owns the copyright on contributed code?
 694  *
 695  * The contributor retains copyright on contributed code.
 696  *
 697  * In some cases I may use contributed code as a template and write the code myself.  In this
 698  * case I'll give the contributor credit for the idea, but will not add their name to the
 699  * copyright holders list.
 700  *
 701  *
 702  *
 703  *
 704  * \page copyright_licence Copyright & Licence
 705  *
 706  * \section copyright Copyright
 707  * \dontinclude strftime.js
 708  * \skip Copyright
 709  * \until rights
 710  *
 711  * \section licence Licence
 712  * \skip This code
 713  * \until SUCH DAMAGE.
 714  *
 715  *
 716  *
 717  * \page changelog ChangeLog
 718  *
 719  * \par 1.3 - 2008/06/17:
 720  * - Fixed padding issue with negative timezone offsets in %r
 721  *   reported and fixed by Mikko <mikko.heimola@iki.fi>
 722  * - Added support for %P
 723  * - Internationalised %r, %p and %P
 724  *
 725  * \par 1.2 - 2008/04/27:
 726  * - Fixed support for c (previously it just returned toLocaleString())
 727  * - Add support for c, x and X
 728  * - Add locales for en-GB, en-US and en-AU
 729  * - Make en-GB the default locale (previous was en)
 730  * - Added more localisation docs
 731  *
 732  * \par 1.1 - 2008/04/27:
 733  * - Fix bug in xPad which wasn't padding more than a single digit
 734  * - Fix bug in j which had an off by one error for days after March 10th because of daylight savings
 735  * - Add support for g, G, U, V and W
 736  *
 737  * \par 1.0 - 2008/04/22:
 738  * - Initial release with support for a, A, b, B, c, C, d, D, e, H, I, j, m, M, p, r, R, S, t, T, u, w, y, Y, z, Z, and %
 739  */