Java 类org.joda.time.field.FieldUtils 实例源码

/**
 * Creates a new instance representing the number of complete standard length units
 * in the specified period.
 * <p>
 * This factory method converts all fields from the period to hours using standardised
 * durations for each field. Only those fields which have a precise duration in
 * the ISO UTC chronology can be converted.
 * <ul>
 * <li>One week consists of 7 days.
 * <li>One day consists of 24 hours.
 * <li>One hour consists of 60 minutes.
 * <li>One minute consists of 60 seconds.
 * <li>One second consists of 1000 milliseconds.
 * </ul>
 * Months and Years are imprecise and periods containing these values cannot be converted.
 *
 * @param period  the period to get the number of hours from, must not be null
 * @param millisPerUnit  the number of milliseconds in one standard unit of this period
 * @throws IllegalArgumentException if the period contains imprecise duration values
 */
protected static int standardPeriodIn(ReadablePeriod period, long millisPerUnit) {
    if (period == null) {
        return 0;
    }
    Chronology iso = ISOChronology.getInstanceUTC();
    long duration = 0L;
    for (int i = 0; i < period.size(); i++) {
        int value = period.getValue(i);
        if (value != 0) {
            DurationField field = period.getFieldType(i).getField(iso);
            if (field.isPrecise() == false) {
                throw new IllegalArgumentException(
                        "Cannot convert period to duration as " + field.getName() +
                        " is not precise in the period " + period);
            }
            duration = FieldUtils.safeAdd(duration, FieldUtils.safeMultiply(field.getUnitMillis(), value));
        }
    }
    return FieldUtils.safeToInt(duration / millisPerUnit);
}

/**
 * Compares this ReadablePartial with another returning true if the chronology,
 * field types and values are equal.
 *
 * @param partial  an object to check against
 * @return true if fields and values are equal
 */
public boolean equals(Object partial) {
    if (this == partial) {
        return true;
    }
    if (partial instanceof ReadablePartial == false) {
        return false;
    }
    ReadablePartial other = (ReadablePartial) partial;
    if (size() != other.size()) {
        return false;
    }
    for (int i = 0, isize = size(); i < isize; i++) {
        if (getValue(i) != other.getValue(i) || getFieldType(i) != other.getFieldType(i)) {
            return false;
        }
    }
    return FieldUtils.equals(getChronology(), other.getChronology());
}

/**
 * Gets a copy of this Partial with the specified period added.
 * <p>
 * If the addition is zero, then <code>this</code> is returned.
 * Fields in the period that aren't present in the partial are ignored.
 * <p>
 * This method is typically used to add multiple copies of complex
 * period instances. Adding one field is best achieved using the method
 * {@link #withFieldAdded(DurationFieldType, int)}.
 * 
 * @param period  the period to add to this one, null means zero
 * @param scalar  the amount of times to add, such as -1 to subtract once
 * @return a copy of this instance with the period added
 * @throws ArithmeticException if the new datetime exceeds the capacity
 */
public Partial withPeriodAdded(ReadablePeriod period, int scalar) {
    if (period == null || scalar == 0) {
        return this;
    }
    int[] newValues = getValues();
    for (int i = 0; i < period.size(); i++) {
        DurationFieldType fieldType = period.getFieldType(i);
        int index = indexOf(fieldType);
        if (index >= 0) {
            newValues = getField(index).add(this, index, newValues,
                    FieldUtils.safeMultiply(period.getValue(i), scalar));
        }
    }
    return new Partial(this, newValues);
}

public long getDateTimeMillis(
        int year, int monthOfYear, int dayOfMonth,
        int hourOfDay, int minuteOfHour, int secondOfMinute, int millisOfSecond)
        throws IllegalArgumentException {
    Chronology base;
    if ((base = getBase()) != null) {
        return base.getDateTimeMillis(year, monthOfYear, dayOfMonth,
                                      hourOfDay, minuteOfHour, secondOfMinute, millisOfSecond);
    }

    FieldUtils.verifyValueBounds(DateTimeFieldType.hourOfDay(), hourOfDay, 0, 23);
    FieldUtils.verifyValueBounds(DateTimeFieldType.minuteOfHour(), minuteOfHour, 0, 59);
    FieldUtils.verifyValueBounds(DateTimeFieldType.secondOfMinute(), secondOfMinute, 0, 59);
    FieldUtils.verifyValueBounds(DateTimeFieldType.millisOfSecond(), millisOfSecond, 0, 999);

    return getDateMidnightMillis(year, monthOfYear, dayOfMonth)
        + hourOfDay * DateTimeConstants.MILLIS_PER_HOUR
        + minuteOfHour * DateTimeConstants.MILLIS_PER_MINUTE
        + secondOfMinute * DateTimeConstants.MILLIS_PER_SECOND
        + millisOfSecond;
}

