[dart-misc] Dart Language and Library Newsletter (2017-10-20)

['Florian Loitsch' via Dart Misc]

Github link for this newsletter:
https://github.com/dart-lang/sdk/blob/master/docs/newsletter/20171020.md
Earlier newsletters:
https://github.com/dart-lang/sdk/tree/master/docs/newsletter

Dart Language and Library Newsletter

Welcome to the Dart Language and Library Newsletter.
<https://github.com/dart-lang/sdk/blob/master/docs/newsletter/20171020.md#datetime>
DateTime

This week's newsletter is all about DateTime. It is shorter than usual, but
that's because there is an accompanying blog post, which contains lots of
additional related information:
https://medium.com/@florian_32814/date-time-526a4f86badb

As mentioned in the post, we are in the process of refactoring the
DateTime class
in Dart. We want to make it less error-prone for our developers to use it
for calendar-dates. Concretely, we will provide date-specific constructors
and methods:

/** * Constructs a [DateTime] instance with the current date. *
* The resulting [DateTime] is in the UTC timezone and has the time
set to 00:00. */
factory DateTime.today();

/** * Constructs a [DateTime] for the given date. * * The
resulting [DateTime] is in the UTC timezone and has the time set to
00:00. */
DateTime.date(int year, int month, int day);

/** * Returns this instance suitable for date computations. *
* The resulting DateTime is in the UTC timezone and has the time set
to 00:00. */
DateTime toDate() => new DateTime.date(year, month, day);

/** * Returns which day of the year this DateTime represents. *
* The 1st of January returns 1. */
int get dayInYear;
}

As can be seen, these constructors and members encourage the use of
DateTime for
calendar-dates in a safe way. They all default to UTC, where daylight
saving is not an issue.

We furthermore want to make it easier to adjust a given DateTime instance.
One common operation is to add a full month or day to a given date-time and
to expect that the clock time stays unchanged. Because of daylight saving
this is too cumbersome with the current DateTime API. In Dart 2.0 we plan
to refactor the existing add method (in a breaking way) to support such
operations:

/** * Returns a new [DateTime] instance with the provided
arguments added to * to [this]. * * Adding a specific number of
months will clamp the day, if the resulting * day would not be in
the same month anymore: * * ``` * new DateTime(2017, 03,
31).add(months: 1); // => 2017-04-30. * ``` * * Days are added
in such a way that the resulting time is the same (if that's *
possible). When daylight saving changes occur, adding a single [day]
might * add as little as 23, and as much as 25 hours. * * The
arguments are added in the following way: * * Compute a new
clock-time using [microseconds], [milliseconds], [seconds], *
[minutes], [hours]. At this time, days are assumed to be 24 hours long
* (without any daylight saving changes). If any unit overflows or
* underflows, the next higher unit is updated correspondingly. *
* Any over- or underflow days are added to the [days] value. * * A
new calendar date is computed by adding 12 * [years] + [months] months
* to the current calendar date. If necessary, the date is then
clamped. * * Once the date is valid, the updated [days] value is
added to the * calendar date. * * The new date and time values
are used to compute a new [DateTime] as if * the [DateTime]
constructor was called. Non-existing or ambiguous times * (because
of daylight saving changes) are resolved at this point. * * Finally,
the [duration] is added to the result of this computation. * * All
arguments may be negative. * ``` * var tomorrowTwoHoursEarlier =
date.add(days: 1, hours: -2); * var lastDayOfMonth = date.with(day:
1).add(month: 1, days: -1); * ``` */
// All values default to 0 (or a duration of 0).
DateTime add({int years, int months, int days, int hours,
int minutes, int seconds, int milliseconds, int microseconds,
Duration duration});

As can be seen by the documentation, the operation is not trivial anymore.
This is a good thing: otherwise our users would need to think about this
themselves.

While the change to DateTime.add is breaking, the work-around is simple:
dt.add(someDuration) becomes simply dt.add(duration: someDuration).

The second common operation is to replace just one property of the
instance. We will provide the with method for this purpose:

/** * Returns a [DateTime] instance with the provided arguments
replaced by the * new values. * * The returned DateTime is
constructed as if the [DateTime] constructor was * called. This
means that over and underflows are allowed. */
DateTime with({int year, int month, int day, int hour, int minute, int second,
int millisecond, int microsecond, bool isUtc});

