Skip to content

Commit 8a171d1

Browse files
author
Maggie Pint
committed
initial examples for zoneddatetime and localdatetime
0 parents  commit 8a171d1

1 file changed

Lines changed: 128 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
### Temporal Proposal
2+
3+
## Champions
4+
5+
Maggie Pint
6+
7+
Brian Terlson
8+
9+
## Status
10+
11+
This proposal is currently stage 0
12+
13+
## Motivation
14+
15+
Date has been a long time pain point in ECMAScript. This proposes `temporal`, a built in module
16+
that brings a DateTime API similar to Java 8's to the ECMAScript language.
17+
18+
Because of the size of the problem domain, this proposal brings only `ZonedDateTime` and `LocalDateTime`. The remaining types - `Instant`, `DateTimeOffset`, `LocalDate`, and `LocalTime` will be left for later proposals.
19+
20+
*Similar APIs:*
21+
22+
[Java 8](https:docs.oracle.com/javase/8/docs/api/)
23+
24+
[NodaTime](http:nodatime.org/)
25+
26+
[JS-Joda](https:github.com/js-joda/js-joda)
27+
28+
## Examples
29+
30+
31+
ZonedDateTime
32+
33+
A date and a time that are bound to a time zone and a specific instant in time.
34+
35+
The first parameter is the time zone or time zone offset. It can be any of:
36+
37+
- A zone or link name from the IANA/Olson time zone database. (BCP175/RFC6557)
38+
- Ex: 'America/New_York', 'Europe/London', 'Asia/Shanghai', 'UTC'
39+
40+
- A fixed offset from UTC in ±HH:MM or ±HHMM format, with positive values are East of GMT. (ISO8601)
41+
- Ex: '-08:00', '-05:00', '+05:30', '+12:45'
42+
43+
- A fixed offset from UTC in number of minutes West of GMT (for compatibility with Date.getTimeZoneOffset()).
44+
- Ex: 480, 300, -330, -765
45+
46+
- An indicator that denotes the local time zone of the computer where the code is executing.
47+
- This can be either undefined, or the string 'SYSTEM'.
48+
49+
Note that Instant and OffsetDateTime from Noda-Time and Java 8 can be represented with this scheme
50+
without explicitly defining them as separate types.
51+
52+
### possible input parameters
53+
```
54+
var zdt = new temporal.ZonedDateTime('America/New_York', 2017, 12, 31, 23, 59);
55+
var zdt = new temporal.ZonedDateTime('America/New_York', 2017, 12, 31, 23, 59, options);
56+
var zdt = new temporal.ZonedDateTime('America/New_York', 2017, 12, 31, 23, 59, 59);
57+
var zdt = new temporal.ZonedDateTime('America/New_York', 2017, 12, 31, 23, 59, 59, options);
58+
var zdt = new temporal.ZonedDateTime('America/New_York', 2017, 12, 31, 23, 59, 59, 123);
59+
var zdt = new temporal.ZonedDateTime('America/New_York', 2017, 12, 31, 23, 59, 59, 123, options);
60+
var zdt = new temporal.ZonedDateTime('America/New_York', 2017, 12, 31, 23, 59, 59, 123, 456789);
61+
var zdt = new temporal.ZonedDateTime('America/New_York', 2017, 12, 31, 23, 59, 59, 123, 456789, options);
62+
```
63+
64+
### default options
65+
```
66+
{
67+
calendar: 'gregory' uses ECMA-402 calendar names
68+
resolver: (mapping) => ({
69+
skipped: mapping.forwardShifted(),
70+
ambiguous: mapping.firstOccurrence()
71+
})
72+
}
73+
```
74+
75+
Any resolver function that returns a ZonedDateTime is allowed.
76+
Properties on mapping are TBD
77+
78+
Built-in skipped local time resolver functions are:
79+
- forwardShifted() Shifts forward by the duration of the gap. (ex: 02:30 => 03:30)
80+
- nextValid() Uses the next valid local time. (ex: 02:30 => 03:00)
81+
- lastValid() Uses the last valid local time. (ex: 02:30 => 01:59:59.999999999)
82+
- throws() Skipped local time causes an error to be thrown.
83+
84+
Built-in ambiguous local time resolver functions are:
85+
- firstOccurrence() Chooses the first occurance of an ambiguous value. (ex: 01:30 EDT)
86+
- lastOccurrence() Chooses the last occurance of an ambiguous value. (ex: 01:30 EST)
87+
- throws() Ambiguous local time causes an error to be thrown.
88+
89+
------------------------------------------------------------------------------------------------------------------------------
90+
91+
92+
LocalDateTime
93+
94+
A date and a time without any time zone reference.
95+
The term "local" here derives from ISO-8601 §2.1.16, and means "locally applicable".
96+
In other words, local to somebody, somewhere. Does not mean local to the user or computer.
97+
98+
99+
```
100+
var ldt = new temporal.LocalDateTime(year, month, day, hours, minutes[, seconds[, millis[, nanosOfMillis]]][, options]);
101+
```
102+
### possible input parameters
103+
```
104+
var ldt = new temporal.LocalDateTime(2017, 12, 31, 23, 59);
105+
var ldt = new temporal.LocalDateTime(2017, 12, 31, 23, 59, options);
106+
var ldt = new temporal.LocalDateTime(2017, 12, 31, 23, 59, 59);
107+
var ldt = new temporal.LocalDateTime(2017, 12, 31, 23, 59, 59, options);
108+
var ldt = new temporal.LocalDateTime(2017, 12, 31, 23, 59, 59, 123);
109+
var ldt = new temporal.LocalDateTime(2017, 12, 31, 23, 59, 59, 123, options);
110+
var ldt = new temporal.LocalDateTime(2017, 12, 31, 23, 59, 59, 123, 456789);
111+
var ldt = new temporal.LocalDateTime(2017, 12, 31, 23, 59, 59, 123, 456789, options);
112+
```
113+
114+
### default options
115+
```
116+
{
117+
calendar: 'gregory' // uses ECMA-402 calendar names
118+
}
119+
```
120+
121+
------------------------------------------------------------------------------------------------------------------------------
122+
123+
Other types TBD in this module
124+
125+
LocalDate : A date without any time or time zone reference. (ex 2017-12-31)
126+
LocalTime : A time-of-day without any date or time zone reference. (ex: 17:00)
127+
Duration : A time-based amount of time, as if measured by a stopwatch. (ex: 5 minutes)
128+
Period : A date-based amount of time in the ISO8601 calendar system. (ex: 3 months)

0 commit comments

Comments
 (0)