/**
 * Set the Month component of the specified time instant.<p>
 * If the new month has less total days than the specified
 * day of the month, this value is coerced to the nearest
 * sane value. e.g.<p>
 * 07-31 to month 6 = 06-30<p>
 * 03-31 to month 2 = 02-28 or 02-29 depending<p>
 * 
 * @param instant  the time instant in millis to update.
 * @param month  the month (1,12) to update the time to.
 * @return the updated time instant.
 * @throws IllegalArgumentException  if month is invalid
 */
public long set(long instant, int month) {
    FieldUtils.verifyValueBounds(this, month, MIN, iMax);
    //
    int thisYear = iChronology.getYear(instant);
    //
    int thisDom = iChronology.getDayOfMonth(instant, thisYear);
    int maxDom = iChronology.getDaysInYearMonth(thisYear, month);
    if (thisDom > maxDom) {
        // Quietly force DOM to nearest sane value.
        thisDom = maxDom;
    }
    // Return newly calculated millis value
    return iChronology.getYearMonthDayMillis(thisYear, month, thisDom) +
        iChronology.getMillisOfDay(instant);
}

/**
 * Constructs an interval from a start instant and a duration.
 * 
 * @param start  start of this interval, null means now
 * @param duration  the duration of this interval, null means zero length
 * @throws IllegalArgumentException if the end is before the start
 * @throws ArithmeticException if the end instant exceeds the capacity of a long
 */
protected BaseInterval(ReadableInstant start, ReadableDuration duration) {
    super();
    iChronology = DateTimeUtils.getInstantChronology(start);
    iStartMillis = DateTimeUtils.getInstantMillis(start);
    long durationMillis = DateTimeUtils.getDurationMillis(duration);
    iEndMillis = FieldUtils.safeAdd(iStartMillis, durationMillis);
    checkInterval(iStartMillis, iEndMillis);
}

/**
 * Constructs an interval from a millisecond duration and an end instant.
 * 
 * @param duration  the duration of this interval, null means zero length
 * @param end  end of this interval, null means now
 * @throws IllegalArgumentException if the end is before the start
 * @throws ArithmeticException if the start instant exceeds the capacity of a long
 */
protected BaseInterval(ReadableDuration duration, ReadableInstant end) {
    super();
    iChronology = DateTimeUtils.getInstantChronology(end);
    iEndMillis = DateTimeUtils.getInstantMillis(end);
    long durationMillis = DateTimeUtils.getDurationMillis(duration);
    iStartMillis = FieldUtils.safeAdd(iEndMillis, -durationMillis);
    checkInterval(iStartMillis, iEndMillis);
}

/**
 * Creates a period from the given duration and end point.
 *
 * @param duration  the duration of the interval, null means zero-length
 * @param endInstant  the interval end, null means now
 * @param type  which set of fields this period supports, null means standard
 */
protected BasePeriod(ReadableDuration duration, ReadableInstant endInstant, PeriodType type) {
    super();
    type = checkPeriodType(type);
    long durationMillis = DateTimeUtils.getDurationMillis(duration);
    long endMillis = DateTimeUtils.getInstantMillis(endInstant);
    long startMillis = FieldUtils.safeSubtract(endMillis, durationMillis);
    Chronology chrono = DateTimeUtils.getInstantChronology(endInstant);
    iType = type;
    iValues = chrono.get(this, startMillis, endMillis);
}

/**
 * Adds the value of a field in this period.
 * 
 * @param values  the array of values to update
 * @param field  the field to set
 * @param value  the value to set
 * @throws IllegalArgumentException if field is is null or not supported.
 */
protected void addFieldInto(int[] values, DurationFieldType field, int value) {
    int index = indexOf(field);
    if (index == -1) {
        if (value != 0 || field == null) {
            throw new IllegalArgumentException(
                "Period does not support field '" + field + "'");
        }
    } else {
        values[index] = FieldUtils.safeAdd(values[index], value);
    }
}

/**
 * Adds to the indexed field part of the period.
 * 
 * @param period  the period to query
 * @param index  the index to use
 * @param values  the array to populate
 * @param valueToAdd  the value to add
 * @return true if the array is updated
 * @throws UnsupportedOperationException if not supported
 */
