/**
* 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);
}
/**
* Returns a copy of this time minus the specified number of millis.
*
* <p>This time instance is immutable and unaffected by this method call.
*
* <p>The following three lines are identical in effect:
*
* <pre>
* TimeOfDay subtracted = dt.minusMillis(6);
* TimeOfDay subtracted = dt.minus(Period.millis(6));
* TimeOfDay subtracted = dt.withFieldAdded(DurationFieldType.millis(), -6);
* </pre>
*
* @param millis the amount of millis to subtract, may be negative
* @return the new time minus the increased millis
* @since 1.1
*/
public TimeOfDay minusMillis(int millis) {
return withFieldAdded(DurationFieldType.millis(), FieldUtils.safeNegate(millis));
}
/**
* Returns a copy of this time minus the specified number of seconds.
*
* <p>This time instance is immutable and unaffected by this method call.
*
* <p>The following three lines are identical in effect:
*
* <pre>
* TimeOfDay subtracted = dt.minusSeconds(6);
* TimeOfDay subtracted = dt.minus(Period.seconds(6));
* TimeOfDay subtracted = dt.withFieldAdded(DurationFieldType.seconds(), -6);
* </pre>
*
* @param seconds the amount of seconds to subtract, may be negative
* @return the new time minus the increased seconds
* @since 1.1
*/
public TimeOfDay minusSeconds(int seconds) {
return withFieldAdded(DurationFieldType.seconds(), FieldUtils.safeNegate(seconds));
}
/**
* Returns a copy of this time minus the specified number of hours.
*
* <p>This time instance is immutable and unaffected by this method call.
*
* <p>The following three lines are identical in effect:
*
* <pre>
* TimeOfDay subtracted = dt.minusHours(6);
* TimeOfDay subtracted = dt.minus(Period.hours(6));
* TimeOfDay subtracted = dt.withFieldAdded(DurationFieldType.hours(), -6);
* </pre>
*
* @param hours the amount of hours to subtract, may be negative
* @return the new time minus the increased hours
* @since 1.1
*/
public TimeOfDay minusHours(int hours) {
return withFieldAdded(DurationFieldType.hours(), FieldUtils.safeNegate(hours));
}
/**
* Returns a new instance with the hours value negated.
*
* @return the new period with a negated value
* @throws ArithmeticException if the result overflows an int
*/
public Hours negated() {
return Hours.hours(FieldUtils.safeNegate(getValue()));
}
/**
* Returns a new instance with the hours multiplied by the specified scalar.
*
* <p>This instance is immutable and unaffected by this method call.
*
* @param scalar the amount to multiply by, may be negative
* @return the new period multiplied by the specified scalar
* @throws ArithmeticException if the result overflows an int
*/
public Hours multipliedBy(int scalar) {
return Hours.hours(FieldUtils.safeMultiply(getValue(), scalar));
}
/**
* Returns a new instance with the specified number of hours taken away.
*
* <p>This instance is immutable and unaffected by this method call.
*
* @param hours the amount of hours to take away, may be negative
* @return the new period minus the specified number of hours
* @throws ArithmeticException if the result overflows an int
*/
public Hours minus(int hours) {
return plus(FieldUtils.safeNegate(hours));
}
/**
* 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));
}
/**
* Converts this period in hours to a period in seconds assuming a 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 hours are 60 minutes long and all minutes are 60 seconds long.
* This may not be true for some unusual chronologies. However, it is included as it is a useful
* operation for many applications and business rules.
*
* @return a period representing the number of seconds for this number of hours
* @throws ArithmeticException if the number of seconds is too large to be represented
*/
public Seconds toStandardSeconds() {
return Seconds.seconds(FieldUtils.safeMultiply(getValue(), DateTimeConstants.SECONDS_PER_HOUR));
}
/**
* Converts this period in hours to a period in minutes assuming a 60 minute hour.
*
* <p>This method allows you to convert between different types of period. However to achieve this
* it makes the assumption that all hours are 60 minutes long. This may not be true for some
* unusual chronologies. However, it is included as it is a useful operation for many applications
* and business rules.
*
* @return a period representing the number of minutes for this number of hours
* @throws ArithmeticException if the number of minutes is too large to be represented
*/
public Minutes toStandardMinutes() {
return Minutes.minutes(FieldUtils.safeMultiply(getValue(), DateTimeConstants.MINUTES_PER_HOUR));
}