This change requires a small modification to the Dart language, because with is
currently a keyword. It is, however, only used for mixin applications,
which means that we can make with a built-in identifier (which is allowed
to be a method-name) without complicating Dart's parser.

Finally, we will improve the DateTime.parse method to support more formats
(in particular RFC1123), and add a method to print the given date-time as
RFC1123 (the format used for cookies).

Altogether, we hope that these changes will make Dart's DateTime class less
error-prone, more convenient, and more versatile.

['Martin Läuter' via Dart Misc]

Hi all,
Florian, thanks for the detailed explanation, both on your medium blog
and this newletter, esp. for pointing at browser differences I had ignored
until now.
I am quite uncomfortable with using one type (as I understood it: DateTime)
for both timestamps and calendar calculations, being heavily influenced by
a 2015 CppCon talk

on Google's
cctz library. You might argue that you want to keep it easy for Dart
programmers, but is it worth to introduce domain type mismatches?
Concerning your description of date.add(), I find it unintuitive to add
all offsets up to the hour first, switching then to calendar calculation,
but adding the duration only in the end. So we would get different results
when adding seconds 1) as parameter to add() and 2) as a Duration, due to
clamping. Or I fail to understand the mentions of "clock-time" and "new
calendar date".
Can you clarify how non-existing and ambiguous dates/times are resolved?
Does it make a difference if you land on Samoa's 2011-12-30 or in DST's
duplicate hour from the future or from the past? Can it decide the validity
of a date in a timezone other than the client's when compiled down to
JavaScript?
Greetings,
Martin.

['Florian Loitsch' via Dart Misc]

Hi Martin,

On Sat, Oct 21, 2017 at 10:38 AM 'Martin LÀuter' via Dart Misc <

Post by 'Martin Läuter' via Dart Misc
Hi all,
Florian, thanks for the detailed explanation, both on your medium blog
and this newletter, esp. for pointing at browser differences I had ignored
until now.
DateTime) for both timestamps and calendar calculations, being heavily
influenced by a 2015 CppCon talk
http://youtu.be/2rnIHsqABfM on Google's cctz library. You
might argue that you want to keep it easy for Dart programmers, but is it
worth to introduce domain type mismatches?

I haven't yet watched the video (but will).
It's a tough choice. Our first attempt at writing DateTime was to have
three classes: Date, Time, DateTime (and thought about having
ZonedDateTime...).
We quickly realized that for almost every use case this was complete
overkill.
Yet, we knew that our simple DateTime class would make problems in corner
cases (such as the one described in the blog post). We have lots of
comments warning users about misuses.
We didn't intend DateTime to be used as a calendar class, and explicitly
didn't make it easy to use it as such.
Unfortunately we have since seen that not making it easy didn't prevent
developers from using it as such, and, even worse, because we didn't
provide useful methods, they often used in wrong.
The brazilian DST shift did break programs; adding a duration of 24 hours
did break programs, ...

Given that DateTime is already used as calendars, we decided we want to
make it easier to do the right thing. Clearly, there are still tons of
pitfalls, and developers that know about them still need to pay lots of
attention to avoid them. In many cases it might even mean to use a
third-party package. We will still keep lots of warnings in our comments to
let users know that date-time is a messy area, and that our DateTime isn't
covering all corner cases.

With the proposed change we will, at least, make UTC dates much more
prominent and thus avoid many problems.

Concerning your description of date.add(), I find it unintuitive to add

Post by 'Martin Läuter' via Dart Misc
all offsets up to the hour first, switching then to calendar calculation,
but adding the duration only in the end. So we would get different results
when adding seconds 1) as parameter to add() and 2) as a Duration, due to
clamping. Or I fail to understand the mentions of "clock-time" and "new
calendar date".

Yes. Duration is added last. It is a choice, and I don't think there isn't
a "correct" solution.
We move Duration last, exactly because it then has a different semantics.
Otherwise I can always add by `microSeconds: duration.inMicroseconds`.
There is still time (no pun intended) to change the order of how we
evaluate these methods, so we would be happy to receive more feedback.