boolean addIndexedField(ReadablePeriod period, int index, int[] values, int valueToAdd) {
    if (valueToAdd == 0) {
        return false;
    }
    int realIndex = iIndices[index];
    if (realIndex == -1) {
        throw new UnsupportedOperationException("Field is not supported");
    }
    values[realIndex] = FieldUtils.safeAdd(values[realIndex], valueToAdd);
    return true;
}

/**
 * Returns a new instance with each element in this period multiplied
 * by the specified scalar.
 *
 * @param scalar  the scalar to multiply by, not null
 * @return a {@code Period} based on this period with the amounts multiplied by the scalar, never null
 * @throws ArithmeticException if the capacity of any field is exceeded
 * @since 2.1
 */
public Period multipliedBy(int scalar) {
    if (this == ZERO || scalar == 1) {
        return this;
    }
    int[] values = getValues();  // cloned
    for (int i = 0; i < values.length; i++) {
        values[i] = FieldUtils.safeMultiply(values[i], scalar);
    }
    return new Period(values, getPeriodType());
}

/**
 * A limit chronology is only equal to a limit chronology with the
 * same base chronology and limits.
 * 
 * @param obj  the object to compare to
 * @return true if equal
 * @since 1.4
 */
public boolean equals(Object obj) {
    if (this == obj) {
        return true;
    }
    if (obj instanceof LimitChronology == false) {
        return false;
    }
    LimitChronology chrono = (LimitChronology) obj;
    return
        getBase().equals(chrono.getBase()) &&
        FieldUtils.equals(getLowerLimit(), chrono.getLowerLimit()) &&
        FieldUtils.equals(getUpperLimit(), chrono.getUpperLimit());
}

public long add(long instant, int years) {
    if (years == 0) {
        return instant;
    }
    int thisYear = get(instant);
    int newYear = FieldUtils.safeAdd(thisYear, years);
    return set(instant, newYear);
}

public long addWrapField(long instant, int years) {
    if (years == 0) {
        return instant;
    }
    // Return newly calculated millis value
    int thisYear = iChronology.getYear(instant);
    int wrappedYear = FieldUtils.getWrappedValue
        (thisYear, years, iChronology.getMinYear(), iChronology.getMaxYear());
    return set(instant, wrappedYear);
}

public long getDateTimeMillis(
        int year, int monthOfYear, int dayOfMonth, int millisOfDay)
        throws IllegalArgumentException {
    Chronology base;
    if ((base = getBase()) != null) {
        return base.getDateTimeMillis(year, monthOfYear, dayOfMonth, millisOfDay);
    }

    FieldUtils.verifyValueBounds
        (DateTimeFieldType.millisOfDay(), millisOfDay, 0, DateTimeConstants.MILLIS_PER_DAY - 1);
    return getDateMidnightMillis(year, monthOfYear, dayOfMonth) + millisOfDay;
}

public long set(long instant, int year) {
    FieldUtils.verifyValueBounds(this, year, 0, getMaximumValue());
    if (getWrappedField().get(instant) < 0) {
        year = -year;
    }
    return super.set(instant, year);
}

/**
 * Set the Era component of the specified time instant.
 * 
 * @param instant  the time instant in millis to update.
 * @param era  the era to update the time to.
 * @return the updated time instant.
 * @throws IllegalArgumentException  if era is invalid.
 */
public long set(long instant, int era) {
    FieldUtils.verifyValueBounds(this, era, DateTimeConstants.BCE, DateTimeConstants.CE);

    int oldEra = get(instant);
    if (oldEra != era) {
        int year = iChronology.getYear(instant);
        return iChronology.setYear(instant, -year);
    } else {
        return instant;
    }
}

/**
 * Returns a copy of this month-day with the specified period added.
 * <p>
 * If the addition is zero, then <code>this</code> is returned.
 * Fields in the period that aren't present in the partial are ignored.
 * <p>
 * This method is typically used to add multiple copies of complex
 * period instances. Adding one field is best achieved using methods
 * like {@link #withFieldAdded(DurationFieldType, int)}
 * or {@link #plusMonths(int)}.
 * 
 * @param period  the period to add to this one, null means zero
 * @param scalar  the amount of times to add, such as -1 to subtract once
 * @return a copy of this instance with the period added, never null
 * @throws ArithmeticException if the new date-time exceeds the capacity
 */
public MonthDay withPeriodAdded(ReadablePeriod period, int scalar) {
    if (period == null || scalar == 0) {
        return this;
    }
    int[] newValues = getValues();
    for (int i = 0; i < period.size(); i++) {
        DurationFieldType fieldType = period.getFieldType(i);
        int index = indexOf(fieldType);
        if (index >= 0) {
            newValues = getField(index).add(this, index, newValues,
                    FieldUtils.safeMultiply(period.getValue(i), scalar));
        }
    }
    return new MonthDay(this, newValues);
}

