shift method

[FMorschel]

I got the idea from here.

I'm going to copy lrhn comment here:

The best syntax for this behavior would be date = date.add(days: 3). That's not possible because add is taken by the Duration version, and because we cannot have both optional positional and named parameters, it can't even be changed to add([Duration? duration], {int years = 0, int months = 0, int days = 0, ...}).

So we need a new name, with the same meaning as add, but not being add. (Without being confusingly similar to add, like fold and reduce where I can never remember which is which.)

Assume we have such a name, the implementation would then be:

extension DateTimeExtensions on DateTime {
  /// Adds time units to the calendar date and/or clock time.
  ///
  /// Creates a new [DateTime] object with a calendar date offset from
  /// that of the the current oneby the provided number of years, months, and/or days,
  /// and a wall clock time offset from that of the current one by the provided
  /// hours, minutes, seconds, milliseconds and/or microseconds.
  ///
  /// The provided time units can be positive or negative, or any combination.
  /// Overflowing, say by adding more than 30 days to a any date, works like
  /// in the [DateTime] constructor.
  /// The resulting day and time must be withing the supported range for
  /// the `DateTime` class.
  ///
  /// The new `DateTime` object is an UTC time if [isUtc] is `true` ,
  /// and it is local-time if [isUtc] is `false`. 
  /// If [isUtc] is not provided, the created `DateTime` object uses the same
  /// UTC/local-time choice as the original.
  DateTime shift({int years = 0, int months = 0, int days = 0, 
      int hours = 0, int minutes = 0, int seconds = 0, int milliseconds = 0, int microseconds = 0, 
      bool? isUtc}) =>
    ((isUtc ?? this.isUtc) ? DateTime.utc : DateTime.new)(
      year + years,
      month + months,
      day + days,
      hour + hours,
      minute + minutes,
      second + seconds,
      millisecond + milliseconds,
      microsecond + microseconds,
    );
}

That looks very much like copyWith, and you can write var newDate = date.copyWith(day: date.day + days); instead of var newDate = date.shift(days: days);.

[FMorschel]

Sorry to tag you @jogboms, but this and #69 have been open for a long time, should I have made them issues?

I'd be more than happy to contribute with PRs if you agree these should enter the package.

[jogboms]

Hey @FMorschel
I missed this because I intentionally reduced my time spent on OSS.
This makes a lot of sense and a PR would be more than welcomed!!

[FMorschel]

I have one question about implementing it.

When isUtc is provided, should I first call toUtc/toLocal to a local variable inside the method and then pass the new values for the constructor, or should I call the constructor no matter what?

I guess the other option could also be a new parameter or a new method if we could name it properly.

[jogboms]

On second look, I don't see why we need the isUtc parameter. Internally we would just use copyWith which handles that.

[FMorschel]

Now that #71 has been merged, what do you intend to do with this discussion?

[jogboms]

Will be closed.