[GitHub] [commons-lang] aherbert commented on a diff in pull request #1062: Syntax for optional tokens in DurationFormatUtils

["aherbert (via GitHub)" <gi...@apache.org>]

aherbert commented on code in PR #1062:
URL: https://github.com/apache/commons-lang/pull/1062#discussion_r1251780977


##########
src/main/java/org/apache/commons/lang3/time/DurationFormatUtils.java:
##########
@@ -48,6 +48,13 @@
  * Token values are printed using decimal digits.
  * A token character can be repeated to ensure that the field occupies a certain minimum
  * size. Values will be left-padded with 0 unless padding is disabled in the method invocation.
+ * <br>
+ * Tokens can be marked as optional by surrounding them with brackets [ ]. These tokens will 
+ * only be printed if the token value is non-zero. Any literals within optional blocks will only be 
+ * printed if the nearest prior non-literal token value was non-zero.

Review Comment:
   It would be useful here to have a few examples in a `<pre>` block or a table. The purpose is to demonstrate that literals will be omitted and zero can return an empty string, e.g.
   ```java
   String format = "[d'd'H'h'm'm's's']";
   LongStream.of(0,
                 Duration.ofMinutes(1).toMillis(),
                 Duration.ofHours(2).toMillis(),
                 Duration.ofDays(3).toMillis())
       .forEach(millis -> System.out.println(DurationFormatUtils.formatDuration(millis, format)));
   ```
   prints
   ```
   
   1m
   2h
   3d
   ```
   Thus the use of optional tokens requires literals to make the format understandable. This is because trailing optional token are omitted when zero. For example this does not work to make a readable time:
   ```java
   String format = "[HH':'mm':']ss";
   LongStream.of(0, 
                 Duration.ofSeconds(1).toMillis(),
                 Duration.ofMinutes(2).toMillis(),
                 Duration.ofHours(3).toMillis())
       .forEach(millis -> System.out.println(DurationFormatUtils.formatDuration(millis, format)));
   ```
   prints
   ```
   00
   01
   02:
   03:
   ```
   not:
   ```
   00
   01
   02:00
   03:00:00
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@commons.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org