/**
 * Normalizes this period using standard rules, assuming a 12 month year,
 * 7 day week, 24 hour day, 60 minute hour and 60 second minute,
 * providing control over how the result is split into fields.
 * <p>
 * This method allows you to normalize a period.
 * However to achieve this it makes the assumption that all years are
 * 12 months, all weeks are 7 days, all days are 24 hours,
 * all hours are 60 minutes and all minutes are 60 seconds. This is not
 * true when daylight savings time is considered, and may also not be true
 * for some chronologies. However, it is included as it is a useful operation
 * for many applications and business rules.
 * <p>
 * If the period contains years or months, then the months will be
 * normalized to be between 0 and 11. The days field and below will be
 * normalized as necessary, however this will not overflow into the months
 * field. Thus a period of 1 year 15 months will normalize to 2 years 3 months.
 * But a period of 1 month 40 days will remain as 1 month 40 days.
 * <p>
 * The PeriodType parameter controls how the result is created. It allows
 * you to omit certain fields from the result if desired. For example,
 * you may not want the result to include weeks, in which case you pass
 * in <code>PeriodType.yearMonthDayTime()</code>.
 * 
 * @param type  the period type of the new period, null means standard type
 * @return a normalized period equivalent to this period
 * @throws ArithmeticException if any field is too large to be represented
 * @throws UnsupportedOperationException if this period contains non-zero
 *  years or months but the specified period type does not support them
 * @since 1.5
 */
public Period normalizedStandard(PeriodType type) {
    long millis = getMillis();  // no overflow can happen, even with Integer.MAX_VALUEs
    millis += (((long) getSeconds()) * ((long) DateTimeConstants.MILLIS_PER_SECOND));
    millis += (((long) getMinutes()) * ((long) DateTimeConstants.MILLIS_PER_MINUTE));
    millis += (((long) getHours()) * ((long) DateTimeConstants.MILLIS_PER_HOUR));
    millis += (((long) getDays()) * ((long) DateTimeConstants.MILLIS_PER_DAY));
    millis += (((long) getWeeks()) * ((long) DateTimeConstants.MILLIS_PER_WEEK));
    Period result = new Period(millis, DateTimeUtils.getPeriodType(type), ISOChronology.getInstanceUTC());
    int years = getYears();
    int months = getMonths();
    if (years != 0 || months != 0) {
        years = FieldUtils.safeAdd(years, months / 12);
        months = months % 12;
        if (years != 0) {
            result = result.withYears(years);
        }
        if (months != 0) {
            result = result.withMonths(months);
        }
    }
    return result;
}

/**
 * Returns a new duration with this length plus that specified multiplied by the scalar.
 * This instance is immutable and is not altered.
 * <p>
 * If the addition is zero, this instance is returned.
 * 
 * @param durationToAdd  the duration to add to this one
 * @param scalar  the amount of times to add, such as -1 to subtract once
 * @return the new duration instance
 */
public Duration withDurationAdded(long durationToAdd, int scalar) {
    if (durationToAdd == 0 || scalar == 0) {
        return this;
    }
    long add = FieldUtils.safeMultiply(durationToAdd, scalar);
    long duration = FieldUtils.safeAdd(getMillis(), add);
    return new Duration(duration);
}

/**
 * Gets the duration of the string using the standard type.
 * This matches the toString() method of ReadableDuration.
 * 
 * @param object  the String to convert, must not be null
 * @throws ClassCastException if the object is invalid
 */
public long getDurationMillis(Object object) {
    // parse here because duration could be bigger than the int supported
    // by the period parser
    String original = (String) object;
    String str = original;
    int len = str.length();
    if (len >= 4 &&
        (str.charAt(0) == 'P' || str.charAt(0) == 'p') &&
        (str.charAt(1) == 'T' || str.charAt(1) == 't') &&
        (str.charAt(len - 1) == 'S' || str.charAt(len - 1) == 's')) {
        // ok
    } else {
        throw new IllegalArgumentException("Invalid format: \"" + original + '"');
    }
    str = str.substring(2, len - 1);
    int dot = -1;
    for (int i = 0; i < str.length(); i++) {
        if ((str.charAt(i) >= '0' && str.charAt(i) <= '9') ||
            (i == 0 && str.charAt(0) == '-')) {
            // ok
        } else if (i > 0 && str.charAt(i) == '.' && dot == -1) {
            // ok
            dot = i;
        } else {
            throw new IllegalArgumentException("Invalid format: \"" + original + '"');
        }
    }
    long millis = 0, seconds = 0;
    if (dot > 0) {
        seconds = Long.parseLong(str.substring(0, dot));
        str = str.substring(dot + 1);
        if (str.length() != 3) {
            str = (str + "000").substring(0, 3);
        }
        millis = Integer.parseInt(str);
    } else {
        seconds = Long.parseLong(str);
    }
    if (seconds < 0) {
        return FieldUtils.safeAdd(FieldUtils.safeMultiply(seconds, 1000), -millis);
    } else {
        return FieldUtils.safeAdd(FieldUtils.safeMultiply(seconds, 1000), millis);
    }
}

