| OLD | NEW |
|---|
| (Empty) |
| 1 // Copyright (c) 2011, the Dart project authors. Please see the AUTHORS file | |
| 2 // for details. All rights reserved. Use of this source code is governed by a | |
| 3 // BSD-style license that can be found in the LICENSE file. | |
| 4 | |
| 5 part of dart.core; | |
| 6 | |
| 7 /** | |
| 8 * An instant in time, such as July 20, 1969, 8:18pm GMT. | |
| 9 * | |
| 10 * Create a DateTime object by using one of the constructors | |
| 11 * or by parsing a correctly formatted string, | |
| 12 * which complies with a subset of ISO 8601. | |
| 13 * Note that hours are specified between 0 and 23, | |
| 14 * as in a 24-hour clock. | |
| 15 * For example: | |
| 16 * | |
| 17 * DateTime now = new DateTime.now(); | |
| 18 * DateTime berlinWallFell = new DateTime(1989, 11, 9); | |
| 19 * DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00"); // 8:18pm | |
| 20 * | |
| 21 * A DateTime object is anchored either in the UTC time zone | |
| 22 * or in the local time zone of the current computer | |
| 23 * when the object is created. | |
| 24 * | |
| 25 * Once created, neither the value nor the time zone | |
| 26 * of a DateTime object may be changed. | |
| 27 * | |
| 28 * You can use properties to get | |
| 29 * the individual units of a DateTime object. | |
| 30 * | |
| 31 * assert(berlinWallFell.month == 11); | |
| 32 * assert(moonLanding.hour == 20); | |
| 33 * | |
| 34 * For convenience and readability, | |
| 35 * the DateTime class provides a constant for each day and month | |
| 36 * name—for example, [AUGUST] and [FRIDAY]. | |
| 37 * You can use these constants to improve code readibility: | |
| 38 * | |
| 39 * DateTime berlinWallFell = new DateTime(1989, DateTime.NOVEMBER, 9); | |
| 40 * assert(berlinWallFell.weekday == DateTime.THURSDAY); | |
| 41 * | |
| 42 * Day and month values begin at 1, and the week starts on Monday. | |
| 43 * That is, the constants [JANUARY] and [MONDAY] are both 1. | |
| 44 * | |
| 45 * ## Working with UTC and local time | |
| 46 * | |
| 47 * A DateTime object is in the local time zone | |
| 48 * unless explicitly created in the UTC time zone. | |
| 49 * | |
| 50 * DateTime dDay = new DateTime.utc(1944, 6, 6); | |
| 51 * | |
| 52 * Use [isUtc] to determine whether a DateTime object is based in UTC. | |
| 53 * Use the methods [toLocal] and [toUtc] | |
| 54 * to get the equivalent date/time value specified in the other time zone. | |
| 55 * Use [timeZoneName] to get an abbreviated name of the time zone | |
| 56 * for the DateTime object. | |
| 57 * To find the difference | |
| 58 * between UTC and the time zone of a DateTime object | |
| 59 * call [timeZoneOffset]. | |
| 60 * | |
| 61 * ## Comparing DateTime objects | |
| 62 * | |
| 63 * The DateTime class contains several handy methods, | |
| 64 * such as [isAfter], [isBefore], and [isAtSameMomentAs], | |
| 65 * for comparing DateTime objects. | |
| 66 * | |
| 67 * assert(berlinWallFell.isAfter(moonLanding) == true); | |
| 68 * assert(berlinWallFell.isBefore(moonLanding) == false); | |
| 69 * | |
| 70 * ## Using DateTime with Duration | |
| 71 * | |
| 72 * Use the [add] and [subtract] methods with a [Duration] object | |
| 73 * to create a new DateTime object based on another. | |
| 74 * For example, to find the date that is sixty days after today, write: | |
| 75 * | |
| 76 * DateTime today = new DateTime.now(); | |
| 77 * DateTime sixtyDaysFromNow = today.add(new Duration(days: 60)); | |
| 78 * | |
| 79 * To find out how much time is between two DateTime objects use | |
| 80 * [difference], which returns a [Duration] object: | |
| 81 * | |
| 82 * Duration difference = berlinWallFell.difference(moonLanding) | |
| 83 * assert(difference.inDays == 7416); | |
| 84 * | |
| 85 * The difference between two dates in different time zones | |
| 86 * is just the number of nanoseconds between the two points in time. | |
| 87 * It doesn't take calendar days into account. | |
| 88 * That means that the difference between two midnights in local time may be | |
| 89 * less than 24 hours times the number of days between them, | |
| 90 * if there is a daylight saving change in between. | |
| 91 * If the difference above is calculated using Australian local time, the | |
| 92 * difference is 7415 days and 23 hours, which is only 7415 whole days as | |
| 93 * reported by `inDays`. | |
| 94 * | |
| 95 * ## Other resources | |
| 96 * | |
| 97 * See [Duration] to represent a span of time. | |
| 98 * See [Stopwatch] to measure timespans. | |
| 99 * | |
| 100 * The DateTime class does not provide internationalization. | |
| 101 * To internationalize your code, use | |
| 102 * the [intl](http://pub.dartlang.org/packages/intl) package. | |
| 103 * | |
| 104 */ | |
| 105 class DateTime implements Comparable<DateTime> { | |
| 106 // Weekday constants that are returned by [weekday] method: | |
| 107 static const int MONDAY = 1; | |
| 108 static const int TUESDAY = 2; | |
| 109 static const int WEDNESDAY = 3; | |
| 110 static const int THURSDAY = 4; | |
| 111 static const int FRIDAY = 5; | |
| 112 static const int SATURDAY = 6; | |
| 113 static const int SUNDAY = 7; | |
| 114 static const int DAYS_PER_WEEK = 7; | |
| 115 | |
| 116 // Month constants that are returned by the [month] getter. | |
| 117 static const int JANUARY = 1; | |
| 118 static const int FEBRUARY = 2; | |
| 119 static const int MARCH = 3; | |
| 120 static const int APRIL = 4; | |
| 121 static const int MAY = 5; | |
| 122 static const int JUNE = 6; | |
| 123 static const int JULY = 7; | |
| 124 static const int AUGUST = 8; | |
| 125 static const int SEPTEMBER = 9; | |
| 126 static const int OCTOBER = 10; | |
| 127 static const int NOVEMBER = 11; | |
| 128 static const int DECEMBER = 12; | |
| 129 static const int MONTHS_PER_YEAR = 12; | |
| 130 | |
| 131 /** | |
| 132 * The value of this DateTime. | |
| 133 * | |
| 134 * The content of this field is implementation dependent. On JavaScript it is | |
| 135 * equal to [millisecondsSinceEpoch]. On the VM it is equal to | |
| 136 * [microsecondsSinceEpoch]. | |
| 137 */ | |
| 138 final int _value; | |
| 139 | |
| 140 /** | |
| 141 * True if this [DateTime] is set to UTC time. | |
| 142 * | |
| 143 * DateTime dDay = new DateTime.utc(1944, 6, 6); | |
| 144 * assert(dDay.isUtc); | |
| 145 * | |
| 146 */ | |
| 147 final bool isUtc; | |
| 148 | |
| 149 /** | |
| 150 * Constructs a [DateTime] instance specified in the local time zone. | |
| 151 * | |
| 152 * For example, | |
| 153 * to create a new DateTime object representing April 29, 2014, 6:04am: | |
| 154 * | |
| 155 * DateTime annularEclipse = new DateTime(2014, DateTime.APRIL, 29, 6, 4); | |
| 156 */ | |
| 157 DateTime(int year, | |
| 158 [int month = 1, | |
| 159 int day = 1, | |
| 160 int hour = 0, | |
| 161 int minute = 0, | |
| 162 int second = 0, | |
| 163 int millisecond = 0, | |
| 164 int microsecond = 0]) | |
| 165 : this._internal( | |
| 166 year, month, day, hour, minute, second, millisecond, microsecond, | |
| 167 false); | |
| 168 | |
| 169 /** | |
| 170 * Constructs a [DateTime] instance specified in the UTC time zone. | |
| 171 * | |
| 172 * DateTime dDay = new DateTime.utc(1944, DateTime.JUNE, 6); | |
| 173 */ | |
| 174 DateTime.utc(int year, | |
| 175 [int month = 1, | |
| 176 int day = 1, | |
| 177 int hour = 0, | |
| 178 int minute = 0, | |
| 179 int second = 0, | |
| 180 int millisecond = 0, | |
| 181 int microsecond = 0]) | |
| 182 : this._internal( | |
| 183 year, month, day, hour, minute, second, millisecond, microsecond, | |
| 184 true); | |
| 185 | |
| 186 /** | |
| 187 * Constructs a [DateTime] instance with current date and time in the | |
| 188 * local time zone. | |
| 189 * | |
| 190 * DateTime thisInstant = new DateTime.now(); | |
| 191 * | |
| 192 */ | |
| 193 DateTime.now() : this._now(); | |
| 194 | |
| 195 /** | |
| 196 * Constructs a new [DateTime] instance based on [formattedString]. | |
| 197 * | |
| 198 * Throws a [FormatException] if the input cannot be parsed. | |
| 199 * | |
| 200 * The function parses a subset of ISO 8601 | |
| 201 * which includes the subset accepted by RFC 3339. | |
| 202 * | |
| 203 * The accepted inputs are currently: | |
| 204 * | |
| 205 * * A date: A signed four-to-six digit year, two digit month and | |
| 206 * two digit day, optionally separated by `-` characters. | |
| 207 * Examples: "19700101", "-0004-12-24", "81030-04-01". | |
| 208 * * An optional time part, separated from the date by either `T` or a space. | |
| 209 * The time part is a two digit hour, | |
| 210 * then optionally a two digit minutes value, | |
| 211 * then optionally a two digit seconds value, and | |
| 212 * then optionally a '.' followed by a one-to-six digit second fraction. | |
| 213 * The minuts and seconds may be separated from the previous parts by a ':'. | |
| 214 * Examples: "12", "12:30:24.124", "123010.50". | |
| 215 * * An optional time-zone offset part, | |
| 216 * possibly separated from the previous by a space. | |
| 217 * The time zone is either 'z' or 'Z', or it is a signed two digit hour | |
| 218 * part and an optional two digit minute part. The sign must be either | |
| 219 * "+" or "-", and can not be omitted. | |
| 220 * The minutes may be separted from the hours by a ':'. | |
| 221 * Examples: "Z", "-10", "01:30", "1130". | |
| 222 * | |
| 223 * This includes the output of both [toString] and [toIso8601String], which | |
| 224 * will be parsed back into a `DateTime` object with the same time as the | |
| 225 * original. | |
| 226 * | |
| 227 * The result is always in either local time or UTC. | |
| 228 * If a time zone offset other than UTC is specified, | |
| 229 * the time is converted to the equivalent UTC time. | |
| 230 * | |
| 231 * Examples of accepted strings: | |
| 232 * | |
| 233 * * `"2012-02-27 13:27:00"` | |
| 234 * * `"2012-02-27 13:27:00.123456z"` | |
| 235 * * `"20120227 13:27:00"` | |
| 236 * * `"20120227T132700"` | |
| 237 * * `"20120227"` | |
| 238 * * `"+20120227"` | |
| 239 * * `"2012-02-27T14Z"` | |
| 240 * * `"2012-02-27T14+00:00"` | |
| 241 * * `"-123450101 00:00:00 Z"`: in the year -12345. | |
| 242 * * `"2002-02-27T14:00:00-0500"`: Same as `"2002-02-27T19:00:00Z"` | |
| 243 */ | |
| 244 // TODO(lrn): restrict incorrect values like 2003-02-29T50:70:80. | |
| 245 // Or not, that may be a breaking change. | |
| 246 static DateTime parse(String formattedString) { | |
| 247 /* | |
| 248 * date ::= yeardate time_opt timezone_opt | |
| 249 * yeardate ::= year colon_opt month colon_opt day | |
| 250 * year ::= sign_opt digit{4,6} | |
| 251 * colon_opt :: <empty> | ':' | |
| 252 * sign ::= '+' | '-' | |
| 253 * sign_opt ::= <empty> | sign | |
| 254 * month ::= digit{2} | |
| 255 * day ::= digit{2} | |
| 256 * time_opt ::= <empty> | (' ' | 'T') hour minutes_opt | |
| 257 * minutes_opt ::= <empty> | colon_opt digit{2} seconds_opt | |
| 258 * seconds_opt ::= <empty> | colon_opt digit{2} millis_opt | |
| 259 * micros_opt ::= <empty> | '.' digit{1,6} | |
| 260 * timezone_opt ::= <empty> | space_opt timezone | |
| 261 * space_opt :: ' ' | <empty> | |
| 262 * timezone ::= 'z' | 'Z' | sign digit{2} timezonemins_opt | |
| 263 * timezonemins_opt ::= <empty> | colon_opt digit{2} | |
| 264 */ | |
| 265 final RegExp re = new RegExp( | |
| 266 r'^([+-]?\d{4,6})-?(\d\d)-?(\d\d)' // Day part. | |
| 267 r'(?:[ T](\d\d)(?::?(\d\d)(?::?(\d\d)(?:\.(\d{1,6}))?)?)?' // Time part. | |
| 268 r'( ?[zZ]| ?([-+])(\d\d)(?::?(\d\d))?)?)?$'); // Timezone part. | |
| 269 | |
| 270 Match match = re.firstMatch(formattedString); | |
| 271 if (match != null) { | |
| 272 int parseIntOrZero(String matched) { | |
| 273 if (matched == null) return 0; | |
| 274 return int.parse(matched); | |
| 275 } | |
| 276 | |
| 277 // Parses fractional second digits of '.(\d{1,6})' into the combined | |
| 278 // microseconds. | |
| 279 int parseMilliAndMicroseconds(String matched) { | |
| 280 if (matched == null) return 0; | |
| 281 int length = matched.length; | |
| 282 assert(length >= 1); | |
| 283 assert(length <= 6); | |
| 284 | |
| 285 int result = 0; | |
| 286 for (int i = 0; i < 6; i++) { | |
| 287 result *= 10; | |
| 288 if (i < matched.length) { | |
| 289 result += matched.codeUnitAt(i) ^ 0x30; | |
| 290 } | |
| 291 } | |
| 292 return result; | |
| 293 } | |
| 294 | |
| 295 int years = int.parse(match[1]); | |
| 296 int month = int.parse(match[2]); | |
| 297 int day = int.parse(match[3]); | |
| 298 int hour = parseIntOrZero(match[4]); | |
| 299 int minute = parseIntOrZero(match[5]); | |
| 300 int second = parseIntOrZero(match[6]); | |
| 301 bool addOneMillisecond = false; | |
| 302 int milliAndMicroseconds = parseMilliAndMicroseconds(match[7]); | |
| 303 int millisecond = | |
| 304 milliAndMicroseconds ~/ Duration.MICROSECONDS_PER_MILLISECOND; | |
| 305 int microsecond = | |
| 306 milliAndMicroseconds.remainder(Duration.MICROSECONDS_PER_MILLISECOND); | |
| 307 bool isUtc = false; | |
| 308 if (match[8] != null) { // timezone part | |
| 309 isUtc = true; | |
| 310 if (match[9] != null) { | |
| 311 // timezone other than 'Z' and 'z'. | |
| 312 int sign = (match[9] == '-') ? -1 : 1; | |
| 313 int hourDifference = int.parse(match[10]); | |
| 314 int minuteDifference = parseIntOrZero(match[11]); | |
| 315 minuteDifference += 60 * hourDifference; | |
| 316 minute -= sign * minuteDifference; | |
| 317 } | |
| 318 } | |
| 319 int value = _brokenDownDateToValue( | |
| 320 years, month, day, hour, minute, second, millisecond, microsecond, | |
| 321 isUtc); | |
| 322 if (value == null) { | |
| 323 throw new FormatException("Time out of range", formattedString); | |
| 324 } | |
| 325 return new DateTime._withValue(value, isUtc: isUtc); | |
| 326 } else { | |
| 327 throw new FormatException("Invalid date format", formattedString); | |
| 328 } | |
| 329 } | |
| 330 | |
| 331 static const int _MAX_MILLISECONDS_SINCE_EPOCH = 8640000000000000; | |
| 332 | |
| 333 /** | |
| 334 * Constructs a new [DateTime] instance | |
| 335 * with the given [millisecondsSinceEpoch]. | |
| 336 * | |
| 337 * If [isUtc] is false then the date is in the local time zone. | |
| 338 * | |
| 339 * The constructed [DateTime] represents | |
| 340 * 1970-01-01T00:00:00Z + [millisecondsSinceEpoch] ms in the given | |
| 341 * time zone (local or UTC). | |
| 342 */ | |
| 343 external DateTime.fromMillisecondsSinceEpoch(int millisecondsSinceEpoch, | |
| 344 {bool isUtc: false}); | |
| 345 | |
| 346 /** | |
| 347 * Constructs a new [DateTime] instance | |
| 348 * with the given [microsecondsSinceEpoch]. | |
| 349 * | |
| 350 * If [isUtc] is false then the date is in the local time zone. | |
| 351 * | |
| 352 * The constructed [DateTime] represents | |
| 353 * 1970-01-01T00:00:00Z + [microsecondsSinceEpoch] us in the given | |
| 354 * time zone (local or UTC). | |
| 355 */ | |
| 356 external DateTime.fromMicrosecondsSinceEpoch(int microsecondsSinceEpoch, | |
| 357 {bool isUtc: false}); | |
| 358 | |
| 359 /** | |
| 360 * Constructs a new [DateTime] instance with the given value. | |
| 361 * | |
| 362 * If [isUtc] is false then the date is in the local time zone. | |
| 363 */ | |
| 364 DateTime._withValue(this._value, {this.isUtc}) { | |
| 365 if (millisecondsSinceEpoch.abs() > _MAX_MILLISECONDS_SINCE_EPOCH || | |
| 366 (millisecondsSinceEpoch.abs() == _MAX_MILLISECONDS_SINCE_EPOCH && | |
| 367 microsecond != 0)) { | |
| 368 throw new ArgumentError(millisecondsSinceEpoch); | |
| 369 } | |
| 370 if (isUtc == null) throw new ArgumentError(isUtc); | |
| 371 } | |
| 372 | |
| 373 /** | |
| 374 * Returns true if [other] is a [DateTime] at the same moment and in the | |
| 375 * same time zone (UTC or local). | |
| 376 * | |
| 377 * DateTime dDayUtc = new DateTime.utc(1944, DateTime.JUNE, 6); | |
| 378 * DateTime dDayLocal = new DateTime(1944, DateTime.JUNE, 6); | |
| 379 * | |
| 380 * assert(dDayUtc.isAtSameMomentAs(dDayLocal) == false); | |
| 381 * | |
| 382 * See [isAtSameMomentAs] for a comparison that adjusts for time zone. | |
| 383 */ | |
| 384 bool operator ==(other) { | |
| 385 if (!(other is DateTime)) return false; | |
| 386 return (_value == other._value && isUtc == other.isUtc); | |
| 387 } | |
| 388 | |
| 389 /** | |
| 390 * Returns true if [this] occurs before [other]. | |
| 391 * | |
| 392 * The comparison is independent | |
| 393 * of whether the time is in UTC or in the local time zone. | |
| 394 * | |
| 395 * DateTime berlinWallFell = new DateTime(1989, 11, 9); | |
| 396 * DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00"); | |
| 397 * | |
| 398 * assert(berlinWallFell.isBefore(moonLanding) == false); | |
| 399 * | |
| 400 */ | |
| 401 bool isBefore(DateTime other) { | |
| 402 return _value < other._value; | |
| 403 } | |
| 404 | |
| 405 /** | |
| 406 * Returns true if [this] occurs after [other]. | |
| 407 * | |
| 408 * The comparison is independent | |
| 409 * of whether the time is in UTC or in the local time zone. | |
| 410 * | |
| 411 * DateTime berlinWallFell = new DateTime(1989, 11, 9); | |
| 412 * DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00"); | |
| 413 * | |
| 414 * assert(berlinWallFell.isAfter(moonLanding) == true); | |
| 415 * | |
| 416 */ | |
| 417 bool isAfter(DateTime other) { | |
| 418 return _value > other._value; | |
| 419 } | |
| 420 | |
| 421 /** | |
| 422 * Returns true if [this] occurs at the same moment as [other]. | |
| 423 * | |
| 424 * The comparison is independent of whether the time is in UTC or in the local | |
| 425 * time zone. | |
| 426 * | |
| 427 * DateTime berlinWallFell = new DateTime(1989, 11, 9); | |
| 428 * DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00"); | |
| 429 * | |
| 430 * assert(berlinWallFell.isAtSameMomentAs(moonLanding) == false); | |
| 431 */ | |
| 432 bool isAtSameMomentAs(DateTime other) { | |
| 433 return _value == other._value; | |
| 434 } | |
| 435 | |
| 436 /** | |
| 437 * Compares this DateTime object to [other], | |
| 438 * returning zero if the values are equal. | |
| 439 * | |
| 440 * This function returns a negative integer | |
| 441 * if this DateTime is smaller (earlier) than [other], | |
| 442 * or a positive integer if it is greater (later). | |
| 443 */ | |
| 444 int compareTo(DateTime other) => _value.compareTo(other._value); | |
| 445 | |
| 446 int get hashCode => (_value ^ (_value >> 30)) & 0x3FFFFFFF; | |
| 447 | |
| 448 /** | |
| 449 * Returns this DateTime value in the local time zone. | |
| 450 * | |
| 451 * Returns [this] if it is already in the local time zone. | |
| 452 * Otherwise this method is equivalent to: | |
| 453 * | |
| 454 * new DateTime.fromMicrosecondsSinceEpoch(microsecondsSinceEpoch, | |
| 455 * isUtc: false) | |
| 456 */ | |
| 457 DateTime toLocal() { | |
| 458 if (isUtc) { | |
| 459 return new DateTime._withValue(_value, isUtc: false); | |
| 460 } | |
| 461 return this; | |
| 462 } | |
| 463 | |
| 464 /** | |
| 465 * Returns this DateTime value in the UTC time zone. | |
| 466 * | |
| 467 * Returns [this] if it is already in UTC. | |
| 468 * Otherwise this method is equivalent to: | |
| 469 * | |
| 470 * new DateTime.fromMicrosecondsSinceEpoch(microsecondsSinceEpoch, | |
| 471 * isUtc: true) | |
| 472 */ | |
| 473 DateTime toUtc() { | |
| 474 if (isUtc) return this; | |
| 475 return new DateTime._withValue(_value, isUtc: true); | |
| 476 } | |
| 477 | |
| 478 static String _fourDigits(int n) { | |
| 479 int absN = n.abs(); | |
| 480 String sign = n < 0 ? "-" : ""; | |
| 481 if (absN >= 1000) return "$n"; | |
| 482 if (absN >= 100) return "${sign}0$absN"; | |
| 483 if (absN >= 10) return "${sign}00$absN"; | |
| 484 return "${sign}000$absN"; | |
| 485 } | |
| 486 | |
| 487 static String _sixDigits(int n) { | |
| 488 assert(n < -9999 || n > 9999); | |
| 489 int absN = n.abs(); | |
| 490 String sign = n < 0 ? "-" : "+"; | |
| 491 if (absN >= 100000) return "$sign$absN"; | |
| 492 return "${sign}0$absN"; | |
| 493 } | |
| 494 | |
| 495 static String _threeDigits(int n) { | |
| 496 if (n >= 100) return "${n}"; | |
| 497 if (n >= 10) return "0${n}"; | |
| 498 return "00${n}"; | |
| 499 } | |
| 500 | |
| 501 static String _twoDigits(int n) { | |
| 502 if (n >= 10) return "${n}"; | |
| 503 return "0${n}"; | |
| 504 } | |
| 505 | |
| 506 /** | |
| 507 * Returns a human-readable string for this instance. | |
| 508 * | |
| 509 * The returned string is constructed for the time zone of this instance. | |
| 510 * The `toString()` method provides a simply formatted string. | |
| 511 * It does not support internationalized strings. | |
| 512 * Use the [intl](http://pub.dartlang.org/packages/intl) package | |
| 513 * at the pub shared packages repo. | |
| 514 * | |
| 515 * The resulting string can be parsed back using [parse]. | |
| 516 */ | |
| 517 String toString() { | |
| 518 String y = _fourDigits(year); | |
| 519 String m = _twoDigits(month); | |
| 520 String d = _twoDigits(day); | |
| 521 String h = _twoDigits(hour); | |
| 522 String min = _twoDigits(minute); | |
| 523 String sec = _twoDigits(second); | |
| 524 String ms = _threeDigits(millisecond); | |
| 525 String us = microsecond == 0 ? "" : _threeDigits(microsecond); | |
| 526 if (isUtc) { | |
| 527 return "$y-$m-$d $h:$min:$sec.$ms${us}Z"; | |
| 528 } else { | |
| 529 return "$y-$m-$d $h:$min:$sec.$ms$us"; | |
| 530 } | |
| 531 } | |
| 532 | |
| 533 /** | |
| 534 * Returns an ISO-8601 full-precision extended format representation. | |
| 535 * | |
| 536 * The format is `yyyy-MM-ddTHH:mm:ss.mmmuuuZ` for UTC time, and | |
| 537 * `yyyy-MM-ddTHH:mm:ss.mmmuuu` (no trailing "Z") for local/non-UTC time, | |
| 538 * where: | |
| 539 * | |
| 540 * * `yyyy` is a, possibly negative, four digit representation of the year, | |
| 541 * if the year is in the range -9999 to 9999, | |
| 542 * otherwise it is a signed six digit representation of the year. | |
| 543 * * `MM` is the month in the range 01 to 12, | |
| 544 * * `dd` is the day of the month in the range 01 to 31, | |
| 545 * * `HH` are hours in the range 00 to 23, | |
| 546 * * `mm` are minutes in the range 00 to 59, | |
| 547 * * `ss` are seconds in the range 00 to 59 (no leap seconds), | |
| 548 * * `mmm` are milliseconds in the range 000 to 999, and | |
| 549 * * `uuu` are microseconds in the range 001 to 999. If [microsecond] equals | |
| 550 * 0, then this part is omitted. | |
| 551 * | |
| 552 * The resulting string can be parsed back using [parse]. | |
| 553 */ | |
| 554 String toIso8601String() { | |
| 555 String y = (year >= -9999 && year <= 9999) ? _fourDigits(year) | |
| 556 : _sixDigits(year); | |
| 557 String m = _twoDigits(month); | |
| 558 String d = _twoDigits(day); | |
| 559 String h = _twoDigits(hour); | |
| 560 String min = _twoDigits(minute); | |
| 561 String sec = _twoDigits(second); | |
| 562 String ms = _threeDigits(millisecond); | |
| 563 String us = microsecond == 0 ? "" : _threeDigits(microsecond); | |
| 564 if (isUtc) { | |
| 565 return "$y-$m-${d}T$h:$min:$sec.$ms${us}Z"; | |
| 566 } else { | |
| 567 return "$y-$m-${d}T$h:$min:$sec.$ms$us"; | |
| 568 } | |
| 569 } | |
| 570 | |
| 571 /** | |
| 572 * Returns a new [DateTime] instance with [duration] added to [this]. | |
| 573 * | |
| 574 * DateTime today = new DateTime.now(); | |
| 575 * DateTime sixtyDaysFromNow = today.add(new Duration(days: 60)); | |
| 576 */ | |
| 577 external DateTime add(Duration duration); | |
| 578 | |
| 579 /** | |
| 580 * Returns a new [DateTime] instance with [duration] subtracted from [this]. | |
| 581 * | |
| 582 * DateTime today = new DateTime.now(); | |
| 583 * DateTime sixtyDaysAgo = today.subtract(new Duration(days: 30)); | |
| 584 * | |
| 585 * Notice that duration being subtracted is actually 30 * 24 * 60 * 60 seconds | |
| 586 * and if that crosses a daylight saving time change, the resulting `DateTime` | |
| 587 * won't have the same time of day as `today`, and may not actually hit the | |
| 588 * calendar date 30 days earlier. Be careful when working with dates in local | |
| 589 * time. | |
| 590 */ | |
| 591 external DateTime subtract(Duration duration); | |
| 592 | |
| 593 /** | |
| 594 * Returns a [Duration] with the difference between [this] and [other]. | |
| 595 * | |
| 596 * DateTime berlinWallFell = new DateTime.utc(1989, DateTime.NOVEMBER, 9); | |
| 597 * DateTime dDay = new DateTime.utc(1944, DateTime.JUNE, 6); | |
| 598 * | |
| 599 * Duration difference = berlinWallFell.difference(dDay); | |
| 600 * assert(difference.inDays == 16592); | |
| 601 * | |
| 602 * The difference is measured in seconds and fractions of seconds. | |
| 603 * The difference above counts the number of fractional seconds between | |
| 604 * midnight at the beginning of those dates. | |
| 605 * If the dates above had been in local time, not UTC, then the difference | |
| 606 * between two midnights may not be a multiple of 24 hours due to daylight | |
| 607 * saving differences. | |
| 608 * | |
| 609 * For example, in Australia, similar code using local time instead of UTC: | |
| 610 * | |
| 611 * DateTime berlinWallFell = new DateTime(1989, DateTime.NOVEMBER, 9); | |
| 612 * DateTime dDay = new DateTime(1944, DateTime.JUNE, 6); | |
| 613 * Duration difference = berlinWallFell.difference(dDay); | |
| 614 * assert(difference.inDays == 16592); | |
| 615 * | |
| 616 * will fail because the difference is actually 16591 days and 23 hours, and | |
| 617 * [Duration.inDays] only returns the number of whole days. | |
| 618 */ | |
| 619 external Duration difference(DateTime other); | |
| 620 | |
| 621 external DateTime._internal(int year, | |
| 622 int month, | |
| 623 int day, | |
| 624 int hour, | |
| 625 int minute, | |
| 626 int second, | |
| 627 int millisecond, | |
| 628 int microsecond, | |
| 629 bool isUtc); | |
| 630 | |
| 631 external DateTime._now(); | |
| 632 | |
| 633 /// Returns the time as value (millisecond or microsecond since epoch), or | |
| 634 /// null if the values are out of range. | |
| 635 external static int _brokenDownDateToValue( | |
| 636 int year, int month, int day, int hour, int minute, int second, | |
| 637 int millisecond, int microsecond, bool isUtc); | |
| 638 | |
| 639 /** | |
| 640 * The number of milliseconds since | |
| 641 * the "Unix epoch" 1970-01-01T00:00:00Z (UTC). | |
| 642 * | |
| 643 * This value is independent of the time zone. | |
| 644 * | |
| 645 * This value is at most | |
| 646 * 8,640,000,000,000,000ms (100,000,000 days) from the Unix epoch. | |
| 647 * In other words: `millisecondsSinceEpoch.abs() <= 8640000000000000`. | |
| 648 */ | |
| 649 external int get millisecondsSinceEpoch; | |
| 650 | |
| 651 /** | |
| 652 * The number of microseconds since | |
| 653 * the "Unix epoch" 1970-01-01T00:00:00Z (UTC). | |
| 654 * | |
| 655 * This value is independent of the time zone. | |
| 656 * | |
| 657 * This value is at most | |
| 658 * 8,640,000,000,000,000,000us (100,000,000 days) from the Unix epoch. | |
| 659 * In other words: `microsecondsSinceEpoch.abs() <= 8640000000000000000`. | |
| 660 * | |
| 661 * Note that this value does not fit into 53 bits (the size of a IEEE double). | |
| 662 * A JavaScript number is not able to hold this value. | |
| 663 */ | |
| 664 external int get microsecondsSinceEpoch; | |
| 665 | |
| 666 /** | |
| 667 * The abbreviated time zone name—for example, | |
| 668 * [:"CET":] or [:"CEST":]. | |
| 669 */ | |
| 670 external String get timeZoneName; | |
| 671 | |
| 672 /** | |
| 673 * The time zone offset, which | |
| 674 * is the difference between local time and UTC. | |
| 675 * | |
| 676 * The offset is positive for time zones east of UTC. | |
| 677 * | |
| 678 * Note, that JavaScript, Python and C return the difference between UTC and | |
| 679 * local time. Java, C# and Ruby return the difference between local time and | |
| 680 * UTC. | |
| 681 */ | |
| 682 external Duration get timeZoneOffset; | |
| 683 | |
| 684 /** | |
| 685 * The year. | |
| 686 * | |
| 687 * DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00"); | |
| 688 * assert(moonLanding.year == 1969); | |
| 689 */ | |
| 690 external int get year; | |
| 691 | |
| 692 /** | |
| 693 * The month [1..12]. | |
| 694 * | |
| 695 * DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00"); | |
| 696 * assert(moonLanding.month == 7); | |
| 697 * assert(moonLanding.month == DateTime.JULY); | |
| 698 */ | |
| 699 external int get month; | |
| 700 | |
| 701 /** | |
| 702 * The day of the month [1..31]. | |
| 703 * | |
| 704 * DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00"); | |
| 705 * assert(moonLanding.day == 20); | |
| 706 */ | |
| 707 external int get day; | |
| 708 | |
| 709 /** | |
| 710 * The hour of the day, expressed as in a 24-hour clock [0..23]. | |
| 711 * | |
| 712 * DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00"); | |
| 713 * assert(moonLanding.hour == 20); | |
| 714 */ | |
| 715 external int get hour; | |
| 716 | |
| 717 /** | |
| 718 * The minute [0...59]. | |
| 719 * | |
| 720 * DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00"); | |
| 721 * assert(moonLanding.minute == 18); | |
| 722 */ | |
| 723 external int get minute; | |
| 724 | |
| 725 /** | |
| 726 * The second [0...59]. | |
| 727 * | |
| 728 * DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00"); | |
| 729 * assert(moonLanding.second == 0); | |
| 730 */ | |
| 731 external int get second; | |
| 732 | |
| 733 /** | |
| 734 * The millisecond [0...999]. | |
| 735 * | |
| 736 * DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00"); | |
| 737 * assert(moonLanding.millisecond == 0); | |
| 738 */ | |
| 739 external int get millisecond; | |
| 740 | |
| 741 /** | |
| 742 * The microsecond [0...999]. | |
| 743 * | |
| 744 * DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00"); | |
| 745 * assert(moonLanding.microsecond == 0); | |
| 746 */ | |
| 747 external int get microsecond; | |
| 748 | |
| 749 /** | |
| 750 * The day of the week [MONDAY]..[SUNDAY]. | |
| 751 * | |
| 752 * In accordance with ISO 8601 | |
| 753 * a week starts with Monday, which has the value 1. | |
| 754 * | |
| 755 * DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00"); | |
| 756 * assert(moonLanding.weekday == 7); | |
| 757 * assert(moonLanding.weekday == DateTime.SUNDAY); | |
| 758 * | |
| 759 */ | |
| 760 external int get weekday; | |
| 761 } | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 2698353003:
unfork DDC's copy of most SDK libraries (Closed)
