support for intervals surrounding instants

see issue #672

Author: MenoData

range/src/main/java/net/time4j/range/MomentInterval.java

@@ -45,6 +45,7 @@
 import net.time4j.format.expert.IsoDecimalStyle;
 import net.time4j.format.expert.ParseLog;
 import net.time4j.format.expert.SignPolicy;
+import net.time4j.scale.TimeScale;
 import net.time4j.tz.TZID;
 import net.time4j.tz.Timezone;
 import net.time4j.tz.ZonalOffset;
@@ -327,7 +328,7 @@ public static MomentInterval until(Instant end) {
      * @param   alignment   determines how to align the interval around moment (in range {@code 0.0 <= x <= 1.0})
      * @return  new moment interval
      * @throws  IllegalArgumentException if the duration is negative or the alignment is not finite or out of range
-     * @throws  UnsupportedOperationException if any given or calculated moment is before 1972
+     * @throws  UnsupportedOperationException if any given or calculated moment is before 1972 (only for SI-duration)
      * @see     #LEFT_ALIGNED
      * @see     #CENTERED
      * @see     #RIGHT_ALIGNED
@@ -348,26 +349,66 @@ public static MomentInterval until(Instant end) {
      * @param   alignment   determines how to align the interval around moment (in range {@code 0.0 <= x <= 1.0})
      * @return  new moment interval
      * @throws  IllegalArgumentException if the duration is negative or the alignment is not finite or out of range
-     * @throws  UnsupportedOperationException if any given or calculated moment is before 1972
+     * @throws  UnsupportedOperationException if any given or calculated moment is before 1972 (only for SI-duration)
      * @see     #LEFT_ALIGNED
      * @see     #CENTERED
      * @see     #RIGHT_ALIGNED
      * @since   3.34/4.29
      */
     public static MomentInterval surrounding(
         Moment moment,
-        MachineTime<SI> duration,
+        MachineTime<?> duration,
         double alignment
     ) {
 
-        if (alignment == 1.0) { // avoid possible rounding errors
-            return MomentInterval.between(moment.minus(duration), moment);
-        } else if ((Double.compare(alignment, 0.0) < 0) || (Double.compare(alignment, 1.0) > 0)) {
+        if ((Double.compare(alignment, 0.0) < 0) || (Double.compare(alignment, 1.0) > 0)) {
             throw new IllegalArgumentException("Out of range: " + alignment);
         }
 
-        Moment start = moment.minus(duration.multipliedBy(alignment));
-        return MomentInterval.between(start, start.plus(duration));
+        Moment start = subtract(moment, duration.multipliedBy(alignment));
+        return MomentInterval.between(start, (alignment == 1.0) ? moment : add(start, duration));
+
+    }
+
+    /**
+     * <p>Creates an interval surrounding given instant. </p>
+     *
+     * <p>Equivalent to {@link #surrounding(Moment, MachineTime, double)
+     * surrounding(Moment.from(instant), duration, alignment)}. </p>
+     *
+     * @param   instant     embedded instant at focus of alignment
+     * @param   duration    machine time duration
+     * @param   alignment   determines how to align the interval around instant (in range {@code 0.0 <= x <= 1.0})
+     * @return  new moment interval
+     * @throws  IllegalArgumentException if the duration is negative or the alignment is not finite or out of range
+     * @see     #LEFT_ALIGNED
+     * @see     #CENTERED
+     * @see     #RIGHT_ALIGNED
+     * @since   3.34/4.29
+     */
+    /*[deutsch]
+     * <p>Erzeugt ein Intervall, das den angegebenen Zeitpunkt umgibt. </p>
+     *
+     * <p>&Auml;quivalent zu {@link #surrounding(Moment, MachineTime, double)
+     * surrounding(Moment.from(instant), duration, alignment)}. </p>
+     *
+     * @param   instant     embedded instant at focus of alignment
+     * @param   duration    machine time duration
+     * @param   alignment   determines how to align the interval around instant (in range {@code 0.0 <= x <= 1.0})
+     * @return  new moment interval
+     * @throws  IllegalArgumentException if the duration is negative or the alignment is not finite or out of range
+     * @see     #LEFT_ALIGNED
+     * @see     #CENTERED
+     * @see     #RIGHT_ALIGNED
+     * @since   3.34/4.29
+     */
+    public static MomentInterval surrounding(
+        Instant instant,
+        MachineTime<TimeUnit> duration,
+        double alignment
+    ) {
+
+        return MomentInterval.surrounding(Moment.from(instant), duration, alignment);
 
     }
 
@@ -1499,6 +1540,38 @@ private static boolean hasSecondOffset(
 
     }
 
+    @SuppressWarnings("unchecked")
+    private static Moment add(
+        Moment moment,
+        MachineTime<?> duration
+    ) {
+
+        if (duration.getScale() == TimeScale.UTC) {
+            MachineTime<SI> mt = (MachineTime<SI>) duration;
+            return moment.plus(mt);
+        } else {
+            MachineTime<TimeUnit> mt = (MachineTime<TimeUnit>) duration;
+            return moment.plus(mt);
+        }
+
+    }
+
+    @SuppressWarnings("unchecked")
+    private static Moment subtract(
+        Moment moment,
+        MachineTime<?> duration
+    ) {
+
+        if (duration.getScale() == TimeScale.UTC) {
+            MachineTime<SI> mt = (MachineTime<SI>) duration;
+            return moment.minus(mt);
+        } else {
+            MachineTime<TimeUnit> mt = (MachineTime<TimeUnit>) duration;
+            return moment.minus(mt);
+        }
+
+    }
+
     /**
      * @serialData  Uses
      *              <a href="../../../serialized-form.html#net.time4j.range.SPX">

range/src/test/java/net/time4j/range/BasicMomentRangeTest.java

@@ -309,21 +309,42 @@ public void move() {
     }
 
     @Test
-    public void surroundingInterval() {
+    public void surroundingIntervalSI() {
         Moment moment = PlainTimestamp.of(2017, 9, 9, 10, 0).atUTC();
-        MachineTime<SI> duration = MachineTime.ofSIUnits(3600, 0);
+        MachineTime<SI> duration = MachineTime.ofSIUnits(5400, 0);
 
         MomentInterval centered = MomentInterval.surrounding(moment, duration, MomentInterval.CENTERED);
+        Moment startCentered = PlainTimestamp.of(2017, 9, 9, 9, 15).atUTC();
+        Moment endCentered = PlainTimestamp.of(2017, 9, 9, 10, 45).atUTC();
+        assertThat(centered, is(MomentInterval.between(startCentered, endCentered)));
+
+        MomentInterval left = MomentInterval.surrounding(moment, duration, MomentInterval.LEFT_ALIGNED);
+        Moment startLeft = PlainTimestamp.of(2017, 9, 9, 8, 30).atUTC();
+        Moment endLeft = PlainTimestamp.of(2017, 9, 9, 10, 0).atUTC();
+        assertThat(left, is(MomentInterval.between(startLeft, endLeft)));
+
+        MomentInterval right = MomentInterval.surrounding(moment, duration, MomentInterval.RIGHT_ALIGNED);
+        Moment startRight = PlainTimestamp.of(2017, 9, 9, 10, 0).atUTC();
+        Moment endRight = PlainTimestamp.of(2017, 9, 9, 11, 30).atUTC();
+        assertThat(right, is(MomentInterval.between(startRight, endRight)));
+    }
+
+    @Test
+    public void surroundingIntervalPOSIX() {
+        Instant instant = PlainTimestamp.of(2017, 9, 9, 10, 0).atUTC().toTemporalAccessor();
+        MachineTime<TimeUnit> duration = MachineTime.ofPosixUnits(3600, 0);
+
+        MomentInterval centered = MomentInterval.surrounding(instant, duration, MomentInterval.CENTERED);
         Moment startCentered = PlainTimestamp.of(2017, 9, 9, 9, 30).atUTC();
         Moment endCentered = PlainTimestamp.of(2017, 9, 9, 10, 30).atUTC();
         assertThat(centered, is(MomentInterval.between(startCentered, endCentered)));
 
-        MomentInterval left = MomentInterval.surrounding(moment, duration, MomentInterval.LEFT_ALIGNED);
+        MomentInterval left = MomentInterval.surrounding(instant, duration, MomentInterval.LEFT_ALIGNED);
         Moment startLeft = PlainTimestamp.of(2017, 9, 9, 9, 0).atUTC();
         Moment endLeft = PlainTimestamp.of(2017, 9, 9, 10, 0).atUTC();
         assertThat(left, is(MomentInterval.between(startLeft, endLeft)));
 
-        MomentInterval right = MomentInterval.surrounding(moment, duration, MomentInterval.RIGHT_ALIGNED);
+        MomentInterval right = MomentInterval.surrounding(instant, duration, MomentInterval.RIGHT_ALIGNED);
         Moment startRight = PlainTimestamp.of(2017, 9, 9, 10, 0).atUTC();
         Moment endRight = PlainTimestamp.of(2017, 9, 9, 11, 0).atUTC();
         assertThat(right, is(MomentInterval.between(startRight, endRight)));