/**
 * Returns a copy of this date with the specified period added.
 * <p>
 * If the addition is zero, then <code>this</code> is returned.
 * <p>
 * This method is typically used to add multiple copies of complex
 * period instances. Adding one field is best achieved using methods
 * like {@link #withFieldAdded(DurationFieldType, int)}
 * or {@link #plusYears(int)}.
 * <p>
 * Unsupported time fields are ignored, thus adding a period of 24 hours
 * will not have any effect.
 *
 * @param period  the period to add to this one, null means zero
 * @param scalar  the amount of times to add, such as -1 to subtract once
 * @return a copy of this date with the period added
 * @throws ArithmeticException if the result exceeds the internal capacity
 */
public LocalDate withPeriodAdded(ReadablePeriod period, int scalar) {
    if (period == null || scalar == 0) {
        return this;
    }
    long instant = getLocalMillis();
    Chronology chrono = getChronology();
    for (int i = 0; i < period.size(); i++) {
        long value = FieldUtils.safeMultiply(period.getValue(i), scalar);
        DurationFieldType type = period.getFieldType(i);
        if (isSupported(type)) {
            instant = type.getField(chrono).add(instant, value);
        }
    }
    return withLocalMillis(instant);
}

/**
 * Returns a copy of this date with the specified period added.
 * <p>
 * If the addition is zero, then <code>this</code> is returned.
 * Fields in the period that aren't present in the partial are ignored.
 * <p>
 * This method is typically used to add multiple copies of complex
 * period instances. Adding one field is best achieved using methods
 * like {@link #withFieldAdded(DurationFieldType, int)}
 * or {@link #plusYears(int)}.
 * 
 * @param period  the period to add to this one, null means zero
 * @param scalar  the amount of times to add, such as -1 to subtract once
 * @return a copy of this instance with the period added
 * @throws ArithmeticException if the new datetime exceeds the capacity
 */
public YearMonthDay withPeriodAdded(ReadablePeriod period, int scalar) {
    if (period == null || scalar == 0) {
        return this;
    }
    int[] newValues = getValues();
    for (int i = 0; i < period.size(); i++) {
        DurationFieldType fieldType = period.getFieldType(i);
        int index = indexOf(fieldType);
        if (index >= 0) {
            newValues = getField(index).add(this, index, newValues,
                    FieldUtils.safeMultiply(period.getValue(i), scalar));
        }
    }
    return new YearMonthDay(this, newValues);
}

/**
 * Returns a copy of this time with the specified period added,
 * wrapping to what would be a new day if required.
 * <p>
 * If the addition is zero, then <code>this</code> is returned.
 * Fields in the period that aren't present in the partial are ignored.
 * <p>
 * This method is typically used to add multiple copies of complex
 * period instances. Adding one field is best achieved using methods
 * like {@link #withFieldAdded(DurationFieldType, int)}
 * or {@link #plusHours(int)}.
 * 
 * @param period  the period to add to this one, null means zero
 * @param scalar  the amount of times to add, such as -1 to subtract once
 * @return a copy of this instance with the period added
 * @throws ArithmeticException if the new datetime exceeds the capacity
 */
public TimeOfDay withPeriodAdded(ReadablePeriod period, int scalar) {
    if (period == null || scalar == 0) {
        return this;
    }
    int[] newValues = getValues();
    for (int i = 0; i < period.size(); i++) {
        DurationFieldType fieldType = period.getFieldType(i);
        int index = indexOf(fieldType);
        if (index >= 0) {
            newValues = getField(index).addWrapPartial(this, index, newValues,
                    FieldUtils.safeMultiply(period.getValue(i), scalar));
        }
    }
    return new TimeOfDay(this, newValues);
}

/** @inheritDoc */
public long set(long instant, int era) {
    FieldUtils.verifyValueBounds(this, era, ERA_VALUE, ERA_VALUE);
    return instant;
}

public long add(long instant, long years) {
    return add(instant, FieldUtils.safeToInt(years));
}

