mozilla

Revision 336833 of Date.prototype.toLocaleString()

  • Revision slug: JavaScript/Reference/Global_Objects/Date/toLocaleString
  • Revision title: Date.toLocaleString
  • Revision id: 336833
  • Created:
  • Creator: ethertank
  • Is current revision? No
  • Comment

Revision Content

Summary

Converts a date to a string, using the operating system's locale's conventions.

Method of Date
Implemented in JavaScript 1.0
ECMAScript Edition ECMAScript 1st Edition

Syntax

toLocaleString() 

Parameters

None.

Description

The toLocaleString method relies on the underlying operating system in formatting dates. It converts the date to a string using the formatting convention of the operating system where the script is running. For example, in the United States, the month appears before the date (04/15/98), whereas in Germany the date appears before the month (15.04.98). If the operating system is not year-2000 compliant and does not use the full year for years before 1900 or over 2000, toLocaleString returns a string that is not year-2000 compliant. toLocaleString behaves similarly to toString when converting a year that the operating system does not properly format.

Methods such as getDate, getMonth, getFullYear, getHours, getMinutes, and getSeconds give more portable results than toLocaleString. Use toLocaleString when the intent is to display to the user a string formatted using the regional format chosen by the user. Be aware that this method, due to its nature, behaves differently depending on the operating system and on the user's settings.

Examples

Using toLocaleString

In the following example, today is a Date object:

var today = new Date(95,11,18,17,28,35); //months are represented by 0 to 11

today.toLocaleString();

In this example, toLocaleString returns a string value that is similar to the following form. The exact format depends on the platform, locale and user's settings.

12/18/95 17:28:35

You shouldn't use this method in contexts where you rely on a particular format or locale.

"Last visit: " + someDate.toLocaleString(); // Good example
"Last visit was at " + someDate.toLocaleString(); // Bad example

Browser compatibility

{{CompatibilityTable}}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support {{CompatNo}} {{CompatVersionUnknown}} {{CompatNo}} {{CompatUnknown}} {{CompatUnknown}}
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support {{CompatUnknown}} {{CompatVersionUnknown}} {{CompatUnknown}} {{CompatUnknown}} {{CompatUnknown}}

See also

Revision Source

<h2 id="Summary" name="Summary">Summary</h2>
<p>Converts a date to a string, using the operating system's locale's conventions.</p>
<table class="standard-table">
  <thead>
    <tr>
      <th class="header" colspan="2">Method of <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Date" title="JavaScript/Reference/Global_Objects/Date"><code>Date</code></a></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Implemented in</td>
      <td>JavaScript 1.0</td>
    </tr>
    <tr>
      <td>ECMAScript Edition</td>
      <td>ECMAScript 1st Edition</td>
    </tr>
  </tbody>
</table>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="syntaxbox"><code>toLocaleString() </code></pre>

<h3 id="Parameters" name="Parameters">Parameters</h3>

<p>None.</p>

<h2 id="Description" name="Description">Description</h2>
<p>The <code>toLocaleString</code> method relies on the underlying operating system in formatting dates. It converts the date to a string using the formatting convention of the operating system where the script is running. For example, in the United States, the month appears before the date (04/15/98), whereas in Germany the date appears before the month (15.04.98). If the operating system is not year-2000 compliant and does not use the full year for years before 1900 or over 2000, <code>toLocaleString</code> returns a string that is not year-2000 compliant. <code>toLocaleString</code> behaves similarly to <code>toString</code> when converting a year that the operating system does not properly format.</p>
<p>Methods such as <code><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Date/getDate" title="JavaScript/Reference/Global_Objects/Date/getDate">getDate</a></code>, <code><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Date/getMonth" title="JavaScript/Reference/Global_Objects/Date/getMonth">getMonth</a></code>, <code><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Date/getFullYear" title="JavaScript/Reference/Global_Objects/Date/getYullYear">getFullYear</a></code>, <code><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Date/getHours" title="JavaScript/Reference/Global_Objects/Date/getHours">getHours</a></code>, <code><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Date/getMinutes" title="JavaScript/Reference/Global_Objects/Date/getMinutes">getMinutes</a></code>, and <code><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Date/getSeconds" title="JavaScript/Reference/Global_Objects/Date/getSeconds">getSeconds</a></code> give more portable results than <code>toLocaleString</code>. Use <code>toLocaleString</code> when the intent is to display to the user a string formatted using the regional format chosen by the user. Be aware that this method, due to its nature, behaves differently depending on the operating system and on the user's settings.</p>

<h2 id="Examples" name="Examples">Examples</h2>

<h3 id="Using_toLocaleString" name="Using_toLocaleString">Using <code>toLocaleString</code></h3>
<p>In the following example, <code>today</code> is a <code>Date</code> object:</p>

<pre class="brush:js">var today = new Date(95,11,18,17,28,35); //months are represented by 0 to 11

today.toLocaleString();</pre>

<p>In this example, <code>toLocaleString</code> returns a string value that is similar to the following form. The exact format depends on the platform, locale and user's settings.</p>

<pre>12/18/95 17:28:35</pre>

<p>You shouldn't use this method in contexts where you rely on a particular format or locale.</p>

<pre class="brush:js">
"Last visit: " + someDate.toLocaleString(); // Good example
"Last visit was at " + someDate.toLocaleString(); // Bad example</pre>

<h2 id="See_also" name="See_also">Browser compatibility</h2>
<p>{{CompatibilityTable}}</p>
<div id="compat-desktop">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Chrome</th>
        <th>Firefox (Gecko)</th>
        <th>Internet Explorer</th>
        <th>Opera</th>
        <th>Safari (WebKit)</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{CompatNo}}</td>

        <td>{{CompatVersionUnknown}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatUnknown}}</td>
        <td>{{CompatUnknown}}</td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Firefox Mobile (Gecko)</th>
        <th>IE Phone</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{CompatUnknown}}</td>
        <td>{{CompatVersionUnknown}}</td>
        <td>{{CompatUnknown}}</td>
        <td>{{CompatUnknown}}</td>
        <td>{{CompatUnknown}}</td>
      </tr>
    </tbody>
  </table>
</div>

<h2 id="See_also" name="See_also">See also</h2>
<ul>
  <li><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Date/toString" title="JavaScript/Reference/Global_Objects/Date/toString">toString</a></li>
  <li><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Date/toUTCString" title="JavaScript/Reference/Global_Objects/Date/toUTCString">toUTCString</a></li>
  <li><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Date/toLocaleDateString" title="JavaScript/Reference/Global_Objects/Date/toLocaleDateString">toLocaleDateString</a></li>
  <li><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Date/toLocaleTimeString" title="JavaScript/Reference/Global_Objects/Date/toLocaleTimeString">toLocaleTimeString</a></li>
</ul>
Revert to this revision