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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
