893512 - Add a prtime-replacable Time class to MFBT

Status: NEW

(Core :: MFBT, defect)

Description

[Joshua Cranmer [:jcranmer]]

Isn't this XPCOM's mozilla::TimeStamp? Nope. mozilla::TimeStamp is designed to guarantee monotonicity, i.e., if TimeStamp::Now() is called twice, the result of the later call is always greater than the result of the earlier call.

prtime.h defines the following functions:
PR_Now [self-explanatory]
PR_ExplodeTime [get seconds/months/etc. in GMT or local time for a PRTime]
PR_ImplodeTime [go from seconds/months/etc. to PRTime]
PR_NormalizeTime [ensure, e.g., hour-of-day is between 0 and 23]
PR_ParseTimeString/PR_ParseTimeStringToExplodedTime [go from a variety of date/time formats to PRTime/PRExplodedTime]
PR_FormatTime{USEnglish} [invert the latter. Note we appear to only use the USEnglish variant.]

These are basically equivalents to the strftime/mktime et al functions in C, along with a well-defined conversion to/from time_t. Unfortunately, I can't find good precedents for this API:
* C++11 does nothing here, only letting you convert system_clock's timepoints to time_t
* Boost does the same thing as C++11. Most of its discussion is in using durations to make milliseconds/microseconds/etc. distinction obvious, and handling date-times as concrete instances is not specified.
* Python just uses the C API
* JS is completely and totally helpless here (they don't even define *how* to parse a string, except by saying "ISO8601 must work!")
* Java. Ahahahahahahaha.
* Rust. Appears to also follow the C API (or, more accurately, python API?).

Comment 1

[Joshua Cranmer [:jcranmer]]

Strawman API:

Okay, first off, I don't know what to do about timezones. Those are crazy, and politicians love to make DST a living nightmare. So let's start with the simple stuff.

The basic class would be mozilla::DateTime, which is a wrapper around PRTime/time_t (time from UTC epoch). Predecessors and use cases can't agree on the granularity of time, but since the primary intended use I'm specing here is for dates and times, sub-second granularity is probably not important to many users. For now, let's pretend it's a mozilla::Duration from epoch. The name DateTime hopefully places more emphasis on the Date part.

Since everyone uses different granularities for duration, DateTime is going to need:
  uint32_t AsSeconds(); // Compatibility with time_t
  uint64_t AsMilliseconds(); // For JS's Date representation
  uint64_t AsMicroseconds(); // For PRTime
  DateTime(const Duration &d);
  static DateTime Now();

A few global functions should set up durations nicely:
Duration Weeks(uint32_t weeks), Days(uint32_t days), Hours(uint32_t hours), Minutes(uint32_t minutes), Seconds(uint32_t seconds), Milliseconds(uint64_t ms), Microseconds(uint32_t us);

Like TimeStamp, DateTime would need comparison operators and addition/subtraction operators. The reason why the global functions are set up to return durations is so you can do something like:
DateTime messageAge = ...;
if (DateTime::Now() - messageAge > Days(7))
  deleteMessage();

Now for the string conversions. One complication is that MFBT has no string APIs. For string-to-date conversions, that's not a big deal (const char * + length). For date-to-string, it's an issue I'm going to punt on for now.

The two most important conversions to output are RFC 822 format [even though it's now 5322, but who cares] and ISO 8601 format, i.e.:
DayOfWeek, Day Month Year Hour:Minute:Second -0500 [RFC 822]
YYYY-MM-DDThh:mm:ssTZD [ISO 8601]

Supporting full strftime formatting also looks necessary, unfortunately. These means the following functions would be necessary:
  ToRFC822String
  ToISO8601String
  ToFormattedString

Coming from strings, we need a function that is in the same "wild" spirit as PR_ParseTimeString, but we may also want something that only accepts the stricter subset of ISO 8601 (sub)strings. I don't know if we need full strptime compatibility, but we haven't had an NSPR function for it, so I think not. These functions need a "default" timezone to assume (which should default to local time, methinks):
  ParseString(const char *str, TimeZone default = TimeZone::Local);
  ParseString(const char *str, size_t len, TimeZone default = TimeZone::Local);
  ParseISO8601String(...)

It is occasionally useful to get timezone information when parsing date/time strings, which makes me think that DateTime should also store the tzoffset. The more I think about it, the closer DateTime comes to being PRExplodedTime instead of PRTime. The main difference is that PRExplodedTime makes string conversions and component accessors much faster, while PRTime is much easier to convert to durations and PRTime/etc.