CODEWITHSUNDEEP
javascriptdatetimespecifications
MetaSean
MetaSean

Reputation: 951

What are the differences between the hourCycle options in Date.prototype.toLocaleTimeString()

MDN documentation for toLocaleTimeString() indicates that the hourCycle and hc options have four possible values: "h11", "h12", "h23", & "h24".

Two of the possible values strike me as super obvious (i.e. "h12" and "h24"), but the other two, I have no idea what they do and my duckduckfoo/googlefoo is failing me!

What are the "h11" and "h23" values representing?

My best guess is that they are some type of 0 vs 1 derivations of "h12" and "h24", but the underlying date stamp is still the same, and the value logged is the same, so if this is it, where is the difference?

This should be documented, or at least linked to, on MDN's toLocalTimeString page or ECMAScript's toLocalTimeString page, but it's not. It also really strikes me as something that should be simple to figure out, and yet I’m not seeing the difference, and it’s now crawling under my skin!

const now = new Date();
console.log('hourCycle: h11', now.toLocaleTimeString('en-US', { hourCycle: 'h11' }))
console.log('hourCycle: h12', now.toLocaleTimeString('en-US', { hourCycle: 'h12' }))
console.log('hourCycle: h23', now.toLocaleTimeString('en-US', { hourCycle: 'h23' }))
console.log('hourCycle: h24', now.toLocaleTimeString('en-US', { hourCycle: 'h24' }))

Upvotes: 16

Views: 8369

Answers (4)

metric152
metric152

Reputation: 432

I know this is a new answer to an old question but the different values have been outline on the MDN. The page is buried and hard to find.

Here are all the listed values.

I ran into this problem face first when trying to create dates in a different timezone using toLocaleTimeString. The times at midnight came back as 24:01:45 and new Date kept choking on it. With only an hour left I had to scramble for an answer. Looks like h24 has limited applications so I'm not sure what it's used for. If you want a format that new Date will accept use h23.

Upvotes: 0

RobG
RobG

Reputation: 147483

Many answers here referencing MDN, however the relevant standard is ECMA-402, so look there.

The hourCycle and hour12 options work as described in ECMA-402 §11.1.1 #40. The way they work in practice seems to be at odds with the specification.

What happens in various browsers is that setting hour12 to true or false means that the language default hour cycle may or may not be adopted, regardless of the hour cycle in the options.

A more reliable method is to set the hourCycle in the language tag, some examples:

// 1 Jan 2022 00:30
let d = new Date(2022,0,1,0,30);

// Specify only hour12: false, get default hour cycle for en-US
// Safari, Firefox 00:30:00
// Chrome 24:30:00
console.log(d.toLocaleTimeString('en-US',{hour12: false}));

// Specify only hourCycle: h24, forces hour12: false
// Safari, Firefox 24:30:00
// Chrome 24:30:00
console.log(d.toLocaleTimeString('en-US',{hourCycle: 'h24'}));

// Specify both, the default hourCycle is used
// Safari, Firefox 00:30:00
// Chrome 24:30:00
console.log(d.toLocaleTimeString('en-US',{hourCycle: 'h24', hour12: false}));

// All three browsers: 00:30:00
console.log(d.toLocaleTimeString('en-US-u-hc-h23'));

// All three browsers: 24:30:00
console.log(d.toLocaleTimeString('en-US-u-hc-h24'));

Upvotes: 2

5260452
5260452

Reputation: 11620

I agree it's currently difficult to find MDN's documentation on hourCycle values, but I found them here:

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Locale/hourCycle

Web technology for developers > JavaScript > JavaScript reference > Standard built-in objects > Intl.Locale > Intl.Locale.prototype.hourCycle

[…]

h12: Hour system using 1–12; corresponds to 'h' in patterns. The 12 hour clock, with midnight starting at 12:00 am.

h23: Hour system using 0–23; corresponds to 'H' in patterns. The 24 hour clock, with midnight starting at 0:00.

h11: Hour system using 0–11; corresponds to 'K' in patterns. The 12 hour clock, with midnight starting at 0:00 am.

h24: Hour system using 1–24; corresponds to 'k' in pattern. The 24 hour clock, with midnight starting at 24:00.

Upvotes: 9

criticabug
criticabug

Reputation: 391

I found that the proposal of dateStyle and timeStyle options for Intl.DateTimeFormat says:

[[HourCycle]] is a String value indicating whether the 12-hour format ("h11", "h12") or the 24-hour format ("h23", "h24") should be used. "h11" and "h23" start with hour 0 and go up to 11 and 23 respectively. "h12" and "h24" start with hour 1 and go up to 12 and 24. [[HourCycle]] is only used when [[Hour]] is not undefined.

English or US style may prefer h12:

› new Date(2019,4,1,12,0,0).toLocaleString('en-US', { hourCycle: 'h12' })
‹ "5/1/2019, 12:00:00 PM"
› new Date(2019,4,1,12,0,0).toLocaleString('en-US', { hourCycle: 'h11' })
‹ "5/1/2019, 0:00:00 PM"

h24 must be used with caution. It would have been nice if the date part was the value one day before.

› new Date(2019,4,1,0,59,59).toLocaleString('ja-JP', { hourCycle: 'h23' })
‹ "2019/5/1 0:59:59"
› new Date(2019,4,1,0,59,59).toLocaleString('ja-JP', { hourCycle: 'h24' })
‹ "2019/5/1 24:59:59"

Compatibility table in MDN says Firefox 58 and Edge supports this.

Upvotes: 13

Related Questions