jars/icu4j-4_8_1_1/main/classes/core/src/com/ibm/icu/util/UniversalTimeScale.java

   1 /*
   2  *********************************************************************************
   3  * Copyright (C) 2004-2010, International Business Machines Corporation and    *
   4  * others. All Rights Reserved.                                                  *
   5  *********************************************************************************
   6  *
   7  */
   8
   9 package com.ibm.icu.util;
  10
  11 import com.ibm.icu.math.BigDecimal;
  12
  13 /**
  14  * There are quite a few different conventions for binary datetime, depending on different
  15  * platforms and protocols. Some of these have severe drawbacks. For example, people using
  16  * Unix time (seconds since Jan 1, 1970, usually in a 32-bit integer)
  17  * think that they are safe until near the year 2038.
  18  * But cases can and do arise where arithmetic manipulations causes serious problems. Consider
  19  * the computation of the average of two datetimes, for example: if one calculates them with
  20  * <code>averageTime = (time1 + time2)/2</code>, there will be overflow even with dates
  21  * beginning in 2004. Moreover, even if these problems don't occur, there is the issue of
  22  * conversion back and forth between different systems.
  23  *
  24  * <p>Binary datetimes differ in a number of ways: the datatype, the unit,
  25  * and the epoch (origin). We refer to these as time scales.</p>
  26  *
  27  * <p>ICU implements a universal time scale that is similar to the
  28  * .NET framework's System.DateTime. The universal time scale is a
  29  * 64-bit integer that holds ticks since midnight, January 1st, 0001.
  30  * (One tick is 100 nanoseconds.)
  31  * Negative values are supported. This has enough range to guarantee that
  32  * calculations involving dates around the present are safe.</p>
  33  *
  34  * <p>The universal time scale always measures time according to the
  35  * proleptic Gregorian calendar. That is, the Gregorian calendar's
  36  * leap year rules are used for all times, even before 1582 when it was
  37  * introduced. (This is different from the default ICU calendar which
  38  * switches from the Julian to the Gregorian calendar in 1582.
  39  * See GregorianCalendar.setGregorianChange() and ucal_setGregorianChange().)</p>
  40  *
  41  * ICU provides conversion functions to and from all other major time
  42  * scales, allowing datetimes in any time scale to be converted to the
  43  * universal time scale, safely manipulated, and converted back to any other
  44  * datetime time scale.</p>
  45  *
  46  * <p>For more details and background, see the
  47  * <a href="http://www.icu-project.org/userguide/universalTimeScale.html">Universal Time Scale</a>
  48  * chapter in the ICU User Guide.</p>
  49  *
  50  * @stable ICU 3.2
  51  */
  52
  53 public final class UniversalTimeScale
  54 {
  55     /**
  56      * Used in the JDK. Data is a <code>long</code>. Value
  57      * is milliseconds since January 1, 1970.
  58      *
  59      * @stable ICU 3.2
  60      */
  61     public static final int JAVA_TIME = 0;
  62
  63     /**
  64      * Used in Unix systems. Data is an <code>int</code> or a <code>long</code>. Value
  65      * is seconds since January 1, 1970.
  66      *
  67      * @stable ICU 3.2
  68      */
  69     public static final int UNIX_TIME = 1;
  70
  71     /**
  72      * Used in the ICU4C. Data is a <code>double</code>. Value
  73      * is milliseconds since January 1, 1970.
  74      *
  75      * @stable ICU 3.2
  76      */
  77     public static final int ICU4C_TIME = 2;
  78
  79     /**
  80      * Used in Windows for file times. Data is a <code>long</code>. Value
  81      * is ticks (1 tick == 100 nanoseconds) since January 1, 1601.
  82      *
  83      * @stable ICU 3.2
  84      */
  85     public static final int WINDOWS_FILE_TIME = 3;
  86
  87     /**
  88      * Used in the .NET framework's <code>System.DateTime</code> structure.
  89      * Data is a <code>long</code>. Value is ticks (1 tick == 100 nanoseconds) since January 1, 0001.
  90      *
  91      * @stable ICU 3.2
  92      */
  93     public static final int DOTNET_DATE_TIME = 4;
  94
  95     /**
  96      * Used in older Macintosh systems. Data is an <code>int</code>. Value
  97      * is seconds since January 1, 1904.
  98      *
  99      * @stable ICU 3.2
 100      */
 101     public static final int MAC_OLD_TIME = 5;
 102
 103     /**
 104      * Used in the JDK. Data is a <code>double</code>. Value
 105      * is milliseconds since January 1, 2001.
 106      *
 107      * @stable ICU 3.2
 108      */
 109     public static final int MAC_TIME = 6;
 110
 111     /**
 112      * Used in Excel. Data is a <code>?unknown?</code>. Value
 113      * is days since December 31, 1899.
 114      *
 115      * @stable ICU 3.2
 116      */
 117     public static final int EXCEL_TIME = 7;
 118
 119     /**
 120      * Used in DB2. Data is a <code>?unknown?</code>. Value
 121      * is days since December 31, 1899.
 122      *
 123      * @stable ICU 3.2
 124      */
 125     public static final int DB2_TIME = 8;
 126
 127     /**
 128      * Data is a <code>long</code>. Value is microseconds since January 1, 1970.
 129      * Similar to Unix time (linear value from 1970) and struct timeval
 130      * (microseconds resolution).
 131      *
 132      * @stable ICU 3.8
 133      */
 134     public static final int UNIX_MICROSECONDS_TIME = 9;
 135
 136     /**
 137      * This is the first unused time scale value.
 138      *
 139      * @stable ICU 3.2
 140      */
 141     public static final int MAX_SCALE = 10;
 142
 143     /**
 144      * The constant used to select the units value
 145      * for a time scale.
 146      *
 147      *
 148      * @stable ICU 3.2
 149      */
 150     public static final int UNITS_VALUE = 0;
 151
 152     /**
 153      * The constant used to select the epoch offset value
 154      * for a time scale.
 155      *
 156      * @see #getTimeScaleValue
 157      *
 158      * @stable ICU 3.2
 159      */
 160     public static final int EPOCH_OFFSET_VALUE = 1;
 161
 162     /**
 163      * The constant used to select the minimum from value
 164      * for a time scale.
 165      *
 166      * @see #getTimeScaleValue
 167      *
 168      * @stable ICU 3.2
 169      */
 170     public static final int FROM_MIN_VALUE = 2;
 171
 172     /**
 173      * The constant used to select the maximum from value
 174      * for a time scale.
 175      *
 176      * @see #getTimeScaleValue
 177      *
 178      * @stable ICU 3.2
 179      */
 180     public static final int FROM_MAX_VALUE = 3;
 181
 182     /**
 183      * The constant used to select the minimum to value
 184      * for a time scale.
 185      *
 186      * @see #getTimeScaleValue
 187      *
 188      * @stable ICU 3.2
 189      */
 190     public static final int TO_MIN_VALUE = 4;
 191
 192     /**
 193      * The constant used to select the maximum to value
 194      * for a time scale.
 195      *
 196      * @see #getTimeScaleValue
 197      *
 198      * @stable ICU 3.2
 199      */
 200     public static final int TO_MAX_VALUE = 5;
 201
 202     /**
 203      * The constant used to select the epoch plus one value
 204      * for a time scale.
 205      *
 206      * NOTE: This is an internal value. DO NOT USE IT. May not
 207      * actually be equal to the epoch offset value plus one.
 208      *
 209      * @see #getTimeScaleValue
 210      *
 211      * @stable ICU 3.2
 212      */
 213     public static final int EPOCH_OFFSET_PLUS_1_VALUE = 6;
 214
 215     /**
 216      * The constant used to select the epoch offset minus one value
 217      * for a time scale.
 218      *
 219      * NOTE: This is an internal value. DO NOT USE IT. May not
 220      * actually be equal to the epoch offset value minus one.
 221      *
 222      * @see #getTimeScaleValue
 223      *
 224      * @internal
 225      * @deprecated This API is ICU internal only.
 226      */
 227     public static final int EPOCH_OFFSET_MINUS_1_VALUE = 7;
 228
 229     /**
 230      * The constant used to select the units round value
 231      * for a time scale.
 232      *
 233      * NOTE: This is an internal value. DO NOT USE IT.
 234      *
 235      * @see #getTimeScaleValue
 236      *
 237      * @internal
 238      * @deprecated This API is ICU internal only.
 239      */
 240     public static final int UNITS_ROUND_VALUE = 8;
 241
 242     /**
 243      * The constant used to select the minimum safe rounding value
 244      * for a time scale.
 245      *
 246      * NOTE: This is an internal value. DO NOT USE IT.
 247      *
 248      * @see #getTimeScaleValue
 249      *
 250      * @internal
 251      * @deprecated This API is ICU internal only.
 252      */
 253     public static final int MIN_ROUND_VALUE = 9;
 254
 255     /**
 256      * The constant used to select the maximum safe rounding value
 257      * for a time scale.
 258      *
 259      * NOTE: This is an internal value. DO NOT USE IT.
 260      *
 261      * @see #getTimeScaleValue
 262      *
 263      * @internal
 264      * @deprecated This API is ICU internal only.
 265      */
 266     public static final int MAX_ROUND_VALUE = 10;
 267
 268     /**
 269      * The number of time scale values.
 270      *
 271      * NOTE: This is an internal value. DO NOT USE IT.
 272      *
 273      * @see #getTimeScaleValue
 274      *
 275      * @internal
 276      * @deprecated This API is ICU internal only.
 277      */
 278     public static final int MAX_SCALE_VALUE = 11;
 279
 280     private static final long ticks        = 1;
 281     private static final long microseconds = ticks * 10;
 282     private static final long milliseconds = microseconds * 1000;
 283     private static final long seconds      = milliseconds * 1000;
 284     private static final long minutes      = seconds * 60;
 285     private static final long hours        = minutes * 60;
 286     private static final long days         = hours * 24;
 287
 288     /**
 289      * This class holds the data that describes a particular
 290      * time scale.
 291      */
 292     private static final class TimeScaleData
 293     {
 294         TimeScaleData(long theUnits, long theEpochOffset,
 295                        long theToMin, long theToMax,
 296                        long theFromMin, long theFromMax)
 297         {
 298             units      = theUnits;
 299             unitsRound = theUnits / 2;
 300
 301             minRound = Long.MIN_VALUE + unitsRound;
 302             maxRound = Long.MAX_VALUE - unitsRound;
 303
 304             epochOffset   = theEpochOffset / theUnits;
 305
 306             if (theUnits == 1) {
 307                 epochOffsetP1 = epochOffsetM1 = epochOffset;
 308             } else {
 309                 epochOffsetP1 = epochOffset + 1;
 310                 epochOffsetM1 = epochOffset - 1;
 311             }
 312
 313             toMin = theToMin;
 314             toMax = theToMax;
 315
 316             fromMin = theFromMin;
 317             fromMax = theFromMax;
 318         }
 319
 320         long units;
 321         long epochOffset;
 322         long fromMin;
 323         long fromMax;
 324         long toMin;
 325         long toMax;
 326
 327         long epochOffsetP1;
 328         long epochOffsetM1;
 329         long unitsRound;
 330         long minRound;
 331         long maxRound;
 332     }
 333
 334     private static final TimeScaleData[] timeScaleTable = {
 335         new TimeScaleData(milliseconds, 621355968000000000L, -9223372036854774999L, 9223372036854774999L, -984472800485477L,         860201606885477L), // JAVA_TIME
 336         new TimeScaleData(seconds,      621355968000000000L, -9223372036854775808L, 9223372036854775807L, -984472800485L,               860201606885L), // UNIX_TIME
 337         new TimeScaleData(milliseconds, 621355968000000000L, -9223372036854774999L, 9223372036854774999L, -984472800485477L,         860201606885477L), // ICU4C_TIME
 338         new TimeScaleData(ticks,        504911232000000000L, -8718460804854775808L, 9223372036854775807L, -9223372036854775808L, 8718460804854775807L), // WINDOWS_FILE_TIME
 339         new TimeScaleData(ticks,        000000000000000000L, -9223372036854775808L, 9223372036854775807L, -9223372036854775808L, 9223372036854775807L), // DOTNET_DATE_TIME
 340         new TimeScaleData(seconds,      600527520000000000L, -9223372036854775808L, 9223372036854775807L, -982389955685L,               862284451685L), // MAC_OLD_TIME
 341         new TimeScaleData(seconds,      631139040000000000L, -9223372036854775808L, 9223372036854775807L, -985451107685L,               859223299685L), // MAC_TIME
 342         new TimeScaleData(days,         599265216000000000L, -9223372036854775808L, 9223372036854775807L, -11368793L,                        9981605L), // EXCEL_TIME
 343         new TimeScaleData(days,         599265216000000000L, -9223372036854775808L, 9223372036854775807L, -11368793L,                        9981605L), // DB2_TIME
 344         new TimeScaleData(microseconds, 621355968000000000L, -9223372036854775804L, 9223372036854775804L, -984472800485477580L,   860201606885477580L)  // UNIX_MICROSECONDS_TIME
 345     };
 346
 347
 348     /*
 349      * Prevent construction of this class.
 350      */
 351     ///CLOVER:OFF
 352     private UniversalTimeScale()
 353     {
 354         // nothing to do
 355     }
 356     ///CLOVER:ON
 357
 358     /**
 359      * Convert a <code>long</code> datetime from the given time scale to the universal time scale.
 360      *
 361      * @param otherTime The <code>long</code> datetime
 362      * @param timeScale The time scale to convert from
 363      *
 364      * @return The datetime converted to the universal time scale
 365      *
 366      * @stable ICU 3.2
 367      */
 368     public static long from(long otherTime, int timeScale)
 369     {
 370         TimeScaleData data = fromRangeCheck(otherTime, timeScale);
 371
 372         return (otherTime + data.epochOffset) * data.units;
 373     }
 374
 375     /**
 376      * Convert a <code>double</code> datetime from the given time scale to the universal time scale.
 377      * All calculations are done using <code>BigDecimal</code> to guarantee that the value
 378      * does not go out of range.
 379      *
 380      * @param otherTime The <code>double</code> datetime
 381      * @param timeScale The time scale to convert from
 382      *
 383      * @return The datetime converted to the universal time scale
 384      *
 385      * @stable ICU 3.2
 386      */
 387     public static BigDecimal bigDecimalFrom(double otherTime, int timeScale)
 388     {
 389         TimeScaleData data     = getTimeScaleData(timeScale);
 390         BigDecimal other       = new BigDecimal(String.valueOf(otherTime));
 391         BigDecimal units       = new BigDecimal(data.units);
 392         BigDecimal epochOffset = new BigDecimal(data.epochOffset);
 393
 394         return other.add(epochOffset).multiply(units);
 395     }
 396
 397     /**
 398      * Convert a <code>long</code> datetime from the given time scale to the universal time scale.
 399      * All calculations are done using <code>BigDecimal</code> to guarantee that the value
 400      * does not go out of range.
 401      *
 402      * @param otherTime The <code>long</code> datetime
 403      * @param timeScale The time scale to convert from
 404      *
 405      * @return The datetime converted to the universal time scale
 406      *
 407      * @stable ICU 3.2
 408      */
 409     public static BigDecimal bigDecimalFrom(long otherTime, int timeScale)
 410     {
 411         TimeScaleData data     = getTimeScaleData(timeScale);
 412         BigDecimal other       = new BigDecimal(otherTime);
 413         BigDecimal units       = new BigDecimal(data.units);
 414         BigDecimal epochOffset = new BigDecimal(data.epochOffset);
 415
 416         return other.add(epochOffset).multiply(units);
 417     }
 418
 419     /**
 420      * Convert a <code>BigDecimal</code> datetime from the given time scale to the universal time scale.
 421      * All calculations are done using <code>BigDecimal</code> to guarantee that the value
 422      * does not go out of range.
 423      *
 424      * @param otherTime The <code>BigDecimal</code> datetime
 425      * @param timeScale The time scale to convert from
 426      *
 427      * @return The datetime converted to the universal time scale
 428      *
 429      * @stable ICU 3.2
 430      */
 431     public static BigDecimal bigDecimalFrom(BigDecimal otherTime, int timeScale)
 432     {
 433         TimeScaleData data = getTimeScaleData(timeScale);
 434
 435         BigDecimal units = new BigDecimal(data.units);
 436         BigDecimal epochOffset = new BigDecimal(data.epochOffset);
 437
 438         return otherTime.add(epochOffset).multiply(units);
 439     }
 440
 441     /**
 442      * Convert a datetime from the universal time scale stored as a <code>BigDecimal</code> to a
 443      * <code>long</code> in the given time scale.
 444      *
 445      * Since this calculation requires a divide, we must round. The straight forward
 446      * way to round by adding half of the divisor will push the sum out of range for values
 447      * within have the divisor of the limits of the precision of a <code>long</code>. To get around this, we do
 448      * the rounding like this:
 449      *
 450      * <p><code>
 451      * (universalTime - units + units/2) / units + 1
 452      * </code>
 453      *
 454      * <p>
 455      * (i.e. we subtract units first to guarantee that we'll still be in range when we
 456      * add <code>units/2</code>. We then need to add one to the quotent to make up for the extra subtraction.
 457      * This simplifies to:
 458      *
 459      * <p><code>
 460      * (universalTime - units/2) / units - 1
 461      * </code>
 462      *
 463      * <p>
 464      * For negative values to round away from zero, we need to flip the signs:
 465      *
 466      * <p><code>
 467      * (universalTime + units/2) / units + 1
 468      * </code>
 469      *
 470      * <p>
 471      * Since we also need to subtract the epochOffset, we fold the <code>+/- 1</code>
 472      * into the offset value. (i.e. <code>epochOffsetP1</code>, <code>epochOffsetM1</code>.)
 473      *
 474      * @param universalTime The datetime in the universal time scale
 475      * @param timeScale The time scale to convert to
 476      *
 477      * @return The datetime converted to the given time scale
 478      *
 479      * @stable ICU 3.2
 480      */
 481     public static long toLong(long universalTime, int timeScale)
 482     {
 483         TimeScaleData data = toRangeCheck(universalTime, timeScale);
 484
 485         if (universalTime < 0) {
 486             if (universalTime < data.minRound) {
 487                 return (universalTime + data.unitsRound) / data.units - data.epochOffsetP1;
 488             }
 489
 490             return (universalTime - data.unitsRound) / data.units - data.epochOffset;
 491         }
 492
 493         if (universalTime > data.maxRound) {
 494             return (universalTime - data.unitsRound) / data.units - data.epochOffsetM1;
 495         }
 496
 497         return (universalTime + data.unitsRound) / data.units - data.epochOffset;
 498     }
 499
 500     /**
 501      * Convert a datetime from the universal time scale to a <code>BigDecimal</code> in the given time scale.
 502      *
 503      * @param universalTime The datetime in the universal time scale
 504      * @param timeScale The time scale to convert to
 505      *
 506      * @return The datetime converted to the given time scale
 507      *
 508      * @stable ICU 3.2
 509      */
 510     public static BigDecimal toBigDecimal(long universalTime, int timeScale)
 511     {
 512         TimeScaleData data     = getTimeScaleData(timeScale);
 513         BigDecimal universal   = new BigDecimal(universalTime);
 514         BigDecimal units       = new BigDecimal(data.units);
 515         BigDecimal epochOffset = new BigDecimal(data.epochOffset);
 516
 517         return universal.divide(units, BigDecimal.ROUND_HALF_UP).subtract(epochOffset);
 518     }
 519
 520     /**
 521      * Convert a datetime from the universal time scale to a <code>BigDecimal</code> in the given time scale.
 522      *
 523      * @param universalTime The datetime in the universal time scale
 524      * @param timeScale The time scale to convert to
 525      *
 526      * @return The datetime converted to the given time scale
 527      *
 528      * @stable ICU 3.2
 529      */
 530     public static BigDecimal toBigDecimal(BigDecimal universalTime, int timeScale)
 531     {
 532         TimeScaleData data     = getTimeScaleData(timeScale);
 533         BigDecimal units       = new BigDecimal(data.units);
 534         BigDecimal epochOffset = new BigDecimal(data.epochOffset);
 535
 536         return universalTime.divide(units, BigDecimal.ROUND_HALF_UP).subtract(epochOffset);
 537     }
 538
 539     /**
 540      * Return the <code>TimeScaleData</code> object for the given time
 541      * scale.
 542      *
 543      * @param scale - the time scale
 544      * @return the <code>TimeScaleData</code> object for the given time scale
 545      */
 546     private static TimeScaleData getTimeScaleData(int scale)
 547     {
 548         if (scale < 0 || scale >= MAX_SCALE) {
 549             throw new IllegalArgumentException("scale out of range: " + scale);
 550         }
 551
 552         return timeScaleTable[scale];
 553     }
 554
 555     /**
 556      * Get a value associated with a particular time scale.
 557      *
 558      * @param scale - the time scale
 559      * @param value - a constant representing the value to get
 560      *
 561      * @return - the value.
 562      *
 563      * @stable ICU 3.2
 564      */
 565     public static long getTimeScaleValue(int scale, int value)
 566     {
 567         TimeScaleData data = getTimeScaleData(scale);
 568
 569         switch (value)
 570         {
 571         case UNITS_VALUE:
 572             return data.units;
 573
 574         case EPOCH_OFFSET_VALUE:
 575             return data.epochOffset;
 576
 577         case FROM_MIN_VALUE:
 578             return data.fromMin;
 579
 580         case FROM_MAX_VALUE:
 581             return data.fromMax;
 582
 583         case TO_MIN_VALUE:
 584             return data.toMin;
 585
 586         case TO_MAX_VALUE:
 587             return data.toMax;
 588
 589         case EPOCH_OFFSET_PLUS_1_VALUE:
 590             return data.epochOffsetP1;
 591
 592         case EPOCH_OFFSET_MINUS_1_VALUE:
 593             return data.epochOffsetM1;
 594
 595         case UNITS_ROUND_VALUE:
 596             return data.unitsRound;
 597
 598         case MIN_ROUND_VALUE:
 599             return data.minRound;
 600
 601         case MAX_ROUND_VALUE:
 602             return data.maxRound;
 603
 604         default:
 605             throw new IllegalArgumentException("value out of range: " + value);
 606         }
 607     }
 608
 609     private static TimeScaleData toRangeCheck(long universalTime, int scale)
 610     {
 611         TimeScaleData data = getTimeScaleData(scale);
 612
 613         if (universalTime >= data.toMin && universalTime <= data.toMax) {
 614             return data;
 615         }
 616
 617         throw new IllegalArgumentException("universalTime out of range:" + universalTime);
 618     }
 619
 620     private static TimeScaleData fromRangeCheck(long otherTime, int scale)
 621     {
 622         TimeScaleData data = getTimeScaleData(scale);
 623
 624         if (otherTime >= data.fromMin && otherTime <= data.fromMax) {
 625             return data;
 626         }
 627
 628         throw new IllegalArgumentException("otherTime out of range:" + otherTime);
 629     }
 630
 631     /**
 632      * Convert a time in the Universal Time Scale into another time
 633      * scale. The division used to do the conversion rounds down.
 634      *
 635      * NOTE: This is an internal routine used by the tool that
 636      * generates the to and from limits. Use it at your own risk.
 637      *
 638      * @param universalTime the time in the Universal Time scale
 639      * @param timeScale the time scale to convert to
 640      * @return the time in the given time scale
 641      *
 642      * @internal
 643      * @deprecated This API is ICU internal only.
 644      */
 645     public static BigDecimal toBigDecimalTrunc(BigDecimal universalTime, int timeScale)
 646     {
 647         TimeScaleData data = getTimeScaleData(timeScale);
 648         BigDecimal units = new BigDecimal(data.units);
 649         BigDecimal epochOffset = new BigDecimal(data.epochOffset);
 650
 651         return universalTime.divide(units, BigDecimal.ROUND_DOWN).subtract(epochOffset);
 652     }
 653 }