<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../../make-menu.xsl" type="text/xsl"?><html>
   <head>
      <this-is section="functions" page="intro" subpage="format-dateTime"/>
      <!--
           Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: format-dateTime</title>
      <meta name="coverage" content="Worldwide"/>
      <meta name="copyright" content="Copyright Saxonica Ltd"/>
      <meta name="title" content="Saxonica: XSLT and XQuery Processing: format-dateTime"/>
      <meta name="robots" content="noindex,nofollow"/>
      <link rel="stylesheet" href="../../saxondocs.css" type="text/css"/>
   </head>
   <body class="main">
      <h1>format-dateTime</h1>
      <p class="subhead">format-dateTime($value as xs:dateTime?, $picture as xs:string) &#8594; xs:string?</p>
      <p>Formats a dateTime, using a format controlled by the picture string. 
               The result is equivalent to the 5-argument form of the function, with the third, fourth, and fifth
               arguments set to an empty sequence.</p>
      <table>
         <tr>
            <td width="470" align="left" colspan="4" style="border-top:solid 1px #3D5B96; ">
               <p>
                     <i>Arguments</i>
                  </p>
            </td>
         </tr>
         <tr>
            <td width="40">
               <p> </p>
            </td>
            <td width="80" valign="top">
               <p>$value</p>
            </td>
            <td valign="top" width="150">
               <p>xs:dateTime?</p>
            </td>
            <td valign="top" width="200">
               <p>The dateTime to be formatted</p>
            </td>
         </tr>
         <tr>
            <td width="40">
               <p> </p>
            </td>
            <td width="80" valign="top">
               <p>$picture</p>
            </td>
            <td valign="top" width="150">
               <p>xs:string</p>
            </td>
            <td valign="top" width="200">
               <p>Picture showing how the dateTime is to be formatted</p>
            </td>
         </tr>
         <tr>
            <td colspan="2"
                style="border-top:solid 1px #3D5B96; border-bottom:solid 1px #3D5B96;">
               <p>
                     <i>Result</i>
                  </p>
            </td>
            <td style="border-top:solid 1px #3D5B96; border-bottom:solid 1px #3D5B96;"
                colspan="2">
               <p>xs:string?</p>
            </td>
         </tr>
      </table>
      <p class="subhead">format-dateTime($value as xs:dateTime?, $picture as xs:string, $language as xs:string?, $calendar as xs:string?, $place as xs:string?) &#8594; xs:string?</p>
      <p>Formats a dateTime, using a format controlled by the picture string.</p>
      <table>
         <tr>
            <td width="470" align="left" colspan="4" style="border-top:solid 1px #3D5B96; ">
               <p>
                     <i>Arguments</i>
                  </p>
            </td>
         </tr>
         <tr>
            <td width="40">
               <p> </p>
            </td>
            <td width="80" valign="top">
               <p>$value</p>
            </td>
            <td valign="top" width="150">
               <p>xs:dateTime?</p>
            </td>
            <td valign="top" width="200">
               <p>The dateTime to be formatted</p>
            </td>
         </tr>
         <tr>
            <td width="40">
               <p> </p>
            </td>
            <td width="80" valign="top">
               <p>$picture</p>
            </td>
            <td valign="top" width="150">
               <p>xs:string</p>
            </td>
            <td valign="top" width="200">
               <p>Picture showing how the dateTime is to be formatted</p>
            </td>
         </tr>
         <tr>
            <td width="40">
               <p> </p>
            </td>
            <td width="80" valign="top">
               <p>$language</p>
            </td>
            <td valign="top" width="150">
               <p>xs:string?</p>
            </td>
            <td valign="top" width="200">
               <p>The language for the output</p>
            </td>
         </tr>
         <tr>
            <td width="40">
               <p> </p>
            </td>
            <td width="80" valign="top">
               <p>$calendar</p>
            </td>
            <td valign="top" width="150">
               <p>xs:string?</p>
            </td>
            <td valign="top" width="200">
               <p>The calendar for the output</p>
            </td>
         </tr>
         <tr>
            <td width="40">
               <p> </p>
            </td>
            <td width="80" valign="top">
               <p>$place</p>
            </td>
            <td valign="top" width="150">
               <p>xs:string?</p>
            </td>
            <td valign="top" width="200">
               <p>The country or Olson timezone where the event took place</p>
            </td>
         </tr>
         <tr>
            <td colspan="2"
                style="border-top:solid 1px #3D5B96; border-bottom:solid 1px #3D5B96;">
               <p>
                     <i>Result</i>
                  </p>
            </td>
            <td style="border-top:solid 1px #3D5B96; border-bottom:solid 1px #3D5B96;"
                colspan="2">
               <p>xs:string?</p>
            </td>
         </tr>
      </table>
      <p class="subhead">Links to W3C specifications</p>
      <p>Namespace: http://www.w3.org/2005/xpath-functions</p>
      <p>Applies to: XPath 2.0, XSLT 2.0, XQuery 1.0 and later versions</p>
      <p>
            <a href="http://www.w3.org/TR/xpath-functions/#func-format-dateTime"
            class="bodylink">XPath 2.0 Functions and Operators</a>
         </p>
      <p>
            <a href="http://www.w3.org/TR/xpath-functions-30/#func-format-dateTime"
            class="bodylink">XPath 3.0 Functions and Operators</a>
         </p>
      <p class="subhead">Notes on the Saxon implementation</p>
      <p>Formats a date, using a format controlled by the picture string. If no language
    is specified, the value is taken from the current Java locale. If the language (explicitly supplied
    or defaulted) is other than "en", the system tries to locate a localization class for the language (called,
    for historic reasons, a <i>Numberer</i>; this class must provide methods to perform the localization.</p>
      <p>Support for English (language="en") is built-in in all versions of the product.</p>
      <p>In Saxon-PE and Saxon-EE, support for a variety of other European languages is also built in:
        specifically da, de, fr, fr_BE, he, it, nl, nl_BE, and sv. The localization modules for these languages
        have names such as <code>net.sf.saxon.option.local.Numberer_da</code>. These modules are not built in
        with Saxon-HE, but they are available as open source code, and it is possible to configure them by
        writing a subclass of <a class="bodylink" href="../../javadoc/net/sf/saxon/lib/LocalizerFactory.html"><code>LocalizerFactory</code></a> and registering
        it with the <a class="bodylink" href="../../javadoc/net/sf/saxon/Configuration.html"><code>Configuration</code></a>.</p>
      <p>Localization modules for other languages can be configured. They are written to implement the interface
         <a class="bodylink" href="../../javadoc/net/sf/saxon/lib/Numberer.html"><code>Numberer</code></a>, typically as subclasses of 
         <a class="bodylink"
            href="../../javadoc/net/sf/saxon/expr/number/AbstractNumberer.html"><code>AbstractNumberer</code></a>. In Saxon-HE they are configured in the
         same way as the system-supplied languages. In Saxon-PE and Saxon-EE they can be registered in one of two ways:
         programmatically using the call <code>Configuration.getLocalizerFactory().setLanguageProperties("ja", props))</code>
         where <code>props</code> is a <code>Properties</code> object in which the <code>class</code> property
         is set to the name of the relevant <code>Numberer</code> class; or by setting an entry in the 
         <a class="bodylink" href="../../configuration/configuration-file.xml">configuration file</a>. For more information
         on writing localization modules, see <a class="bodylink" href="../../extensibility/localizing.xml">Localizing numbers and dates</a>.</p>
      <p>If a calendar other than
    AD or ISO is specified, the result is prefixed "[Calendar: AD]" and is otherwise output as if the default
    calendar were used.</p>
      <p>The country argument is currently used only when the format requests output of timezones
	by name (using <code>[ZN]</code>): for example with language="en", country="gb" and a date that falls in British Summer Time, 
	+01:00 is output as "BST". This is problematic, because the information is not really
