public Duration subtract (Duration rhs)

Computes a new duration whose value is this-rhs.

For example:

 "1 day" - "-3 days" = "4 days"
 "1 year" - "1 day" = IllegalStateException
 "-(1 hour,50 minutes)" - "-20 minutes" = "-(1hours,30 minutes)"
 "15 hours" - "-3 days" = "3 days and 15 hours"
 "1 year" - "-1 day" = "1 year and 1 day"
 

Since there's no way to meaningfully subtract 1 day from 1 month, there are cases where the operation fails in IllegalStateException.

Formally the computation is defined as follows. First, we can assume that two Durations are both positive without losing generality. (i.e., (-X)-Y=-(X+Y), X-(-Y)=X+Y, (-X)-(-Y)=-(X-Y))

Then two durations are subtracted field by field. If the sign of any non-zero field F is different from the sign of the most significant field, 1 (if F is negative) or -1 (otherwise) will be borrowed from the next bigger unit of F.

This process is repeated until all the non-zero fields have the same sign.

If a borrow occurs in the days field (in other words, if the computation needs to borrow 1 or -1 month to compensate days), then the computation fails by throwing an IllegalStateException.

Parameters:
rhs    Duration to subtract from this Duration.

Returns:  New Duration created from subtracting rhs from this Duration.

Exceptions:
IllegalStateException     If two durations cannot be meaningfully subtracted. For example, subtracting one day from one month causes this exception.
NullPointerException     If the rhs parameter is null.

See also:
add(Duration)