Add DateTime.replace.

sdk/lib/core/date_time.dart

 // Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.core;
 
 /**
  * An instant in time, such as July 20, 1969, 8:18pm GMT.
  *
  * Create a DateTime object by using one of the constructors
@@ skipping 349 matching lines @@
                                       {bool isUtc: false})
       : this.millisecondsSinceEpoch = millisecondsSinceEpoch,
         this.isUtc = isUtc {
     if (millisecondsSinceEpoch.abs() > _MAX_MILLISECONDS_SINCE_EPOCH) {
       throw new ArgumentError(millisecondsSinceEpoch);
     }
     if (isUtc == null) throw new ArgumentError(isUtc);
   }
 
   /**
+   * Replaces specific parts of a date or time while keeping the rest.
+   *
+   * Equivalent to createing a new `DateTime` using `new DateTime`

[sra1, 2015/11/23 21:15:14]

creating

+   * with the values specified as arguments to this method, and taking
+   * the values of the this `DateTime` object for arguments that were omitted.
+   *
+   * # Example
+   *
+   *     var dt = new DateTime(1969, 7, 20, 20, 18);
+   *     var ut = dt.replace(day: 21, hour: 17, minute: 54);
+   *     Expect.equals("1969-07-21T17:54:00.000", "$ut");
+   *
+   */
+  DateTime replace({int year,

[floitsch, 2015/11/23 19:11:01]

I think we discussed this already on another class, but I'm really not happy
with the name `replace`. It sounds way too much like an in-place operation.

Can we use `with`?

`date.with(year: 1000)` ?

[sra1, 2015/11/23 21:15:14]

I would like to see `with` too.

We should have used `with` on Uri. We still can.
What do we want to do for the next 5 classes that have this kind of 'functional
update'?

+                    int month,
+                    int day,
+                    int hour,
+                    int minute,
+                    int second,
+                    int millisecond,
+                    bool isUtc}) {
+    return new DateTime._internal(year        ?? this.year,
+                                  month       ?? this.month,
+                                  day         ?? this.day,
+                                  hour        ?? this.hour,
+                                  minute      ?? this.minute,
+                                  second      ?? this.second,
+                                  millisecond ?? this.millisecond,
+                                  isUtc       ?? this.isUtc);
+  }
+
+  /**
    * Returns true if [other] is a [DateTime] at the same moment and in the
    * same time zone (UTC or local).
    *
    *     DateTime dDayUtc   = new DateTime.utc(1944, DateTime.JUNE, 6);
    *     DateTime dDayLocal = new DateTime(1944, DateTime.JUNE, 6);
    *
    *     assert(dDayUtc.isAtSameMomentAs(dDayLocal) == false);
    *
    * See [isAtSameMomentAs] for a comparison that adjusts for time zone.
    */
@@ skipping 320 matching lines @@
    * In accordance with ISO 8601
    * a week starts with Monday, which has the value 1.
    *
    *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
    *     assert(moonLanding.weekday == 7);
    *     assert(moonLanding.weekday == DateTime.SUNDAY);
    *
    */
   external int get weekday;
 }