[Proposal] Add DateTime.addYears, DateTime.addMonths, DateTime.addDays, ...

[jolleekin]

Problem

It is really inconvenient to work with Dart's DateTime because it misses some important methods for date-time manipulation. Some good examples are

1. There's no easy way to add years to a DateTime
2. There's no easy way to add months to a DateTime
3. There's no easy way to subtract years from a DateTime
4. There's no easy way to subtract months from a DateTime
5. There's no easy way to subtract a DateTime from another
6. I have to deal with low level stuff (leap years; months have different number of days) when I want to do one of the above
7. Using Duration is more cumbersome than int or num

Proposal

Given the limitations above, I propose adding the following methods to Dart's DateTime

• DateTime addDays(num value)
• DateTime addHours(num value)
• DateTime addMilliseconds(num value)
• DateTime addMinutes(num value)
• DateTime addMonths(int value)
• DateTime addSeconds(num value)
• DateTime addTicks(int value)
• DateTime addYears(int value)
• Duration subtractAnother(DateTime other)

Reference

C#'s DateTime has the following methods

• AddDays(Double)
• AddHours(Double)
• AddMilliseconds(Double)
• AddMinutes(Double)
• AddMonths(Int32)
• AddSeconds(Double)
• AddTicks(Int64)
• AddYears(Int32)
• Subtract(DateTime)

[lrhn]

I think that should be fixed with an replace method: date.repace(month: date.month + moreMonths).

You can already use the format date + new Duration(hours: 23) for everything below a month, and you can subtract two DateTime instances as date1.difference(date2).

There is a semantic problem with adding months and years in that "a month" and "a year" isn't a specific amount of time. Years vary by one day, months by up to three days. Adding "one month" to the 30th of January is ambiguous. We can do it, we just have to pick some arbitrary day between the 27th of February and the 2nd of March. That's why we haven't added month and year to Duration - they do not describe durations.

An replace method would allow you to write the actual date that you want - if you end up writing date.update(month: 2, day: 30), we have already decided how to interpret that (it's the 2nd of March, 1st of March in leap years).

(We had a CL to add the replace method, but blocked on naming: https://codereview.chromium.org/1472803003/)

[jolleekin]

In a subscription management system, recurring billing is the core. After charges of a period are collected, a task is scheduled to run next month, next quarter, next six months, next year, and so on. Without addMonths and addYears, it would be difficult to calculate the correct date for the next task.

This is how C# handles leap years and the number of days in a month

The AddMonths method calculates the resulting month and year, taking into account leap years and the number of days in a month, then adjusts the day part of the resulting DateTime object. If the resulting day is not a valid day in the resulting month, the last valid day of the resulting month is used. For example, March 31st + 1 month = April 30th, and March 31st - 1 month = February 28 for a non-leap year and February 29 for a leap year.

[lrhn]

I guess there is a reason many subscriptions work in increments of 30 days, not "months" :)

The C# choice is not a bad one. It's one choice and it may or may not be the right choice for any particular use case.
Doing something like that is definitely possible. It works when you just add a number of months or years (or days, for that matter, since daylight savings means that not all days are 24 hours).
We can't get the same effect by having an add({int year, int month, int day, int hour, int minute, int second, ...}) method instead (which I would otherwise prefer). Adding both a day and a month isn't indifferent to the order: adding 1 month and 3 days to the 26th of February can yield either 29th of March or 1st of April, depending on whether you add the day first or the month first (because you do want days to wrap over into the next month).
That's also why it doesn't work very well with Duration - it's not clear whether the difference between 24th of February and 25th of March is "29 days" or "1 month and 1 day".

[jolleekin]

My company specializes in subscription commerce, so I can confirm that subscriptions are charged mostly on a monthly or yearly basis rather than every 30 days. For example, if you sign up for a monthly charged subscription on Jan 1, you'll get charged again on Feb 1, Mar 1, and so on. From Jan 1 to Feb 1 is 31 days and from Feb 1 to Mar 1 is 28 or 29 days, but those periods are all considered as one month.

Below is my implementation of addMonths. By the way, it would be nice to add static methods isLeapYear and daysInMonth to DateTime.

const _daysInMonth = const [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];

bool isLeapYear(int value) =>
    value % 400 == 0 || (value % 4 == 0 && value % 100 != 0);

int daysInMonth(int year, int month) {
  var result = _daysInMonth[month];
  if (month == 2 && isLeapYear(year)) result++;
  return result;
}

DateTime addMonths(DateTime dt, int value) {
  var r = value % 12;
  var q = (value - r) ~/ 12;
  var newYear = dt.year + q;
  var newMonth = dt.month + r;
  if (newMonth > 12) {
    newYear++;
    newMonth -= 12;
  }
  var newDay = min(dt.day, daysInMonth(newYear, newMonth));
  if (dt.isUtc) {
    return new DateTime.utc(
        newYear,
        newMonth,
        newDay,
        dt.hour,
        dt.minute,
        dt.second,
        dt.millisecond,
        dt.microsecond);
  } else {
    return new DateTime(
        newYear,
        newMonth,
        newDay,
        dt.hour,
        dt.minute,
        dt.second,
        dt.millisecond,
        dt.microsecond);
  }
}

[johnpryan]

I'm not saying this is the way to do it, but moment.js calculates an average: https://github.com/moment/moment/blob/b8a297c1f99b3918f44dd9e3d7bd59379a876ba6/moment.js#L3997

in dart this is something like:

int monthsToDays(int months) {
  return (months * 146097 / 4800) as int;
}

[eseidelGoogle]

An internal Flutter customer (customer: fast) had an issue with their shipping app last week due to using DateTime.add(new Duration(days: 2)) not accounting for daylight savings. Having this API might have helped them avoid typing that bug in the first place.

[johnpryan]

@jolleekin @eseidelGoogle I would be happy to contribute to a 3rd party package. Maybe that's the first step to getting native SDK support.

[floitschG]

Our plan is to work on improving the libraries in Q2. This issue is on our list.