Other languages have multiple `addX` calls, but we wanted to avoid that.
This means that we have to define a sequence. In general, we will recommend
to do `add` calls in sequence when there are possible conflicts.

Post by 'Martin Läuter' via Dart Misc
Can you clarify how non-existing and ambiguous dates/times are resolved?
Does it make a difference if you land on Samoa's 2011-12-30
<20%2011%2012%2030> or in DST's duplicate hour from the future or from
the past? Can it decide the validity of a date in a timezone other than the
client's when compiled down to JavaScript?

We will use the underlying system for these computations. This means,
unfortunately, that a Dart program can't trust to have the same behavior on
all platforms. Even Linux, Windows, and MacOs differ in their results...

As a result, I do expect that we will eventually need a similar library to
CCTZ to support more use cases (like different timezones than UTC and
Local), and to have deterministic behavior.

Thanks for the feedback.

Post by 'Martin Läuter' via Dart Misc
Greetings,
Martin.
--
For other discussions, see https://groups.google.com/a/dartlang.org/
For HOWTO questions, visit http://stackoverflow.com/tags/dart
To file a bug report or feature request, go to http://www.dartbug.com/new
---
You received this message because you are subscribed to the Google Groups
"Dart Misc" group.
To unsubscribe from this group and stop receiving emails from it, send an

[Man Hoang]

Hi Florian,

Should the following utility functions be part of the sdk?

// Returns the number of days of the month specified by [year] and [month].
int daysInMonth(int year, int month);

// Tests if [year] is a leap year.
bool isLeapYear(int year);

Post by 'Florian Loitsch' via Dart Misc
https://github.com/dart-lang/sdk/blob/master/docs/newsletter/20171020.md
https://github.com/dart-lang/sdk/tree/master/docs/newsletter
Dart Language and Library Newsletter
Welcome to the Dart Language and Library Newsletter.
<https://github.com/dart-lang/sdk/blob/master/docs/newsletter/20171020.md#datetime>
DateTime
This week's newsletter is all about DateTime. It is shorter than usual,
but that's because there is an accompanying blog post, which contains lots
As mentioned in the post, we are in the process of refactoring the
DateTime class in Dart. We want to make it less error-prone for our
developers to use it for calendar-dates. Concretely, we will provide
/** * Constructs a [DateTime] instance with the current date. * * The resulting [DateTime] is in the UTC timezone and has the time set to 00:00. */
factory DateTime.today();
/** * Constructs a [DateTime] for the given date. * * The resulting [DateTime] is in the UTC timezone and has the time set to 00:00. */
DateTime.date(int year, int month, int day);
/** * Returns this instance suitable for date computations. * * The resulting DateTime is in the UTC timezone and has the time set to 00:00. */
DateTime toDate() => new DateTime.date(year, month, day);
/** * Returns which day of the year this DateTime represents. * * The 1st of January returns 1. */
int get dayInYear;
}
As can be seen, these constructors and members encourage the use of
DateTime for calendar-dates in a safe way. They all default to UTC, where
daylight saving is not an issue.
We furthermore want to make it easier to adjust a given DateTime instance.
One common operation is to add a full month or day to a given date-time and
to expect that the clock time stays unchanged. Because of daylight saving
this is too cumbersome with the current DateTime API. In Dart 2.0 we plan
to refactor the existing add method (in a breaking way) to support such
/** * Returns a new [DateTime] instance with the provided arguments added to * to [this]. * * Adding a specific number of months will clamp the day, if the resulting * day would not be in the same month anymore: * * ``` * new DateTime(2017, 03, 31).add(months: 1); // => 2017-04-30. * ``` * * Days are added in such a way that the resulting time is the same (if that's * possible). When daylight saving changes occur, adding a single [day] might * add as little as 23, and as much as 25 hours. * * The arguments are added in the following way: * * Compute a new clock-time using [microseconds], [milliseconds], [seconds], * [minutes], [hours]. At this time, days are assumed to be 24 hours long * (without any daylight saving changes). If any unit overflows or * underflows, the next higher unit is updated correspondingly. * * Any over- or underflow days are added to the [days] value. * * A new calendar date is computed by adding 12 * [years] + [months] months * to the current calendar date. If necessary, the date is then clamped. * * Once the date is valid, the updated [days] value is added to the * calendar date. * * The new date and time values are used to compute a new [DateTime] as if * the [DateTime] constructor was called. Non-existing or ambiguous times * (because of daylight saving changes) are resolved at this point. * * Finally, the [duration] is added to the result of this computation. * * All arguments may be negative. * ``` * var tomorrowTwoHoursEarlier = date.add(days: 1, hours: -2); * var lastDayOfMonth = date.with(day: 1).add(month: 1, days: -1); * ``` */
// All values default to 0 (or a duration of 0).
DateTime add({int years, int months, int days, int hours,
int minutes, int seconds, int milliseconds, int microseconds,
Duration duration});
As can be seen by the documentation, the operation is not trivial anymore.
This is a good thing: otherwise our users would need to think about this
themselves.
dt.add(someDuration) becomes simply dt.add(duration: someDuration).
The second common operation is to replace just one property of the
/** * Returns a [DateTime] instance with the provided arguments replaced by the * new values. * * The returned DateTime is constructed as if the [DateTime] constructor was * called. This means that over and underflows are allowed. */
DateTime with({int year, int month, int day, int hour, int minute, int second,
int millisecond, int microsecond, bool isUtc});
This change requires a small modification to the Dart language, because
with is currently a keyword. It is, however, only used for mixin
applications, which means that we can make with a built-in identifier
(which is allowed to be a method-name) without complicating Dart's parser.
Finally, we will improve the DateTime.parse method to support more
formats (in particular RFC1123), and add a method to print the given
date-time as RFC1123 (the format used for cookies).
Altogether, we hope that these changes will make Dart's DateTime class
less error-prone, more convenient, and more versatile.

