1519167 - Implement the Temporal proposal

Status: ASSIGNED

(Core :: JavaScript Engine, enhancement, P3)

Description

[Alexandre Folle de Menezes]

The proposal is currently in Stage 2.

Comment 1

[André Bargull [:anba]]

Taking for now because I've already written some code.

Comment 2

[Alexandre Folle de Menezes]

Proposal now in Stage 3.

Comment 3

[Yulia Startsev [:yulia] | Back in Oct.]

This is currently blocked from shipping unflagged on IETF Standardization work: https://github.com/tc39/proposal-temporal/issues/1450

Comment 4

[André Bargull [:anba]]

FWIW, I have a local prototype which includes everything from the current proposal apart from https://tc39.es/proposal-temporal/#sec-temporal-legacy-date-objects and https://tc39.es/proposal-temporal/#sec-temporal-intl. Unsurprisingly a proposal as large as Temporal has numerous issues, I've already filed some at https://github.com/tc39/proposal-temporal/issues/1502, but in the meantime I've found more issues. (There are more than 350 FIXME and TODO annotations referring to spec issues in that prototype.) My current plan is to wait until the spec authors have addressed this feedback before I'll upload the patches for review, because I don't think it makes sense to spend time reviewing code which is still so volatile. And waiting a bit longer gives me additional time to clean-up the code, add comments, etc. :-)

Comment 5

[André Bargull [:anba]]

In its current form, without any optimisations or overly large comments except spec-step comments, the number of lines already exceeds "builtin/intl", so reviewers will have their, err..., fun! :-)

