395794 - write some documentation for toLocaleFormat()

Status: RESOLVED WORKSFORME

(Documentation Graveyard :: Web Developer, defect)

Description

[(not reading, please use [e-mail] instead)]

add a "separator" parameter to nsIScriptableDateFormat

from bug #395773, dietrich wrote:

"it'd be nice to add a separator option to
nsIScriptableDateFormatter, can you please file a followup for that if you
think the idea has merit?"

note, there are other illegal characters on various platforms, see http://lxr.mozilla.org/seamonkey/source/xpcom/ds/nsCRT.h#275), for example ":" on windows.

this feels like a wontfix, and should be the responsibilty of the caller to remove or change any "illegal" separators if they intend to use it for a file name.

but at least we have a bug to discuss it.

Comment 1

[Dan Mills [:thunder]]

Rather than an option for the separator, I would prefer the ability to give a format string such as the ones for the 'date' command.

An example from the date(1) man page:

     The command:

           date "+DATE: %m/%d/%y%nTIME: %H:%M:%S"

     will display:

           DATE: 11/21/87
           TIME: 13:36:16

TBH, I think this should be built-in functionality for the Date object.

Comment 2

[Dão Gottwald [:dao]]

I'm all for a wontfix, as using a random separator for a local format produces non-conforming dates. There are standards bodies that define how a date has to look like, and users also expect that.

(In reply to comment #1)
> Rather than an option for the separator, I would prefer the ability to give a
> format string such as the ones for the 'date' command.
> 
> An example from the date(1) man page:
> 
>      The command:
> 
>            date "+DATE: %m/%d/%y%nTIME: %H:%M:%S"
> 
>      will display:
> 
>            DATE: 11/21/87
>            TIME: 13:36:16
> 
> TBH, I think this should be built-in functionality for the Date object.

Yeah, see http://en.design-noir.de/webdev/JS/Date.format/

Comment 3

[Neil Deakin]

(In reply to comment #2)

> > 
> > TBH, I think this should be built-in functionality for the Date object.
> 

It already is:
  (new Date()).toLocaleFormat("%H %M %S")

Comment 4

[Dão Gottwald [:dao]]

(In reply to comment #3)
Where's that documented?

Comment 5

[:Gavin Sharp [email: [e-mail]]]

Looks like nowhere official, but there is http://developer.mozilla.org/en/docs/User:Waldo:Date.toLocaleFormat for whatever that's worth :)

Comment 6

[Dan Mills [:thunder]]

I was going by http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Date (where there's no mention of it).

This bug should be wontfixed in my opinion.  If you need to dictate the syntax of the date string, you should format it yourself with toLocaleFormat.

How do we ensure it gets documented in all the right places?  Spinoff bug?  That's a very useful method.

Comment 7

[(not reading, please use [e-mail] instead)]

I agree, the original bug is wontfix.

morphing bug, and cc'ing waldo and sheppy.

Comment 8

[Jeff Walden [:Waldo]]

To be honest, I sort of stopped documenting it because it turns out our implementation relies on the C strftime API, which as a platform-specific API is inconsistent in its implementation.  For example, Microsoft doesn't implement %D, but <http://www.opengroup.org/onlinepubs/007908799/xsh/strftime.html> claims that it's part of the "Unix" (so in glibc?) platform.  Also see the ifdefs in date_toLocale(Date)?String for more platform-specificity.

If we really want to publicize a date-formatting method, I think we should roll our own formatting method whose exact characteristics can be guaranteed to be the same across platforms, tedious tho that might be.  There's also a possibility that some of this has made its way into ES4, tho I've not been following the list closely enough lately to know for sure (and I'm not caught up on older archive-reading, either).

While we're on the subject of that API, do note that output of strftime is locale-specific, so you're sort of hoping you're in en-US or something like that or else you'll get something in the user's OS language, I think.  I've only skimmed the code somewhat cursorily, so take this with a grain of salt.

Comment 9

[Marc Diethelm]

Can this be true? (Rubbing eyes) There's really no safe way to localize a date in Mozilla beloved?

In the extension I'm writing localizers need to be able to format dates with a property file. So it would be very convenient to put the format_string into the property file and then use something like toLocaleFormat(format_string) to do this reliably! Unfortunately here on WinXP I can't even get %d for day (01-31) or %e for day (1-31). %d resulted in 0 and %e gave 0.000000e+00. I admit it has a certain comedic value, but it makes building an application for Mozilla a pain.

People are playing with 3D Canvas and I can't format a simple date. Surreal...
I guess I'll have to try and use SQLite's date functions in mozStorage.
http://www.sqlite.org/cvstrac/wiki?p=DateAndTimeFunctions

Comment 10

[Florian Scholz (Open Web Docs)]

No activity here in almost 7 years and there is documentation about this method:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleFormat

Also note the new Intl API https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat

Please open new issues against MDN in the "Developer Documentation" product and in "JS Engine" for SpiderMonkey implementation issues/concerns. This product ("Documentation") is a graveyard.