public long set(long instant, int year) {
    FieldUtils.verifyValueBounds
        (this, year, iChronology.getMinYear(), iChronology.getMaxYear());
    return iChronology.setYear(instant, year);
}

public long add(long instant, long value) {
    return add(instant, FieldUtils.safeToInt(value));
}

/**
 * Adds to each field of this period.
 * 
 * @param years  amount of years to add to this period, which must be zero if unsupported
 * @param months  amount of months to add to this period, which must be zero if unsupported
 * @param weeks  amount of weeks to add to this period, which must be zero if unsupported
 * @param days  amount of days to add to this period, which must be zero if unsupported
 * @param hours  amount of hours to add to this period, which must be zero if unsupported
 * @param minutes  amount of minutes to add to this period, which must be zero if unsupported
 * @param seconds  amount of seconds to add to this period, which must be zero if unsupported
 * @param millis  amount of milliseconds to add to this period, which must be zero if unsupported
 * @throws IllegalArgumentException if the period being added contains a field
 * not supported by this period
 * @throws ArithmeticException if the addition exceeds the capacity of the period
 */
public void add(int years, int months, int weeks, int days,
                   int hours, int minutes, int seconds, int millis) {
    setPeriod(
        FieldUtils.safeAdd(getYears(), years),
        FieldUtils.safeAdd(getMonths(), months),
        FieldUtils.safeAdd(getWeeks(), weeks),
        FieldUtils.safeAdd(getDays(), days),
        FieldUtils.safeAdd(getHours(), hours),
        FieldUtils.safeAdd(getMinutes(), minutes),
        FieldUtils.safeAdd(getSeconds(), seconds),
        FieldUtils.safeAdd(getMillis(), millis)
    );
}

/**
 * Returns a new instance with the specified number of hours added.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param hours  the amount of hours to add, may be negative
 * @return the new period plus the specified number of hours
 * @throws ArithmeticException if the result overflows an int
 */
public Hours plus(int hours) {
    if (hours == 0) {
        return this;
    }
    return Hours.hours(FieldUtils.safeAdd(getValue(), hours));
}

/**
 * Compares this object with the specified object for equality based
 * on the millisecond instant, chronology and time zone.
 * <p>
 * Two objects which represent the same instant in time, but are in
 * different time zones (based on time zone id), will be considered to
 * be different. Only two objects with the same {@link DateTimeZone},
 * {@link Chronology} and instant are equal.
 * <p>
 * See {@link #isEqual(ReadableInstant)} for an equals method that
 * ignores the Chronology and time zone.
 * <p>
 * All ReadableInstant instances are accepted.
 *
 * @param readableInstant  a readable instant to check against
 * @return true if millisecond and chronology are equal, false if
 *  not or the instant is null or of an incorrect type
 */
public boolean equals(Object readableInstant) {
    // must be to fulfil ReadableInstant contract
    if (this == readableInstant) {
        return true;
    }
    if (readableInstant instanceof ReadableInstant == false) {
        return false;
    }
    ReadableInstant otherInstant = (ReadableInstant) readableInstant;
    return
        getMillis() == otherInstant.getMillis() &&
        FieldUtils.equals(getChronology(), otherInstant.getChronology());
}

/**
 * Returns a new instance with the specified number of minutes added.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param minutes  the amount of minutes to add, may be negative
 * @return the new period plus the specified number of minutes
 * @throws ArithmeticException if the result overflows an int
 */
public Minutes plus(int minutes) {
    if (minutes == 0) {
        return this;
    }
    return Minutes.minutes(FieldUtils.safeAdd(getValue(), minutes));
}

/**
 * Returns a new instance with the specified number of weeks added.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param weeks  the amount of weeks to add, may be negative
 * @return the new period plus the specified number of weeks
 * @throws ArithmeticException if the result overflows an int
 */
public Weeks plus(int weeks) {
    if (weeks == 0) {
        return this;
    }
    return Weeks.weeks(FieldUtils.safeAdd(getValue(), weeks));
}

/**
 * Converts this period to a period in weeks assuming a
 * 7 day week, 24 hour day, 60 minute hour and 60 second minute.
 * <p>
 * This method allows you to convert between different types of period.
 * However to achieve this it makes the assumption that all
 * weeks are 7 days, all days are 24 hours, all hours are 60 minutes and
 * all minutes are 60 seconds. This is not true when daylight savings time
 * is considered, and may also not be true for some unusual chronologies.
 * However, it is included as it is a useful operation for many
 * applications and business rules.
 * <p>
 * If the period contains years or months, an exception will be thrown.
 * 
 * @return a period representing the number of standard weeks in this period
 * @throws UnsupportedOperationException if the period contains years or months
 * @throws ArithmeticException if the number of weeks is too large to be represented
 * @since 1.5
 */