['Florian Loitsch' via Dart Misc]

Post by Man Hoang
Hi Florian,
Should the following utility functions be part of the sdk?
// Returns the number of days of the month specified by [year] and [month].
int daysInMonth(int year, int month);
// Tests if [year] is a leap year.
bool isLeapYear(int year);
We didn't plan to add them, but we could. Not sure it's worth it.

Please file a feature-request and we can have a look.

Post by Man Hoang

Post by 'Florian Loitsch' via Dart Misc
https://github.com/dart-lang/sdk/blob/master/docs/newsletter/20171020.md
https://github.com/dart-lang/sdk/tree/master/docs/newsletter
Dart Language and Library Newsletter
Welcome to the Dart Language and Library Newsletter.
<https://github.com/dart-lang/sdk/blob/master/docs/newsletter/20171020.md#datetime>
DateTime
This week's newsletter is all about DateTime. It is shorter than usual,
but that's because there is an accompanying blog post, which contains lots
As mentioned in the post, we are in the process of refactoring the
DateTime class in Dart. We want to make it less error-prone for our
developers to use it for calendar-dates. Concretely, we will provide
/** * Constructs a [DateTime] instance with the current date. * * The resulting [DateTime] is in the UTC timezone and has the time set to 00:00. */
factory DateTime.today();
/** * Constructs a [DateTime] for the given date. * * The resulting [DateTime] is in the UTC timezone and has the time set to 00:00. */
DateTime.date(int year, int month, int day);
/** * Returns this instance suitable for date computations. * * The resulting DateTime is in the UTC timezone and has the time set to 00:00. */
DateTime toDate() => new DateTime.date(year, month, day);
/** * Returns which day of the year this DateTime represents. * * The 1st of January returns 1. */
int get dayInYear;
}
As can be seen, these constructors and members encourage the use of
DateTime for calendar-dates in a safe way. They all default to UTC,
where daylight saving is not an issue.
We furthermore want to make it easier to adjust a given DateTime instance.
One common operation is to add a full month or day to a given date-time and
to expect that the clock time stays unchanged. Because of daylight saving
this is too cumbersome with the current DateTime API. In Dart 2.0 we
plan to refactor the existing add method (in a breaking way) to support
/** * Returns a new [DateTime] instance with the provided arguments added to * to [this]. * * Adding a specific number of months will clamp the day, if the resulting * day would not be in the same month anymore: * * ``` * new DateTime(2017, 03, 31).add(months: 1); // => 2017-04-30 <20%2017%2004%2030>. * ``` * * Days are added in such a way that the resulting time is the same (if that's * possible). When daylight saving changes occur, adding a single [day] might * add as little as 23, and as much as 25 hours. * * The arguments are added in the following way: * * Compute a new clock-time using [microseconds], [milliseconds], [seconds], * [minutes], [hours]. At this time, days are assumed to be 24 hours long * (without any daylight saving changes). If any unit overflows or * underflows, the next higher unit is updated correspondingly. * * Any over- or underflow days are added to the [days] value. * * A new calendar date is computed by adding 12 * [years] + [months] months * to the current calendar date. If necessary, the date is then clamped. * * Once the date is valid, the updated [days] value is added to the * calendar date. * * The new date and time values are used to compute a new [DateTime] as if * the [DateTime] constructor was called. Non-existing or ambiguous times * (because of daylight saving changes) are resolved at this point. * * Finally, the [duration] is added to the result of this computation. * * All arguments may be negative. * ``` * var tomorrowTwoHoursEarlier = date.add(days: 1, hours: -2); * var lastDayOfMonth = date.with(day: 1).add(month: 1, days: -1); * ``` */
// All values default to 0 (or a duration of 0).
DateTime add({int years, int months, int days, int hours,
int minutes, int seconds, int milliseconds, int microseconds,
Duration duration});
As can be seen by the documentation, the operation is not trivial
anymore. This is a good thing: otherwise our users would need to think
about this themselves.
dt.add(someDuration) becomes simply dt.add(duration: someDuration).
The second common operation is to replace just one property of the
/** * Returns a [DateTime] instance with the provided arguments replaced by the * new values. * * The returned DateTime is constructed as if the [DateTime] constructor was * called. This means that over and underflows are allowed. */
DateTime with({int year, int month, int day, int hour, int minute, int second,
int millisecond, int microsecond, bool isUtc});
This change requires a small modification to the Dart language, because
with is currently a keyword. It is, however, only used for mixin
applications, which means that we can make with a built-in identifier
(which is allowed to be a method-name) without complicating Dart's parser.
Finally, we will improve the DateTime.parse method to support more
formats (in particular RFC1123), and add a method to print the given
date-time as RFC1123 (the format used for cookies).
Altogether, we hope that these changes will make Dart's DateTime class
less error-prone, more convenient, and more versatile.

