content: /*
   * Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
   * particular file as subject to the "Classpath" exception as provided
   * by Oracle in the LICENSE file that accompanied this code.
   *
   * This code is distributed in the hope that it will be useful, but WITHOUT
   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   * version 2 for more details (a copy is included in the LICENSE file that
   * accompanied this code).
   *
   * You should have received a copy of the GNU General Public License version
   * 2 along with this work; if not, write to the Free Software Foundation,
   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   *
   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   * or visit www.oracle.com if you need additional information or have any
   * questions.
   */
  
  package java.nio.file.attribute;
  
  import java.time.Instant;
  import java.time.LocalDateTime;
  import java.time.ZoneOffset;
  import java.util.Objects;
  import java.util.concurrent.TimeUnit;
  
  /**
   * Represents the value of a file's time stamp attribute. For example, it may
   * represent the time that the file was last
   * {@link BasicFileAttributes#lastModifiedTime() modified},
   * {@link BasicFileAttributes#lastAccessTime() accessed},
   * or {@link BasicFileAttributes#creationTime() created}.
   *
   * <p> Instances of this class are immutable.
   *
   * @since 1.7
   * @see java.nio.file.Files#setLastModifiedTime
   * @see java.nio.file.Files#getLastModifiedTime
   */
  
  public final class FileTime
      implements Comparable<FileTime>
  {
      /**
       * The unit of granularity to interpret the value. Null if
       * this {@code FileTime} is converted from an {@code Instant},
       * the {@code value} and {@code unit} pair will not be used
       * in this scenario.
       */
      private final TimeUnit unit;
  
      /**
       * The value since the epoch; can be negative.
       */
      private final long value;
  
      /**
       * The value as Instant (created lazily, if not from an instant)
       */
      private Instant instant;
  
      /**
       * The value return by toString (created lazily)
       */
      private String valueAsString;
  
      /**
       * Initializes a new instance of this class.
       */
      private FileTime(long value, TimeUnit unit, Instant instant) {
          this.value = value;
          this.unit = unit;
          this.instant = instant;
      }
  
      /**
       * Returns a {@code FileTime} representing a value at the given unit of
       * granularity.
       *
       * @param   value
       *          the value since the epoch (1970-01-01T00:00:00Z); can be
       *          negative
       * @param   unit
       *          the unit of granularity to interpret the value
       *
       * @return  a {@code FileTime} representing the given value
       */
      public static FileTime from(long value, TimeUnit unit) {
          Objects.requireNonNull(unit, "unit");
          return new FileTime(value, unit, null);
      }
  
      /**
       * Returns a {@code FileTime} representing the given value in milliseconds.
       *
       * @param   value
       *          the value, in milliseconds, since the epoch
       *          (1970-01-01T00:00:00Z); can be negative
       *
       * @return  a {@code FileTime} representing the given value
       */
      public static FileTime fromMillis(long value) {
          return new FileTime(value, TimeUnit.MILLISECONDS, null);
      }
  
      /**
       * Returns a {@code FileTime} representing the same point of time value
       * on the time-line as the provided {@code Instant} object.
       *
       * @param   instant
       *          the instant to convert
       * @return  a {@code FileTime} representing the same point on the time-line
       *          as the provided instant
       * @since 1.8
       */
      public static FileTime from(Instant instant) {
          Objects.requireNonNull(instant, "instant");
          return new FileTime(0, null, instant);
      }
  
      /**
       * Returns the value at the given unit of granularity.
       *
       * <p> Conversion from a coarser granularity that would numerically overflow
       * saturate to {@code Long.MIN_VALUE} if negative or {@code Long.MAX_VALUE}
       * if positive.
       *
       * @param   unit
       *          the unit of granularity for the return value
       *
       * @return  value in the given unit of granularity, since the epoch
       *          since the epoch (1970-01-01T00:00:00Z); can be negative
       */
      public long to(TimeUnit unit) {
          Objects.requireNonNull(unit, "unit");
          if (this.unit != null) {
              return unit.convert(this.value, this.unit);
          } else {
              long secs = unit.convert(instant.getEpochSecond(), TimeUnit.SECONDS);
              if (secs == Long.MIN_VALUE || secs == Long.MAX_VALUE) {
                  return secs;
              }
              long nanos = unit.convert(instant.getNano(), TimeUnit.NANOSECONDS);
              long r = secs + nanos;
              // Math.addExact() variant
              if (((secs ^ r) & (nanos ^ r)) < 0) {
                  return (secs < 0) ? Long.MIN_VALUE : Long.MAX_VALUE;
              }
              return r;
          }
      }
  
      /**
       * Returns the value in milliseconds.
       *
       * <p> Conversion from a coarser granularity that would numerically overflow
       * saturate to {@code Long.MIN_VALUE} if negative or {@code Long.MAX_VALUE}
       * if positive.
       *
       * @return  the value in milliseconds, since the epoch (1970-01-01T00:00:00Z)
       */
      public long toMillis() {
          if (unit != null) {
              return unit.toMillis(value);
          } else {
              long secs = instant.getEpochSecond();
              int  nanos = instant.getNano();
              // Math.multiplyExact() variant
              long r = secs * 1000;
              long ax = Math.abs(secs);
              if (((ax | 1000) >>> 31 != 0)) {
                  if ((r / 1000) != secs) {
                      return (secs < 0) ? Long.MIN_VALUE : Long.MAX_VALUE;
                  }
              }
              return r + nanos / 1000_000;
          }
      }
  
      /**
       * Time unit constants for conversion.
       */
      private static final long HOURS_PER_DAY      = 24L;
      private static final long MINUTES_PER_HOUR   = 60L;
      private static final long SECONDS_PER_MINUTE = 60L;
      private static final long SECONDS_PER_HOUR   = SECONDS_PER_MINUTE * MINUTES_PER_HOUR;
      private static final long SECONDS_PER_DAY    = SECONDS_PER_HOUR * HOURS_PER_DAY;
      private static final long MILLIS_PER_SECOND  = 1000L;
      private static final long MICROS_PER_SECOND  = 1000_000L;
      private static final long NANOS_PER_SECOND   = 1000_000_000L;
      private static final int  NANOS_PER_MILLI    = 1000_000;
      private static final int  NANOS_PER_MICRO    = 1000;
      // The epoch second of Instant.MIN.
      private static final long MIN_SECOND = -31557014167219200L;
      // The epoch second of Instant.MAX.
      private static final long MAX_SECOND = 31556889864403199L;
  
      /*
       * Scale d by m, checking for overflow.
       */
      private static long scale(long d, long m, long over) {
          if (d >  over) return Long.MAX_VALUE;
          if (d < -over) return Long.MIN_VALUE;
          return d * m;
      }
  
      /**
       * Converts this {@code FileTime} object to an {@code Instant}.
       *
       * <p> The conversion creates an {@code Instant} that represents the
       * same point on the time-line as this {@code FileTime}.
       *
       * <p> {@code FileTime} can store points on the time-line further in the
       * future and further in the past than {@code Instant}. Conversion
       * from such further time points saturates to {@link Instant#MIN} if
       * earlier than {@code Instant.MIN} or {@link Instant#MAX} if later
       * than {@code Instant.MAX}.
       *
       * @return  an instant representing the same point on the time-line as
       *          this {@code FileTime} object
       * @since 1.8
       */
      public Instant toInstant() {
          if (instant == null) {
              long secs = 0L;
              int nanos = 0;
              switch (unit) {
                  case DAYS:
                      secs = scale(value, SECONDS_PER_DAY,
                                   Long.MAX_VALUE/SECONDS_PER_DAY);
                      break;
                  case HOURS:
                      secs = scale(value, SECONDS_PER_HOUR,
                                   Long.MAX_VALUE/SECONDS_PER_HOUR);
                      break;
                  case MINUTES:
                      secs = scale(value, SECONDS_PER_MINUTE,
                                   Long.MAX_VALUE/SECONDS_PER_MINUTE);
                      break;
                  case SECONDS:
                      secs = value;
                      break;
                  case MILLISECONDS:
                      secs = Math.floorDiv(value, MILLIS_PER_SECOND);
                      nanos = (int)Math.floorMod(value, MILLIS_PER_SECOND)
                              * NANOS_PER_MILLI;
                      break;
                  case MICROSECONDS:
                      secs = Math.floorDiv(value, MICROS_PER_SECOND);
                      nanos = (int)Math.floorMod(value, MICROS_PER_SECOND)
                              * NANOS_PER_MICRO;
                      break;
                  case NANOSECONDS:
                      secs = Math.floorDiv(value, NANOS_PER_SECOND);
                      nanos = (int)Math.floorMod(value, NANOS_PER_SECOND);
                      break;
                  default : throw new AssertionError("Unit not handled");
              }
              if (secs <= MIN_SECOND)
                  instant = Instant.MIN;
              else if (secs >= MAX_SECOND)
                  instant = Instant.MAX;
              else
                  instant = Instant.ofEpochSecond(secs, nanos);
          }
          return instant;
      }
  
      /**
       * Tests this {@code FileTime} for equality with the given object.
       *
       * <p> The result is {@code true} if and only if the argument is not {@code
       * null} and is a {@code FileTime} that represents the same time. This
       * method satisfies the general contract of the {@code Object.equals} method.
       *
       * @param   obj
       *          the object to compare with
       *
       * @return  {@code true} if, and only if, the given object is a {@code
       *          FileTime} that represents the same time
       */
      @Override
      public boolean equals(Object obj) {
          return (obj instanceof FileTime) ? compareTo((FileTime)obj) == 0 : false;
      }
  
      /**
       * Computes a hash code for this file time.
       *
       * <p> The hash code is based upon the value represented, and satisfies the
       * general contract of the {@link Object#hashCode} method.
       *
       * @return  the hash-code value
       */
      @Override
      public int hashCode() {
          // hashcode of instant representation to satisfy contract with equals
          return toInstant().hashCode();
      }
  
      private long toDays() {
          if (unit != null) {
              return unit.toDays(value);
          } else {
              return TimeUnit.SECONDS.toDays(toInstant().getEpochSecond());
          }
      }
  
      private long toExcessNanos(long days) {
          if (unit != null) {
              return unit.toNanos(value - unit.convert(days, TimeUnit.DAYS));
          } else {
              return TimeUnit.SECONDS.toNanos(toInstant().getEpochSecond()
                                              - TimeUnit.DAYS.toSeconds(days));
          }
      }
  
      /**
       * Compares the value of two {@code FileTime} objects for order.
       *
       * @param   other
       *          the other {@code FileTime} to be compared
       *
       * @return  {@code 0} if this {@code FileTime} is equal to {@code other}, a
       *          value less than 0 if this {@code FileTime} represents a time
       *          that is before {@code other}, and a value greater than 0 if this
       *          {@code FileTime} represents a time that is after {@code other}
       */
      @Override
      public int compareTo(FileTime other) {
          // same granularity
          if (unit != null && unit == other.unit) {
              return Long.compare(value, other.value);
          } else {
              // compare using instant representation when unit differs
              long secs = toInstant().getEpochSecond();
              long secsOther = other.toInstant().getEpochSecond();
              int cmp = Long.compare(secs, secsOther);
              if (cmp != 0) {
                  return cmp;
              }
              cmp = Long.compare(toInstant().getNano(), other.toInstant().getNano());
              if (cmp != 0) {
                  return cmp;
              }
              if (secs != MAX_SECOND && secs != MIN_SECOND) {
                  return 0;
              }
              // if both this and other's Instant reps are MIN/MAX,
              // use daysSinceEpoch and nanosOfDays, which will not
              // saturate during calculation.
              long days = toDays();
              long daysOther = other.toDays();
              if (days == daysOther) {
                  return Long.compare(toExcessNanos(days), other.toExcessNanos(daysOther));
              }
              return Long.compare(days, daysOther);
          }
      }
  
      // days in a 400 year cycle = 146097
      // days in a 10,000 year cycle = 146097 * 25
      // seconds per day = 86400
      private static final long DAYS_PER_10000_YEARS = 146097L * 25L;
      private static final long SECONDS_PER_10000_YEARS = 146097L * 25L * 86400L;
      private static final long SECONDS_0000_TO_1970 = ((146097L * 5L) - (30L * 365L + 7L)) * 86400L;
  
      // append year/month/day/hour/minute/second/nano with width and 0 padding
      private StringBuilder append(StringBuilder sb, int w, int d) {
          while (w > 0) {
              sb.append((char)(d/w + '0'));
              d = d % w;
              w /= 10;
          }
          return sb;
      }
  
      /**
       * Returns the string representation of this {@code FileTime}. The string
       * is returned in the <a
       * href="http://www.w3.org/TR/NOTE-datetime">ISO&nbsp;8601</a> format:
       * <pre>
       *     YYYY-MM-DDThh:mm:ss[.s+]Z
       * </pre>
       * where "{@code [.s+]}" represents a dot followed by one of more digits
       * for the decimal fraction of a second. It is only present when the decimal
       * fraction of a second is not zero. For example, {@code
       * FileTime.fromMillis(1234567890000L).toString()} yields {@code
       * "2009-02-13T23:31:30Z"}, and {@code FileTime.fromMillis(1234567890123L).toString()}
       * yields {@code "2009-02-13T23:31:30.123Z"}.
       *
       * <p> A {@code FileTime} is primarily intended to represent the value of a
       * file's time stamp. Where used to represent <i>extreme values</i>, where
       * the year is less than "{@code 0001}" or greater than "{@code 9999}" then
       * this method deviates from ISO 8601 in the same manner as the
       * <a href="http://www.w3.org/TR/xmlschema-2/#deviantformats">XML Schema
       * language</a>. That is, the year may be expanded to more than four digits
       * and may be negative-signed. If more than four digits then leading zeros
       * are not present. The year before "{@code 0001}" is "{@code -0001}".
       *
       * @return  the string representation of this file time
       */
      @Override
      public String toString() {
          if (valueAsString == null) {
              long secs = 0L;
              int  nanos = 0;
              if (instant == null && unit.compareTo(TimeUnit.SECONDS) >= 0) {
                  secs = unit.toSeconds(value);
              } else {
                  secs = toInstant().getEpochSecond();
                  nanos = toInstant().getNano();
              }
              LocalDateTime ldt;
              int year = 0;
              if (secs >= -SECONDS_0000_TO_1970) {
                  // current era
                  long zeroSecs = secs - SECONDS_PER_10000_YEARS + SECONDS_0000_TO_1970;
                  long hi = Math.floorDiv(zeroSecs, SECONDS_PER_10000_YEARS) + 1;
                  long lo = Math.floorMod(zeroSecs, SECONDS_PER_10000_YEARS);
                  ldt = LocalDateTime.ofEpochSecond(lo - SECONDS_0000_TO_1970, nanos, ZoneOffset.UTC);
                  year = ldt.getYear() +  (int)hi * 10000;
              } else {
                  // before current era
                  long zeroSecs = secs + SECONDS_0000_TO_1970;
                  long hi = zeroSecs / SECONDS_PER_10000_YEARS;
                  long lo = zeroSecs % SECONDS_PER_10000_YEARS;
                  ldt = LocalDateTime.ofEpochSecond(lo - SECONDS_0000_TO_1970, nanos, ZoneOffset.UTC);
                  year = ldt.getYear() + (int)hi * 10000;
              }
              if (year <= 0) {
                  year = year - 1;
              }
              int fraction = ldt.getNano();
              StringBuilder sb = new StringBuilder(64);
              sb.append(year < 0 ? "-" : "");
              year = Math.abs(year);
              if (year < 10000) {
                  append(sb, 1000, Math.abs(year));
              } else {
                  sb.append(String.valueOf(year));
              }
              sb.append('-');
              append(sb, 10, ldt.getMonthValue());
              sb.append('-');
              append(sb, 10, ldt.getDayOfMonth());
              sb.append('T');
              append(sb, 10, ldt.getHour());
              sb.append(':');
              append(sb, 10, ldt.getMinute());
              sb.append(':');
              append(sb, 10, ldt.getSecond());
              if (fraction != 0) {
                  sb.append('.');
                  // adding leading zeros and stripping any trailing zeros
                  int w = 100_000_000;
                  while (fraction % 10 == 0) {
                      fraction /= 10;
                      w /= 10;
                  }
                  append(sb, w, fraction);
              }
              sb.append('Z');
              valueAsString = sb.toString();
          }
          return valueAsString;
      }
  }
  