Adding labels to split StopWatch feature

Author: edelgadoh

src/main/java/org/apache/commons/lang3/time/StopWatch.java

@@ -19,6 +19,9 @@
 
 import java.time.Duration;
 import java.time.Instant;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
 import java.util.Objects;
 import java.util.concurrent.TimeUnit;
 import java.util.function.Supplier;
@@ -27,6 +30,7 @@
 import org.apache.commons.lang3.function.FailableConsumer;
 import org.apache.commons.lang3.function.FailableRunnable;
 import org.apache.commons.lang3.function.FailableSupplier;
+import org.apache.commons.lang3.tuple.ImmutablePair;
 
 /**
  * {@link StopWatch} provides a convenient API for timings.
@@ -248,6 +252,11 @@ public static StopWatch createStarted() {
      */
     private long stopTimeNanos;
 
+    /**
+     * The split history list.
+     */
+    private List<Split> splitHistory;
+
     /**
      * Constructs a new instance.
      */
@@ -326,6 +335,16 @@ public String getMessage() {
         return message;
     }
 
+    /**
+     * Gets the split history list.
+     *
+     * @return the list of splits.
+     * @since 3.19.0
+     */
+    public List<Split> getSplitHistory() {
+        return Collections.unmodifiableList(splitHistory);
+    }
+
     /**
      * Gets the <em>elapsed</em> time in nanoseconds.
      *
@@ -557,6 +576,7 @@ private long nanosToMillis(final long nanos) {
     public void reset() {
         runningState = State.UNSTARTED;
         splitState = SplitState.UNSPLIT;
+        splitHistory = new ArrayList<>();
     }
 
     /**
@@ -626,6 +646,23 @@ public void split() {
         splitState = SplitState.SPLIT;
     }
 
+    /**
+     * <p>
+     * Captures the time in ns and records in a history list.
+     * The label specified is used to identify the current split.
+     * </p>
+     *
+     * @param label A message for string presentation.
+     * @throws IllegalStateException if the StopWatch is not running.
+     * @since 3.19.0
+     */
+    public void recordSplit(final String label) {
+        if (runningState != State.RUNNING) {
+            throw new IllegalStateException("Stopwatch is not running.");
+        }
+        splitHistory.add(new Split(label, System.nanoTime()));
+    }
+
     /**
      * Starts this StopWatch.
      *
@@ -645,6 +682,7 @@ public void start() {
         startTimeNanos = System.nanoTime();
         startInstant = Instant.now();
         runningState = State.RUNNING;
+        splitHistory = new ArrayList<>();
     }
 
     /**
@@ -746,4 +784,45 @@ public void unsplit() {
         splitState = SplitState.UNSPLIT;
     }
 
+    /**
+     * Class to store details of each split.
+     * @since 3.19.0
+     */
+    public static final class Split extends ImmutablePair<String, Long> {
+
+        /**
+         * Constructor with label and duration.
+         * @param label Label for this split.
+         * @param timeNanos time in ns.
+         */
+        public Split(String label, Long timeNanos) {
+            super(label, timeNanos);
+        }
+
+        /**
+         * Get the label of this split.
+         * @return label.
+         */
+        public String getLabel() {
+            return getLeft();
+        }
+
+        /**
+         * Get the time in nanoseconds.
+         * @return time in ns.
+         */
+        public Long getTimeNanos() {
+            return getRight();
+        }
+
+        /**
+         * Converts this instance to a handy string.
+         * @return this instance as a string.
+         */
+        @Override
+        public String toString() {
+            return String.format("Split [label=%s, timeNanos=%d])", getLabel(), getTimeNanos());
+        }
+    }
+
 }

src/test/java/org/apache/commons/lang3/time/StopWatchTest.java

@@ -26,6 +26,7 @@
 import java.io.IOException;
 import java.time.Duration;
 import java.time.Instant;
+import java.util.List;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicInteger;
 
@@ -500,6 +501,32 @@ void testToStringWithMessage() throws InterruptedException {
         assertEquals(SPLIT_CLOCK_STR_LEN + MESSAGE.length() + 1, splitStr.length(), "Formatted split string not the correct length");
     }
 
+    @Test
+    void testSplitsWithStringLabels() {
+        final StopWatch watch = new StopWatch();
+        final String firstLabel = "one";
+        final String secondLabel = "two";
+        final String thirdLabel = "three";
+        watch.start();
+        // starting splits
+        watch.recordSplit(firstLabel);
+        watch.recordSplit(secondLabel);
+        watch.recordSplit(thirdLabel);
+        watch.stop();
+        // getting splits
+        final List<StopWatch.Split> splits = watch.getSplitHistory();
+        // check size
+        assertEquals(3, splits.size());
+        // check labels
+        assertEquals(firstLabel, splits.get(0).getLabel());
+        assertEquals(secondLabel, splits.get(1).getLabel());
+        assertEquals(thirdLabel, splits.get(2).getLabel());
+        // check time in nanos
+        assertTrue(splits.get(0).getTimeNanos() > 0);
+        assertTrue(splits.get(1).getTimeNanos() > 0);
+        assertTrue(splits.get(2).getTimeNanos() > 0);
+    }
+
     private int throwIOException() throws IOException {
         throw new IOException("A");
     }