public Weeks toStandardWeeks() {
    checkYearsAndMonths("Weeks");
    long millis = getMillis();  // assign to a long
    millis += ((long) getSeconds()) * DateTimeConstants.MILLIS_PER_SECOND;
    millis += ((long) getMinutes()) * DateTimeConstants.MILLIS_PER_MINUTE;
    millis += ((long) getHours()) * DateTimeConstants.MILLIS_PER_HOUR;
    millis += ((long) getDays()) * DateTimeConstants.MILLIS_PER_DAY;
    long weeks = ((long) getWeeks()) + millis / DateTimeConstants.MILLIS_PER_WEEK;
    return Weeks.weeks(FieldUtils.safeToInt(weeks));
}

/**
 * Converts this period to a period in days assuming a
 * 7 day week, 24 hour day, 60 minute hour and 60 second minute.
 * <p>
 * This method allows you to convert between different types of period.
 * However to achieve this it makes the assumption that all
 * weeks are 7 days, all days are 24 hours, all hours are 60 minutes and
 * all minutes are 60 seconds. This is not true when daylight savings time
 * is considered, and may also not be true for some unusual chronologies.
 * However, it is included as it is a useful operation for many
 * applications and business rules.
 * <p>
 * If the period contains years or months, an exception will be thrown.
 * 
 * @return a period representing the number of standard days in this period
 * @throws UnsupportedOperationException if the period contains years or months
 * @throws ArithmeticException if the number of days is too large to be represented
 * @since 1.5
 */
public Days toStandardDays() {
    checkYearsAndMonths("Days");
    long millis = getMillis();  // assign to a long
    millis += ((long) getSeconds()) * DateTimeConstants.MILLIS_PER_SECOND;
    millis += ((long) getMinutes()) * DateTimeConstants.MILLIS_PER_MINUTE;
    millis += ((long) getHours()) * DateTimeConstants.MILLIS_PER_HOUR;
    long days = millis / DateTimeConstants.MILLIS_PER_DAY;
    days = FieldUtils.safeAdd(days, getDays());
    days = FieldUtils.safeAdd(days, ((long) getWeeks()) * ((long) DateTimeConstants.DAYS_PER_WEEK));
    return Days.days(FieldUtils.safeToInt(days));
}

/**
 * Converts this period to a period in hours assuming a
 * 7 day week, 24 hour day, 60 minute hour and 60 second minute.
 * <p>
 * This method allows you to convert between different types of period.
 * However to achieve this it makes the assumption that all
 * weeks are 7 days, all days are 24 hours, all hours are 60 minutes and
 * all minutes are 60 seconds. This is not true when daylight savings time
 * is considered, and may also not be true for some unusual chronologies.
 * However, it is included as it is a useful operation for many
 * applications and business rules.
 * <p>
 * If the period contains years or months, an exception will be thrown.
 * 
 * @return a period representing the number of standard hours in this period
 * @throws UnsupportedOperationException if the period contains years or months
 * @throws ArithmeticException if the number of hours is too large to be represented
 * @since 1.5
 */
public Hours toStandardHours() {
    checkYearsAndMonths("Hours");
    long millis = getMillis();  // assign to a long
    millis += ((long) getSeconds()) * DateTimeConstants.MILLIS_PER_SECOND;
    millis += ((long) getMinutes()) * DateTimeConstants.MILLIS_PER_MINUTE;
    long hours = millis / DateTimeConstants.MILLIS_PER_HOUR;
    hours = FieldUtils.safeAdd(hours, getHours());
    hours = FieldUtils.safeAdd(hours, ((long) getDays()) * ((long) DateTimeConstants.HOURS_PER_DAY));
    hours = FieldUtils.safeAdd(hours, ((long) getWeeks()) * ((long) DateTimeConstants.HOURS_PER_WEEK));
    return Hours.hours(FieldUtils.safeToInt(hours));
}

/**
 * Converts this period to a period in minutes assuming a
 * 7 day week, 24 hour day, 60 minute hour and 60 second minute.
 * <p>
 * This method allows you to convert between different types of period.
 * However to achieve this it makes the assumption that all
 * weeks are 7 days, all days are 24 hours, all hours are 60 minutes and
 * all minutes are 60 seconds. This is not true when daylight savings time
 * is considered, and may also not be true for some unusual chronologies.
 * However, it is included as it is a useful operation for many
 * applications and business rules.
 * <p>
 * If the period contains years or months, an exception will be thrown.
 * 
 * @return a period representing the number of standard minutes in this period
 * @throws UnsupportedOperationException if the period contains years or months
 * @throws ArithmeticException if the number of minutes is too large to be represented
 * @since 1.5
 */