~/hg/mozilla-inbound$ LANG=C wc -l js/src/builtin/temporal/*
  2819 js/src/builtin/temporal/Calendar.cpp
   149 js/src/builtin/temporal/Calendar.h
  5500 js/src/builtin/temporal/Duration.cpp
   107 js/src/builtin/temporal/Duration.h
  2006 js/src/builtin/temporal/Instant.cpp
    80 js/src/builtin/temporal/Instant.h
    35 js/src/builtin/temporal/moz.build
  2419 js/src/builtin/temporal/PlainDate.cpp
    85 js/src/builtin/temporal/PlainDate.h
  2940 js/src/builtin/temporal/PlainDateTime.cpp
   110 js/src/builtin/temporal/PlainDateTime.h
  1174 js/src/builtin/temporal/PlainMonthDay.cpp
    58 js/src/builtin/temporal/PlainMonthDay.h
  2277 js/src/builtin/temporal/PlainTime.cpp
    84 js/src/builtin/temporal/PlainTime.h
  1943 js/src/builtin/temporal/PlainYearMonth.cpp
    59 js/src/builtin/temporal/PlainYearMonth.h
  2558 js/src/builtin/temporal/Temporal.cpp
   334 js/src/builtin/temporal/Temporal.h
   494 js/src/builtin/temporal/TemporalNow.cpp
    31 js/src/builtin/temporal/TemporalNow.h
  2584 js/src/builtin/temporal/TemporalParser.cpp
    61 js/src/builtin/temporal/TemporalParser.h
    76 js/src/builtin/temporal/TemporalTypes.h
    67 js/src/builtin/temporal/TemporalTypes-inl.h
  1912 js/src/builtin/temporal/TimeZone.cpp
    96 js/src/builtin/temporal/TimeZone.h
    22 js/src/builtin/temporal/Wrapped.cpp
   183 js/src/builtin/temporal/Wrapped.h
  3902 js/src/builtin/temporal/ZonedDateTime.cpp
   131 js/src/builtin/temporal/ZonedDateTime.h
 34296 total

Comment 6

[Yulia Startsev [:yulia] | Back in Oct.]

Wow, amazing stuff. Can't wait to review ;) maybe we can have a couple of us do it..

Comment 7

[André Bargull [:anba]]

Attachment: WIP: Bug 1519167 - Part 2: Add config for Temporal.

Comment 8

[André Bargull [:anba]]

Attachment: WIP: Bug 1519167 - Part 3: Add source files.

Depends on D124224

Comment 9

[André Bargull [:anba]]

Attachment: WIP: Bug 1519167 - Part 4: Add Temporal object.

Depends on D124225

Comment 10

[André Bargull [:anba]]

Attachment: WIP: Bug 1519167 - Part 6: Temporal tests.

Depends on D124226

Comment 11

[André Bargull [:anba]]

This is the current prototype, not yet ready for review. There is currently one large patch which covers the whole proposal, for review it will be split into smaller, reviewable parts. The --with-temporal-api flag must be set in the "mozconfig" resp. passed to configure to enable the Temporal code.

Comment 12

[André Bargull [:anba]]

Attachment: WIP: Bug 1519167 - Part 1: Add methods to intl::TimeZone.

Temporal.TimeZone needs these additional methods.

Comment 13

[André Bargull [:anba]]

Attachment: WIP: Bug 1519167 - Part 5: Handle Temporal.TimeZone in IcuMemoryUsage.

Depends on D124226

Comment 14

[André Bargull [:anba]]

Attachment: WIP: Bug 1519167 - Part 7: Enable test262 Temporal tests.

Depends on D124227

Comment 15

[André Bargull [:anba]]

Notes for reviewers:

The implementation is based on the current spec text (at commit 84d1b184ac200a81a6648f2d148082f69ae0547b). There are a couple of major spec refactorings planned, so at some point the implementation will no longer match the rendered spec at https://tc39.es/proposal-temporal/. When that happens, you either have to build the rendered spec locally or use the Wayback Machine copy (https://web.archive.org/web/20230316163651/https://tc39.es/proposal-temporal).

The current implementation supports different time zones, but not different calendars, because we still plan to implement support for calendars other than the ISO-8601 calendar through ICU4X. So most changes from https://tc39.es/proposal-temporal/#sec-temporal-intl aren't yet implemented.

I'll upload the patches in small, reviewable parts, because I don't want to force anyone to review the 8000 lines for Temporal.Duration all at once. (Temporal.Duration is currently by far the largest file, the next largest is Temporal.Calendar, which has only 4000 lines.) When reviewing these small patches, you may notice that:

1. Some functions are declared in a header, even though they're currently only used in a single cpp file, so normally they should be declared as static in the cpp file. This is most likely a sign that in a later patch the function will be called from other cpp files, too. I could have declared the function as static and only later moved the declaration to the header, but that would require extra work for me when I create the review patches.
2. Similarly, sometimes there are excess #include statements. I used IWYU (include-what-you-use) during development, so the includes are (likely) correct for the final version, but when splitting the files into reviewable parts, I don't want to run IWYU for each individual patch I upload.
3. I'll try to group similar functions into a single patch, so the same kind of function doesn't need to be reviewed multiple times. This can lead to adding apparently unused function. Later patches will eventually add a caller for those functions.
4. Some optimisations are already implemented. This may seem strange for an initial implementation, which should normally strive to only implement the spec correctly, but leave optimisations for later. But the spec authors like to know if the various abstractions used in Temporal can actually be implemented efficiently.
5. Rooted/Handle uses avoid the typedef versions, see bug 1773366. For example Handle<JSObject*> instead of HandleObject.
6. Header files try to avoid using "NamespaceImports.h" typedefs, for example JS::Value instead of Value. (bug 1773721)

The review patches are generated from the implementation which is already uploaded at https://phabricator.services.mozilla.com/D124226.

When during review there are any change requests for (mostly) stylistic issues, I'd like to fix those issues after the complete patches have been reviewed, because the same kind of stylistic issues will probably appear in other patches, too. And it probably makes sense to handle all code style issues at once.

Comment 16

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 1: Add config for Temporal. r=#spidermonkey-reviewers!

Add a new configure option "--with-temporal-api" to enable the Temporal API.

This option is off by default, because the Temporal spec is still work-in-progress.

Time zone and calendrical operations will require ICU, so we don't support
Temporal when "--without-intl-api" is specified.

Comment 17

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 2: Add source files for Temporal types. r=#spidermonkey-reviewers!

Add the source files for all Temporal types, using a blank class definition.

Depends on D174153

Comment 18

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 3: Add internal representation for Temporal types and units. r=#spidermonkey-reviewers!

Add internal representations for Temporal types.

Instant:
Represents a time since the epoch value, measured in nanoseconds. The number of
epoch nanoseconds exceeds int64_t storage, therefore it's split into a full
seconds and fractional seconds part. This representation is used so we don't
have to allocate BigInt values for any Instant value computation.

PlainDate, PlainTime, and PlainDateTime:
Representation for date-time values. The spec often passes each individual
date-time value separately, so some spec operations use nine or more
parameters. We pack date-time values into structs to avoid having functions
with excess parameters.

Duration:
Representation of a duration amount. Similar to date-time values, using a
struct avoids writing functions with excess parameters.

Also add Temporal unit enum with some helpers for conversion between types.

Depends on D174154

Comment 19

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 4: Add Temporal rounding functions. r=#spidermonkey-reviewers!

Temporal supports nine different rounding modes. This adds the implementation
for int64_t rounding, later patches will add similar functions for BigInt
values.

Depends on D174155

Comment 20

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 5: Add functions to convert to internal representation. r=#spidermonkey-reviewers!

Add functions to convert Temporal objects to their internal representation.

Depends on D174156

Comment 21

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 6: Add class to represent possibly wrapped objects. r=#spidermonkey-reviewers!

Abstraction to work with possibly wrapped objects in a type-safe way. Strictly
speaking the class name should be "PossiblyWrapped", but that's a bit too long,
so it was shortened to just "Wrapped".

Useful when the Temporal spec uses different code paths for built-in objects.
For example when Wrapped<DurationObject*> to represent a possibly wrapped
DurationObject*. Alternatives currently used in SpiderMonkey code are:

1. Unwrapped DurationObject* with a scary name to document that the object is
   possibly from a different compartment.
   For example unsafeTypedArrayCrossCompartment and DangerouslyUnwrapTypedArray
   in SelfHosting.cpp.
2. JSObject* with a descriptive name to document the object is a DurationObject*.
   For example: Callers to UnwrapAndDowncastObject or similar functions.

Wrapped<DurationObject*> avoids passing unwrapped objects around, so we can
more easily avoid compartment mismatches. And because it includes the concrete
JSObject subclass as part of its type, it's more easy to see which actual
JSObject class is used. And we can also use the C++ type system more
effectively.

For example:

void consumer(JSObject* maybeWrappedInstant);

// Type only part of the variable name.
JSObject* maybeWrappedDuration = producer();

// Compiles, but will crash at runtime.
consumer(maybeWrappedDuration);

Compare to:

void consumer(Wrapped<InstantObject*> maybeWrappedInstant);

// Type part of the variable type.
Wrapped<DurationObject*> maybeWrappedDuration = producer();

// Doesn't even compile.
consumer(maybeWrappedDuration);

There's one downside of this approach: This is yet another set of tools to work
with possibly wrapped objects, in addition to the already existing functions:

• JSObject::{canUnwrapAs, unwrapAs, maybeUnwrapAs, maybeUnwrapIf}()
• UnwrapAndDowncastObject and friends
• Direct calls to either UncheckedUnwrap or CheckedUnwrapStatic
• etc.

Depends on D174157

Comment 22

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 7: Add helper functions to validate and convert Instant values to and from BigInts. r=#spidermonkey-reviewers!

Adds the following functions:

js::temporal::IsValidEpochNanoseconds:

• Implementation of the IsValidEpochNanoseconds spec abstract operation.
• Implemented for Instant and BigInt values.
• The naive implementation to compare a BigInt against a constant BigInt
  requires to allocate the constant, which is (a) slow and (b) makes the
  operation fallible when the allocation fails. Instead implement it through
  direct comparison of the BigInt digits.

js::temporal::IsValidInstantDifference:

• Functions to validate an Instant or BigInt value doesn't exceed the
  maximum difference between two valid epoch nanoseconds values.

js::temporal::ToInstant and js::temporal::ToInstantDifference:

• Create an Instant value from a BigInt.
• More BigInt::Digit surgery to make the operation infallible and performant.

js::temporal::ToEpochNanoseconds and js::temporal::ToEpochDifferenceNanoseconds:

• Create a BigInt from an Instant value.
• Last BigInt::Digit fun until the implementation of the AddInstant
  abstract operation.

Depends on D174158

Comment 23

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 8: Implement Temporal.Instant constructor and some simple Instant methods. r=#spidermonkey-reviewers!

The Temporal.Instant constructor and some Temporal.Instant methods are
ready to be implemented.

Depends on D174159

Comment 24

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 9: Implement Temporal.Calendar constructor and some simple methods. r=#spidermonkey-reviewers!

Depends on D174160

Comment 25

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 10: Implement Temporal.Duration constructor and some simple methods. r=#spidermonkey-reviewers!

Depends on D174161

Comment 26

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 11: Add functions to validate date-time values. r=#spidermonkey-reviewers!

Most functions are present two times: The version which takes double inputs is
called for user-inputs (double for the JS Number type). The version which
takes PlainDate, PlainTime, or PlainDateTime is used for internally created
objects.

Calendar.cpp:

• The static ISODaysInMonth is constexpr in preparation for a later patch.

Depends on D174162

Comment 27

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 12: Start implementing the Temporal parser. r=#spidermonkey-reviewers!

The Temporal API supports parsing strings into various Temporal types. We
start with parsing calendar strings, because that's a prerequisite for other
Temporal constructors like Temporal.PlainDate.

The parser is split into two classes:

1. StringReader provides access to the underlying characters. The
   characters are wrapped into a mozilla::Span for extra safety, any
   out-of-bounds access will crash.
2. TemporalParser is the actual parser implementation. The interface is
   Rust-like where all fallible methods return a mozilla::Result object.
   Parse errors are stored in ParserError, which is a simple wrapper around
   JSErrNum. ParserError implements mozilla::detail::UnusedZero to ensure
   efficient packing in the mozilla::Result object.

Depends on D174267

Comment 28

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 13: Implement date-time parsing. r=#spidermonkey-reviewers!

Implements parsing the TemporalDateTimeString parse goal.

Depends on D174268

Comment 29

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 14: Implement instant parsing. r=#spidermonkey-reviewers!

Implements parsing the TemporalInstantString parse goal.

Depends on D174269

Comment 30

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 15: Implement time parsing. r=#spidermonkey-reviewers!

Implements parsing the TemporalTimeString parse goal.

Depends on D174270

Comment 31

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 16: Implement zoned-date-time parsing. r=#spidermonkey-reviewers!

Implements parsing the TemporalZonedDateTimeString parse goal.

Depends on D174271

Comment 32

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 17: Implement month-day parsing. r=#spidermonkey-reviewers!

Implements parsing the TemporalMonthDayString parse goal.

Depends on D174272

Comment 33

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 18: Implement year-month parsing. r=#spidermonkey-reviewers!

Implements parsing the TemporalYearMonthString parse goal.

Depends on D174273

Comment 34

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 19: Implement abstract operations to retrieve Temporal.Calendar objects. r=#spidermonkey-reviewers!

Implements the following abstract operations:

• GetISO8601Calendar
• ToTemporalCalendar
• ToTemporalCalendarWithISODefault
• GetTemporalCalendarWithISODefault

Note: The PlainTimeObject::getOrCreateCalendar() is used to lazily create the
calendar object of a Temporal.PlainTime object. This method will likely be
removed when the spec is changed to represent built-in calendars as strings.

Depends on D174274

Comment 35

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 20: Implement constructors for Temporal.PlainX objects. r=#spidermonkey-reviewers!

Implements constructors for Temporal.Plain{Date,DateTime,Time,MonthDay,YearMonth}.

Additionally implements the CreateTemporalX operations for later patches.

Depends on D174275

Comment 36

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 21: Implement time zone validation and canonicalisation. r=#spidermonkey-reviewers!

This actually just ports the canonicalisation code from builtin/intl/DateTimeFormat.js
to C++. The self-hosted code can be removed after Temporal is enabled by default.

Depends on D174276

Comment 37

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 22: Implement Temporal.TimeZone constructor. r=#spidermonkey-reviewers!

Implement the Temporal.TimeZone constructor and the corresponding
CreateTemporalTimeZone abstract operations.

Depends on D174277

Comment 38

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 23: Implement abstract operations to retrieve Temporal.TimeZone objects. r=#spidermonkey-reviewers!

Implements the ToTemporalTimeZone abstract operation, which is needed to
implement the Temporal.ZonedDateTime constructor.

Depends on D174278

Comment 39

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 24: Implement Temporal.ZonedDateTime constructor. r=#spidermonkey-reviewers!

Implement the Temporal.ZonedDateTime constructor and the corresponding
CreateTemporalZonedDateTime abstract operation.

Depends on D174279

Comment 40

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 25: Implement ISO-8601 calendar methods. r=#spidermonkey-reviewers!

Implement the various ISO-8601 calendar methods and abstract operations.

Depends on D174280

Comment 41

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 26: Implement ToTemporalInstant abstract operation. r=#spidermonkey-reviewers!

Depends on D174282

Comment 42

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 27: Implement Temporal.Instant.{from,compare} and Temporal.Instant.prototype.equals . r=#spidermonkey-reviewers!

These three functions are now trivial to implement after the last part added ToTemporalInstant.

Depends on D174283

Comment 43

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 28: Implement Temporal.Instant.prototype.toZonedDateTime{ISO}. r=#spidermonkey-reviewers!

Depends on D174284

Comment 44

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 29: Implement Temporal.TimeZone.from and Temporal.TimeZone.prototype.toString. r=#spidermonkey-reviewers!

And additionally implement toJSON, id getter, and @@toString tag.

Depends on D174285

Comment 45

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 30: Add methods to retrieve time zone transitions and utf-offsets from local time. r=#spidermonkey-reviewers!

The GetNamedTimeZoneEpochNanoseconds, GetNamedTimeZoneNextTransition, and
GetNamedTimeZonePreviousTransition abstract operations from the Temporal API
proposal require these additional methods.

Depends on D174286

Comment 46

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 31: Implement Temporal.TimeZone.prototype.get{Next,Previous}Transition. r=#spidermonkey-reviewers!

Depends on D174287

Comment 47

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 32: Implement Temporal.TimeZone.prototype.getOffset{Nanoseconds,String}For. r=#spidermonkey-reviewers!

Depends on D174288

Comment 48

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 33: Implement Temporal.PlainX.prototype.{getISOFields,valueOf}. r=#spidermonkey-reviewers!

Depends on D174289

Comment 49

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 34: Implement Temporal.Plain{Date,MonthDay,YearMonth}.prototype.to{String,LocaleString,JSON}. r=#spidermonkey-reviewers!

Depends on D174393

Comment 50

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 35: Implement Temporal.Calendar.prototype.{fields,mergeFields}. r=#spidermonkey-reviewers!

Also implement the "CalendarMergeFields" abstract operation with a fast-path
when the built-in Temporal.Calendar.prototype.mergeFields is called.

The "CalendarFields" abstract operation needs some additional setup, so it'll
be implemented later.

Depends on D174394

Comment 51

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 36: Implement Temporal.Calendar.from. r=#spidermonkey-reviewers!

Depends on D174395

Comment 52

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 37: Implement CalendarFields abstract operation. r=#spidermonkey-reviewers!

Including a fast-path when the built-in Temporal.Calendar.prototype.fields
function is called.

Depends on D174396

Comment 53

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 38: Implement PrepareTemporalFields abstract operation. r=#spidermonkey-reviewers!

Later patches will add more PrepareTemporalFields implementations, suitable
for each different call site.

Depends on D174397

Comment 54

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 39: Implement Temporal.Calendar.prototype.dateFromFields. r=#spidermonkey-reviewers!

Implement Temporal.Calendar.prototype.dateFromFields and the corresponding
"CalendarDateFromFields" abstract operation.

Depends on D174398

Comment 55

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 40: Implement Temporal.Calendar.prototype.{yearMonth,monthDay}FromFields. r=#spidermonkey-reviewers!

And implement the corresponding "CalendarYearMonthFromFields" and
"CalendarMonthDayFromFields" abstract operations.

Depends on D174399

Comment 56

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 41: Implement Temporal.TimeZone.prototype.getPlainDateTimeFor. r=#spidermonkey-reviewers!

Including any abstract operation which is called from "GetPlainDateTimeFor".

BalanceISODateNew implements the "BalanceISODate" abstract operation according
to the current spec text. The current definition doesn't correctly handle large
years values, though. Therefore we still have to implement it based on the
definition from an old spec revision.

Depends on D174400

Comment 57

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 42: Implement Temporal.PlainDate.from. r=#spidermonkey-reviewers!

And the corresponding ToTemporalDate abstract operation.

Depends on D174401

Comment 58

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 43: Implement Temporal.PlainMonthDay.from. r=#spidermonkey-reviewers!

And the corresponding ToTemporalMonthDay abstract operation.

Depends on D174402

Comment 59

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 44: Implement Temporal.PlainYearMonth.from. r=#spidermonkey-reviewers!

And the corresponding ToTemporalYearMonth abstract operation.

Depends on D174403

Comment 60

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 45: Implement Temporal.PlainTime.from. r=#spidermonkey-reviewers!

And the corresponding ToTemporalTime abstract operation.

Depends on D174404

Comment 61

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 46: Implement Temporal.PlainDateTime.from. r=#spidermonkey-reviewers!

And the corresponding ToTemporalDateTime abstract operation.

Depends on D174405

Comment 62

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 47: Implement Temporal.TimeZone.prototype.getPossibleInstantsFor. r=#spidermonkey-reviewers!

Depends on D174406

Comment 63

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 48: Implement Temporal.PlainDate.prototype.toPlain{DateTime,YearMonth,MonthDay}. r=#spidermonkey-reviewers!

Depends on D174407

Comment 64

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 49: Implement Temporal.PlainDateTime.prototype.toPlain{Date,Time,YearMonth,MonthDay}. r=#spidermonkey-reviewers!

Depends on D174408

Comment 65

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 50: Implement Temporal.PlainTime.prototype.toPlainDateTime. r=#spidermonkey-reviewers!

Depends on D174409

Comment 66

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 51: Implement Temporal.PlainYearMonth.prototype.toPlainDate. r=#spidermonkey-reviewers!

Depends on D174410

Comment 67

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 52: Implement Temporal.PlainMonthDay.prototype.toPlainDate. r=#spidermonkey-reviewers!

Depends on D174411

Comment 68

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 53: Implement the getter properties for Temporal.PlainX objects. r=#spidermonkey-reviewers!

And additionally the @@toStringTag property.

Depends on D174412

Comment 69

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 54: Implement Temporal.PlainX.{compare,prototype.equals} methods. r=#spidermonkey-reviewers!

Depends on D174413

Comment 70

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 55: Implement Temporal.PlainX.with methods. r=#spidermonkey-reviewers!

Temporal.PlainMonthDay is now completely implemented!

Depends on D174414

Comment 71

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 56: Implement Temporal.Plain{Date,DateTime}.withCalendar. r=#spidermonkey-reviewers!

Depends on D174415

Comment 72

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 57: Implement Temporal.PlainDateTime.prototype.withPlain{Date,Time}. r=#spidermonkey-reviewers!

Depends on D174416

Comment 73

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 58: Add GetTemporalUnit, ToTemporalRoundingMode, ToFractionalSecondDigits, ToSecondsStringPrecision . r=#spidermonkey-reviewers!

Abstract operations needed for the next patch.

Depends on D174417

Comment 74

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 59: Implement Temporal.PlainTime.prototype.to{String,LocaleString,JSON}. r=#spidermonkey-reviewers!

The spec operation "RoundTime" rounds the mathematical value quantity to the
input increment. To implement this operation without loss of precision, we
can't use C++ double for the quantity variable, but instead need to
interpret the mathematical value, i.e. a real number ℝ, as a rational number ℚ.

For example when unit="microseconds":

9.a Let quantity be nanosecond × 10^-3 + microsecond.
...
11. Let result be RoundNumberToIncrement(quantity, increment, roundingMode).

Where RoundNumberToIncrement is spec'ed as:

1. Let quotient be x / increment.
   2-8. Let rounded be RoundOp(quotient).
2. Return rounded × increment.

We compute quantity as the rational number (nanosecond + microsecond × 10^3) / (10^3),
i.e. we scale it to nanoseconds. The quotient is then computed with
x = (nanosecond + microsecond × 10^3) / (10^3):

quotient

= x / increment
= ((nanosecond + microsecond × 10^3) / (10^3)) / increment
= (nanosecond + microsecond × 10^3) / (increment × 10^3)

The same approach will be used in later patches when "RoundDuration" gets
implemented. The RoundDuration implementation has code comments explaining this
approach, that's why there's a comment in the RoundTime code which points to
RoundDuration.

Depends on D174418

Comment 75

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 60: Implement Temporal.PlainTime.prototype.round. r=#spidermonkey-reviewers!

Depends on D174419

Comment 76

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 61: Implement Temporal.PlainDateTime.p.to{String,LocaleString,JSON} and PDT.p.round. r=#spidermonkey-reviewers!

Depends on D174420

Comment 77

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 62: Implement Temporal.Instant.p.to{String,LocaleString,JSON} and Instant.p.round. r=#spidermonkey-reviewers!

The Divide function implements the different rounding modes which were already
implemented for int64_t in "TemporalRoundingMode.h".

BigInt::divmod computes the quotient and remainder of a BigInt division in a
single operation. The implementation is based on the existing BigInt::div and
BigInt::mod methods.

Depends on D174421

Comment 78

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 63: Implement Temporal.Now. r=#spidermonkey-reviewers!

Also add the missing Temporal[@@toStringTag] property.

Depends on D174422

Comment 79

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 64: Implement Temporal.ZonedDateTime.prototype.to{String,LocaleString,JSON} and ZDT.p.valueOf. r=#spidermonkey-reviewers!

Depends on D174423

Comment 80

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 65: Implement ZDT.p.to{Instant,Plain{Date,Time,DateTime,YearMonth,MonthDay}} and ZDT.p.getISOFields. r=#spidermonkey-reviewers!

Depends on D174424

Comment 81

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 66: Implement ZonedDateTime.p.with{Calendar,TimeZone}. r=#spidermonkey-reviewers!

Depends on D174425

Comment 82

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 67: Implement most Temporal.ZonedDateTime.prototype accessor properties. r=#spidermonkey-reviewers!

Implement all accessor properties except for hoursInDay, because that one
requires more Temporal.Duration support, which hasn't landed yet.

Depends on D174426

Comment 83

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 68: Implement Temporal.Duration.from and Temporal.Duration.prototype.with. r=#spidermonkey-reviewers!

Temporal.Duration.from calls the "ToTemporalDuration{Record}" abstract
operation, which in turn calls "ParseTemporalDurationString". So we need to
finish the last missing bits of the Temporal parser to add support for parsing
duration strings. The duration type is placed last in a duration string
component, for example when parsing the digits 123 in the string "P123Y",
we need to parse until the "Y" to know that 123 is the years part. This
makes it a bit different when compared to date-time parsing.

js::temporal::ParseTemporalDurationString computes the fractional parts
using int64_t variables to ensure there's no loss of precision when
compared to using double variables.

Depends on D174427

Comment 84

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 69: Implement Temporal.Calendar.prototype.dateUntil. r=#spidermonkey-reviewers!

And the correspoding CalendarDateUntil abstract operation.

Depends on D174428

Comment 85

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 70: Implement Temporal.PlainTime.prototype.{add,subtract}. r=#spidermonkey-reviewers!

Depends on D174429

Comment 86

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 71: Implement Temporal.Instant.prototype.{add,subtract}. r=#spidermonkey-reviewers!

In the spec, duration fields are stored as mathematical values. The "AddInstant"
operation first converts the mathematical values into BigInts and then adds
them together. We can avoid the extra BigInt allocations as follows:

1. Any hours, minutes, seconds, or milliseconds component which isn't
   equivalent to an int64_t (tested with mozilla::NumberEqualsInt64)
   will make the result overflow the maximum instant value 8.64 × 10^21.
2. The maximum instant difference in microseconds resolution doesn't fit into
   an int64_t, so we can't use the same approach. The absolute value does fit
   into an uint64_t, though. There's no mozilla::NumberEqualsUint64, so we
   have to perform manual range checks before converting the absolute value to
   an uint64_t.
3. Nanoseconds are more complicated, because they fit neither in int64_t nor
   in uint64_t. So we just copy the existing double-to-BigInt code from
   BigInt::createFromDouble() to convert the nanoseconds and then use the
   existing ToInstant function to convert the BigInt digits into an Instant.

Then we add the hours, minutes, and seconds to the milliseconds and convert the
result into an instant, too. If the sum is a valid instant difference value, we
add the total milliseconds to the earlier computed microseconds and nanoseconds,
check again for instant difference limits, then add that sum to the input
instant. If that result is a valid epoch instant, we're finished. Otherwise the
input duration is too large and we have to report an error.

Depends on D174430

Comment 87

[Henri Sivonen (:hsivonen) (not reading bugmail while on leave)]

(In reply to André Bargull [:anba] from comment #15)

The current implementation supports different time zones, but not different calendars, because we still plan to implement support for calendars other than the ISO-8601 calendar through ICU4X.

Do I understand correctly that the only new dependency on ICU4C APIs that is being added is calculating the previous and next time zone changes in https://phabricator.services.mozilla.com/D174287 ?

Do I understand correctly that the ISO-8601 calendar is algorithmic enough that it is being implemented within the Temporal code itself without delegation to either ICU4C or ICU4X?

Is there a tracker for how well ICU4X covers the non-ISO-8601 calendar needs of Temporal?

Comment 88

[André Bargull [:anba]]

(In reply to Henri Sivonen (:hsivonen) from comment #87)

Do I understand correctly that the only new dependency on ICU4C APIs that is being added is calculating the previous and next time zone changes in https://phabricator.services.mozilla.com/D174287 ?

Yes, that's currently the only new dependency on ICU4C APIs.

Do I understand correctly that the ISO-8601 calendar is algorithmic enough that it is being implemented within the Temporal code itself without delegation to either ICU4C or ICU4X?

Correct. ISO-8601 calendar algorithms are actually even defined in the Temporal spec text, for example ToISODayOfYear or ToISOWeekOfYear.

Is there a tracker for how well ICU4X covers the non-ISO-8601 calendar needs of Temporal?

I haven't yet looked into the ECMA-402 extensions for Temporal, which is where support for calendars other than ISO-8601 is defined. So I can't really tell which functionality will be required. And I also don't know how well ICU4X supports different calendars. This issue makes it sound like there's still some major work to be done, though.

Comment 89

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 72: Implement BalanceDuration abstract operation. r=#spidermonkey-reviewers!

Implements the "BalanceDuration" abstract operation when the relativeTo
argument isn't present.

Everything is essentially implemented two times: Once for the normal case, when
the operation can be implemented using int64_t value. And then another time
when we need to use BigInts to ensure there's no loss of precision because the
spec actually defines the operation to work on mathematical values.

Depends on D174431

Comment 90

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 73: Implement RoundDuration abstract operation. r=#spidermonkey-reviewers!

Implements the "RoundDuration" abstract operation when the relativeTo
argument isn't present.

As with previous parts, we need to make sure to compute the correct results
without any floating-point loss of precision, because the spec is defined in
terms of exact mathematical values. That means fractionalSeconds is actually
a real number (ℝ), so we need to convert it into the rational number (ℚ)
totalNanoseconds / unit, where totalNanoseconds and unit are both
integers. totalNanoseconds should fit into int64_t in the normal case, so
we optimise for that case. When totalNanoseconds doesn't fit into int64_t,
we need to compute everything using BigInt values.

I don't know if TruncateNumber actually always computes the correct result
or if the result is incorrect by 1 ULP when compared to the exact result. But
this part of the spec is probably going to change when duration fields are
restricted to smaller values, so an in-depth numerical analysis isn't yet
needed. :-)

Also adds another Divide function for the case when both the dividend and
the divisor are BigInt values.

Depends on D174585

Comment 91

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 74: Implement Temporal.PlainTime.prototype.{since,until}. r=#spidermonkey-reviewers!

Implement the last missing PlainTime.prototype methods now that RoundDuration
is available (Part 73).

Adds specialised versions of "BalanceDuration", "TotalDurationNanoseconds", and
"DurationSign" which can be implemented more efficiently when compared to the
already existing versions.

Depends on D174586

Comment 92

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 75: Implement Temporal.Calendar.prototype.dateAdd. r=#spidermonkey-reviewers!

And the corresponding "CalendarDateAdd" abstract operation.

Temporal.Calendar.prototype.dateAdd depends on BalanceDuration from part 72.

Depends on D174587

Comment 93

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 76: Implement Temporal.PlainDate.prototype.{add,subtract}. r=#spidermonkey-reviewers!

Can be implemented after adding CalendarDateAdd in part 75.

Depends on D174589

Comment 94

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 77: Implement Temporal.PlainDateTime.prototype.{add,subtract}. r=#spidermonkey-reviewers!

Another set of functions which depend on CalendarDateAdd from part 75.

And again extra complexity to use BigInts when we have to ensure no loss of
precision occurs.

Depends on D174590

Comment 95

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 78: Implement Temporal.TimeZone.prototype.getInstantFor. r=#spidermonkey-reviewers!

More functionality unblocked now that CalendarDateAdd is available.

Depends on D174591

Comment 96

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 79: Implement Temporal.PlainYearMonth.prototype.{add,subtract}. r=#spidermonkey-reviewers!

Also required CalendarDateAdd so it can be implemented.

Depends on D174592

Comment 97

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 80: Implement Temporal.Plain{DateTime,Date,Time}.prototype.toZonedDateTime. r=#spidermonkey-reviewers!

We can now implement these functions after part 78 added "GetInstantFor".

Depends on D174593

Comment 98

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 81: Implement Temporal.Instant.prototype.{since,until}. r=#spidermonkey-reviewers!

Depends on D174594

Comment 99

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 82: Implement Temporal.ZonedDateTime.prototype.{hoursInDay,startOfDay}. r=#spidermonkey-reviewers!

Depends on D174595

Comment 100

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 83: Implement Temporal.ZonedDateTime.prototype.{add,subtract}. r=#spidermonkey-reviewers!

Depends on D174596

Comment 101

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 84: Implement Temporal.ZonedDateTime.prototype.withPlain{Date,Time}. r=#spidermonkey-reviewers!

Depends on D174597

Comment 102

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 85: Implement Temporal.ZonedDateTime.{compare,from,prototype.{equals,with}}. r=#spidermonkey-reviewers!

All four functions call "ToTemporalZonedDateTime", which in turn calls the three
previously not implemented abstract operations:

• InterpretISODateTimeOffset
• ParseTemporalZonedDateTimeString
• ToTemporalOffset

Temporal.ZonedDateTime.prototype.equals additionally calls the previously not
implemented "TimeZoneEquals" abstract operation.

Also add another "PrepareTemporalFields" implementation. This one supports the
requiredFields parameter from the spec.

The AppendSorted function has optimisations for appending a single or two
items. When the spec is more stable, we probably want to remove the version
which takes an initializer_list and directly call the optimised versions.

Depends on D174598

Comment 103

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 86: Implement Temporal.ZonedDateTime.prototype.round. r=#spidermonkey-reviewers!

Depends on D174599

Comment 104

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 87: Implement Temporal.Duration.prototype.to{String,LocaleString,JSON}. r=#spidermonkey-reviewers!

As usual some extra code to make sure everything is computed with exact precision.

Depends on D174600

Comment 105

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 88: Implement Temporal.Duration.compare. r=#spidermonkey-reviewers!

Temporal.Duration.compare requires to support the following abstract operations:

• ToRelativeTemporalObject
  • ParseTemporalRelativeToString
• CalculateOffsetShift
• UnbalanceDurationRelative
  • MoveRelativeDate
    • DaysUntil

Depends on D174601

Comment 106

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 89: Implement Temporal.Duration.prototype.{add,subtract}. r=#spidermonkey-reviewers!

Temporal.Duration.prototype.{add,subtract} calls "AddDurationToOrSubtractDurationFromDuration",
which in turn needs a few other previously unimplemented abstract operations:

AddDurationToOrSubtractDurationFromDuration:

• AddDuration
  • DifferenceZonedDateTime
    • DifferenceISODateTime
    • NanosecondsToDays
  • AddZonedDateTime

The two additional "BalanceDuration" functions are again needed to ensure the
precise result is correctly computed.

Depends on D174602

Comment 107

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 90: Implement Temporal.Duration.prototype.total. r=#spidermonkey-reviewers!

Adds another round of specialised version of previously implemented
functions.

And implements the "RoundDuration" abstract operation. The spec text for
"RoundDuration" is relatively large and we have to implement basically
everything at least two times to have a fast path for the common case and
additionally a slow path which uses BigInts when the numbers can't be stored
in double without loss of precision. Both factors lead to having to write
quite a bit of code for this feature.

Depends on D174603

Comment 108

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 91: Implement Temporal.PlainDateTime.prototype.{until,since}. r=#spidermonkey-reviewers!

Part 90 added support for "RoundDuration", so now we can finally implement the
last missing Temporal.PlainDateTime functions.

Depends on D174604

Comment 109

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 92: Implement Temporal.PlainDate.prototype.{until,since}. r=#spidermonkey-reviewers!

Part 90 added support for "RoundDuration", so now we can finally implement the
last missing Temporal.PlainDate functions.

Depends on D174605

Comment 110

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 93: Implement Temporal.ZonedDateTime.prototype.{until,since}. r=#spidermonkey-reviewers!

Part 90 added support for "RoundDuration", so now we can finally implement the
last missing Temporal.ZonedDateTime functions.

Depends on D174606

Comment 111

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 94: Implement Temporal.PlainYearMonth.prototype.{until,since}. r=#spidermonkey-reviewers!

Part 90 added support for "RoundDuration", so now we can finally implement the
last missing Temporal.PlainYearMonth functions.

Depends on D174607

Comment 112

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 95: Implement Temporal.Duration.prototype.round. r=#spidermonkey-reviewers!

The is the last function which was still missing from the main Temporal spec.

Depends on D174608

Comment 113

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 96: Add an example how to optimise calendar operations. r=#spidermonkey-reviewers!

TemporalFields.cpp contains a comment how to optimise
PlainDate.prototype.toPlainMonthDay. Implement the proposed optimisation to
show more concretely what needs to be done when optimising Temporal operations.

Depends on D174609

Comment 114

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 97: Support Temporal.TimeZone in IcuMemoryUsage. r=#spidermonkey-reviewers!

Update the IcuMemoryUsage Java-script to support Temporal.TimeZone.

Depends on D174616

Comment 115

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 98: Enable test262 Temporal tests. r=#spidermonkey-reviewers!

Enables the test262 Temporal tests. Test262 needs to be reimported for this to
have an effect.

Depends on D174617

Comment 116

[André Bargull [:anba]]

Attachment: Bug 1519167 - Part 99: Add a taskcluster configuration for Temporal. r=#spidermonkey-reviewers!

Temporal isn't enabled by default, so we need a separate taskcluster
configuration when we want to test it on the try-servers.

The new "temporaldebug" configuration is based on the existing "plaindebug"
configuration, but additionally sets the "--with-temporal-api" configure
argument.

Depends on D174618

Comment 117

[André Bargull [:anba]]

That's it for now. It looks like the "Phabricator Revisions" tab is limited to display no more than 100 entries, so stopping at part 99 seems like a good choice. :-)