Add method to round a DateTimeComponents

Fixes #954

src/changes/changes.xml

@@ -27,6 +27,9 @@
       <action dev="greyskyy" type="add">
         Added waypoint interpolation of PVCoordinatesProvider.
       </action>
+      <action dev="evan" type="add" issue="954">
+        Added method to round DateTimeComponents for custom formatting.
+      </action>
     </release>
     <release version="11.2.1" date="2022-08-01"
              description="Version 11.2.1 is a patch release of Orekit.

src/main/java/org/orekit/time/DateTimeComponents.java

@@ -315,8 +315,34 @@ public class DateTimeComponents implements Serializable, Comparable<DateTimeComp
                 new DecimalFormat("00", new DecimalFormatSymbols(Locale.US));
         secondsFormat.setMaximumFractionDigits(fractionDigits);
         secondsFormat.setMinimumFractionDigits(fractionDigits);
-        DateComponents roundedDate = this.date;
-        TimeComponents roundedTime = this.time;
+        final DateTimeComponents rounded = roundIfNeeded(minuteDuration, fractionDigits);
+        return rounded.getDate().toString() + 'T' +
+                rounded.getTime().toStringWithoutUtcOffset(secondsFormat);
+    }
+
+    /**
+     * Round this date-time to the given precision if needed to prevent rounding up to an
+     * invalid seconds number. This is useful, for example, when writing custom date-time
+     * formatting methods so one does not, e.g., end up with "60.0" seconds during a
+     * normal minute when the value of seconds is {@code 59.999}. This method will instead
+     * round up the minute, hour, day, month, and year as needed.
+     *
+     * @param minuteDuration 59, 60, 61, or 62 seconds depending on the date being close
+     *                       to a leap second introduction and the magnitude of the leap
+     *                       second.
+     * @param fractionDigits the number of decimal digits after the decimal point in the
+     *                       seconds number that will be printed. This date-time is
+     *                       rounded to {@code fractionDigits} after the decimal point if
+     *                       necessary to prevent rounding up to {@code minuteDuration}.
+     *                       {@code fractionDigits} must be greater than or equal to
+     *                       {@code 0}.
+     * @return a date-time within {@code 0.5 * 10**-fractionDigits} seconds of this, and
+     * with a seconds number that will not round up to {@code minuteDuration} when rounded
+     * to {@code fractionDigits} after the decimal point.
+     * @since 11.3
+     */
+    public DateTimeComponents roundIfNeeded(final int minuteDuration,
+                                            final int fractionDigits) {
         double second = time.getSecond();
         final double wrap = minuteDuration - 0.5 * FastMath.pow(10, -fractionDigits);
         if (second >= wrap) {
@@ -334,11 +360,11 @@ public class DateTimeComponents implements Serializable, Comparable<DateTimeComp
                     ++j2000;
                 }
             }
-            roundedDate = new DateComponents(j2000);
-            roundedTime = new TimeComponents(hour, minute, second);
+            return new DateTimeComponents(
+                    new DateComponents(j2000),
+                    new TimeComponents(hour, minute, second));
         }
-        return roundedDate.toString() + 'T' +
-                roundedTime.toStringWithoutUtcOffset(secondsFormat);
+        return this;
     }
 
     /**