doc: converting LocalDateTime instance to ZonedDateTime

[mikeal]

What is the API for converting between the two base types?

[maggiepint]

Haven't decided, but the following mirrors Java 8 mostly and I think it works well:

var ldt = new temporal.LocalDateTime(2017, 12, 31, 23, 59);
var zoned = temporal.ZonedDateTime.of(ldt, 'America/Chicago', {
    resolver: (mapping) => ({
        skipped: mapping.forwardShifted(),
        ambiguous: mapping.firstOccurrence()
    })
}); //the options object with the resolver is optional here

var backToLocal = zoned.toLocalDateTime();

Java 8 has three methods for converting from local to zoned - .of(ltd, zoneid) which is shown, .ofLocal(ldt, zoneid, preferredOffset) which allows the user to specify a preferred offset for ambiguous times, and ofStrict(ldt, offset, zoneid) which will validate the combination of the three parameters.

I'm not sure if I want to get that deep. To me the resolver seems reasonable enough for control of ambiguous times. Use of the 'throws' mapping would create all the same functionality of the three method system, but allow it all in one.

[timrwood]

I like the withZone examples for converting a ZonedDateTime between zones, could something similar be used here?

var ldt = new temporal.LocalDateTime(2017, 12, 31, 23, 59);
var zoned = ldt.withZone('America/Chicago', {
    resolver: (mapping) => ({
        skipped: mapping.forwardShifted(),
        ambiguous: mapping.firstOccurrence()
    })
});

I like the parallel of using withoutZone to convert from ZonedDateTime to LocalDateTime, but toLocalDateTime is a bit more explicit, especially if other types are included in the proposal, like toLocalDate or toLocalTime.

[maggiepint]

@timrwood both could probably quite reasonably be implemented. They both exist in Java. Will have to think how many options we want to give people.

[mattjohnsonpint]

With the revised proposal, the types are now called PlainDateTime and ZonedInstant respectively. The conversion is as follows:

let dt = temporal.createDateTime(2017, 12, 31, 23, 59);
let zi = dt.withZone('America/Chicago', options);

options can be omitted, and is not currently spec'd - but the intention is to allow things like the resolver to be adjusted. We will eventually cover this in the spec, and describe the default resolver behavior.