public Minutes toStandardMinutes() {
    checkYearsAndMonths("Minutes");
    long millis = getMillis();  // assign to a long
    millis += ((long) getSeconds()) * DateTimeConstants.MILLIS_PER_SECOND;
    long minutes = millis / DateTimeConstants.MILLIS_PER_MINUTE;
    minutes = FieldUtils.safeAdd(minutes, getMinutes());
    minutes = FieldUtils.safeAdd(minutes, ((long) getHours()) * ((long) DateTimeConstants.MINUTES_PER_HOUR));
    minutes = FieldUtils.safeAdd(minutes, ((long) getDays()) * ((long) DateTimeConstants.MINUTES_PER_DAY));
    minutes = FieldUtils.safeAdd(minutes, ((long) getWeeks()) * ((long) DateTimeConstants.MINUTES_PER_WEEK));
    return Minutes.minutes(FieldUtils.safeToInt(minutes));
}

/**
 * Converts this period to a period in seconds assuming a
 * 7 day week, 24 hour day, 60 minute hour and 60 second minute.
 * <p>
 * This method allows you to convert between different types of period.
 * However to achieve this it makes the assumption that all
 * weeks are 7 days, all days are 24 hours, all hours are 60 minutes and
 * all minutes are 60 seconds. This is not true when daylight savings time
 * is considered, and may also not be true for some unusual chronologies.
 * However, it is included as it is a useful operation for many
 * applications and business rules.
 * <p>
 * If the period contains years or months, an exception will be thrown.
 * 
 * @return a period representing the number of standard seconds in this period
 * @throws UnsupportedOperationException if the period contains years or months
 * @throws ArithmeticException if the number of seconds is too large to be represented
 * @since 1.5
 */
public Seconds toStandardSeconds() {
    checkYearsAndMonths("Seconds");
    long seconds = getMillis() / DateTimeConstants.MILLIS_PER_SECOND;
    seconds = FieldUtils.safeAdd(seconds, getSeconds());
    seconds = FieldUtils.safeAdd(seconds, ((long) getMinutes()) * ((long) DateTimeConstants.SECONDS_PER_MINUTE));
    seconds = FieldUtils.safeAdd(seconds, ((long) getHours()) * ((long) DateTimeConstants.SECONDS_PER_HOUR));
    seconds = FieldUtils.safeAdd(seconds, ((long) getDays()) * ((long) DateTimeConstants.SECONDS_PER_DAY));
    seconds = FieldUtils.safeAdd(seconds, ((long) getWeeks()) * ((long) DateTimeConstants.SECONDS_PER_WEEK));
    return Seconds.seconds(FieldUtils.safeToInt(seconds));
}

/**
 * Create a duration with the specified number of days assuming that
 * there are the standard number of milliseconds in a day.
 * <p>
 * This method assumes that there are 24 hours in a day,
 * 60 minutes in an hour, 60 seconds in a minute and 1000 milliseconds in
 * a second. This will be true for most days, however days with Daylight
 * Savings changes will not have 24 hours, so use this method with care.
 * <p>
 * A Duration is a representation of an amount of time. If you want to express
 * the concepts of 'days' you should consider using the {@link Days} class.
 *
 * @param days  the number of standard days in this duration
 * @return the duration, never null
 * @throws ArithmeticException if the days value is too large
 * @since 1.6
 */
public static Duration standardDays(long days) {
    if (days == 0) {
        return ZERO;
    }
    return new Duration(FieldUtils.safeMultiply(days, DateTimeConstants.MILLIS_PER_DAY));
}

/**
 * Create a duration with the specified number of hours assuming that
 * there are the standard number of milliseconds in an hour.
 * <p>
 * This method assumes that there are 60 minutes in an hour,
 * 60 seconds in a minute and 1000 milliseconds in a second.
 * All currently supplied chronologies use this definition.
 * <p>
 * A Duration is a representation of an amount of time. If you want to express
 * the concepts of 'hours' you should consider using the {@link Hours} class.
 *
 * @param hours  the number of standard hours in this duration
 * @return the duration, never null
 * @throws ArithmeticException if the hours value is too large
 * @since 1.6
 */
public static Duration standardHours(long hours) {
    if (hours == 0) {
        return ZERO;
    }
    return new Duration(FieldUtils.safeMultiply(hours, DateTimeConstants.MILLIS_PER_HOUR));
}