--
For other discussions, see https://groups.google.com/a/dartlang.org/
For HOWTO questions, visit http://stackoverflow.com/tags/dart
To file a bug report or feature request, go to http://www.dartbug.com/new
---
You received this message because you are subscribed to the Google Groups
"Dart Misc" group.
To unsubscribe from this group and stop receiving emails from it, send an

[tatumizer-v0.2]

@Florian: after reading your blog post, I became convinced that there
should be 2 different classes - one for UTC, another for local time.
Putting it differently: YOU convinced me there should be 2 different
classes :)
I think it directly follows from your (indeed, quite informative)
exposition.
In particular, class representing local time would be better off without
confusing methods like "add". If you want to "add" minutes or days, convert
to UTC time do your manipulations and then convert back.

The impression I got is that UTC time and local time are SO MUCH different
that hammering them into same class even feels 'artificial', and may lead
to unnecessary confusion.
(Not sure UTC time needs the notions of month, year at all. In fact, UTC
time can be just a thin wrapper around "double" value of milliseconds since
epoch. I might be mistaken though - as usual :)

['Florian Loitsch' via Dart Misc]

Post by tatumizer-v0.2
@Florian: after reading your blog post, I became convinced that there
should be 2 different classes - one for UTC, another for local time.
Putting it differently: YOU convinced me there should be 2 different
classes :)

That's unfortunate and clearly not what I intended :)

Post by tatumizer-v0.2
I think it directly follows from your (indeed, quite informative)
exposition.
In particular, class representing local time would be better off without
confusing methods like "add". If you want to "add" minutes or days, convert
to UTC time do your manipulations and then convert back.