available: the data type maintains only a time zone offset, and different countries (time zones) use different names
for the same offset, at different times of year. If the value is a date or dateTime, and if the country argument is
supplied, Saxon uses the Java database of time zones and daylight savings time (summer time) changeover dates
to work out the most likely timezone applicable to the date in question.</p>
      <p>If the timezone is formatted as [ZN,6] (specifically, with a minumum length of 6 or more) then the Olsen timezone name
is output (again, this requires the country to be supplied). The Olsen timezone name generally takes the form
<code>Continent/City</code>, for example "Europe/London" or "America/Los_Angeles". If the date/time is in daylight
savings time for that timezone, an asterisk is appended to the Olsen timezone name.</p>
      <p>When formatting times in the 12-hour clock, with language="en", the abbreviations "a.m." and "p.m." are used. These
can be shortened to "am" and "pm" by giving a maximum width of 2 (<code>[PN,*-2]</code>). The US convention of denoting
noon as "pm" and midnight as "am" is followed, unless the maximum width is 8 or more (<code>[PN,*-8]</code>) in which case
these values are represented as "noon" and "midnight" respectively.</p>
      <p>
            <i>The rules for formatting of timezones have been clarified and extended in the XPath 3.0 version of the specification.
As of Saxon 9.4, these changes are not yet implemented.</i>
         </p>
      <table width="100%">
         <tr>
            <td>
               <p align="right"><a class="nav" href="format-integer.xml">Next</a></p>
            </td>
         </tr>
      </table>
   </body>
</html>