Converting to UTC first is exactly the behavior we have with the current
"Duration" semantics: adding 3 hours in UTC is the equivalent of adding 180
minutes and that can be nicely expressed with the `Duration` object.
The problem is, that there are many use cases where this is not the case.
For example a recurrent event wants to be able to add a day (or a week),
and not 24 hours (or the equivalent for a week). There will, obviously, be
cases where even the new methods won't work: if you have a meeting at 2:30
in the morning, but the DST change makes that time invalid (or duplicated)
then there is not a lot we can do.
In short: date-time is hard. If you want to do it right, you need to be
aware of many potential issues. However, that doesn't mean that the common
case should just be blatantly wrong: adding 24 hours to go to the next day
is almost never what our users actually wanted (when there is a DST change).

Post by tatumizer-v0.2
The impression I got is that UTC time and local time are SO MUCH
different that hammering them into same class even feels 'artificial',
and may lead to unnecessary confusion.
(Not sure UTC time needs the notions of month, year at all. In fact, UTC
time can be just a thin wrapper around "double" value of milliseconds since
epoch. I might be mistaken though - as usual :)

Both, UTC and local DateTimes, are only implemented as a small wrapper on
top of a int64 (or double in JS).

Yes: you could make the case for distinct classes for UTC and local
DateTimes, but the majority of the methods are actually the same, and *all*
of them do make sense for both.
The main thing you get from having different classes, is that you could
force a type to be UTC. For example, when dealing with calendar-dates, this
could be reasonable. However, at that point we might as well add a
`CalendarDate` class, instead of using the `UTCDateTime` for it. Once you
do that, you would also want to add other classes...
We think that users that have to deal with these difficulties should use a
separate package. We would never recommend to use just the `DateTime` class
to implement a calendar (like the one from Google). It's not powerful
enough and doesn't deal with all the corner-cases.

For many other uses, the `DateTime` class is, however, perfectly fine. The
main problem we saw, was that local `DateTime`s were used as
calendar-dates. By providing primitives that force users into UTC, this
should be much less of a problem now.

Post by tatumizer-v0.2
--
For other discussions, see https://groups.google.com/a/dartlang.org/
For HOWTO questions, visit http://stackoverflow.com/tags/dart
To file a bug report or feature request, go to http://www.dartbug.com/new
---
You received this message because you are subscribed to the Google Groups
"Dart Misc" group.
To unsubscribe from this group and stop receiving emails from it, send an

[tatumizer-v0.2]

Maybe the notion of "view" can make things more intuitive? E.g. you have a
moment of time, and can establish different views on it (like: "as viewed
from timezone X").
Sure, it's just wording, but maybe for intuition, the wording is more than
"just wording"?
And yeah, it will make programming more verbose, but maybe in a bug-prone
topic like this, "more verbose" is a good thing?
It's just a humble idea for consideration :)
We saw on several occasions (while discussing various topics on this
mailing list) that the notion of "view" might be useful. Maybe now we have
another case like this?.

['Florian Loitsch' via Dart Misc]

Yes. "Views" are something that would work.
I/We have some ideas, but they aren't yet on the short list.

Post by tatumizer-v0.2
Maybe the notion of "view" can make things more intuitive? E.g. you have a
moment of time, and can establish different views on it (like: "as viewed
from timezone X").
Sure, it's just wording, but maybe for intuition, the wording is more than
"just wording"?
And yeah, it will make programming more verbose, but maybe in a bug-prone
topic like this, "more verbose" is a good thing?
It's just a humble idea for consideration :)
We saw on several occasions (while discussing various topics on this
mailing list) that the notion of "view" might be useful. Maybe now we have
another case like this?.
--
For other discussions, see https://groups.google.com/a/dartlang.org/
For HOWTO questions, visit http://stackoverflow.com/tags/dart
To file a bug report or feature request, go to http://www.dartbug.com/new
---
You received this message because you are subscribed to the Google Groups
"Dart Misc" group.
To unsubscribe from this group and stop receiving emails from it, send an

[Randal L. Schwartz]

Florian> This week's newsletter is all about DateTime. It is shorter
Florian> than usual, but that's because there is an accompanying blog
Florian> post, which contains lots of additional related information:
Florian> https://medium.com/@florian_32814/date-time-526a4f86badb

I have three interesting links in the comments for that article. Check
it out!
--
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - [phone]
<***@stonehenge.com> <URL:http://www.stonehenge.com/merlyn/>
Perl/Unix/Dart consulting, Technical writing, Comedy, etc. etc.
Still trying to think of something clever for the fourth line of this .sig