Constructs a new instance of duration formatter.
Uses a pattern with symbols as followed:
Legend
Symbol | Description |
+ | sign of duration, printing + or - |
- | sign of duration, printing only - |
I |
CalendarUnit#MILLENNIA |
C |
CalendarUnit#CENTURIES |
E |
CalendarUnit#DECADES |
Y |
CalendarUnit#YEARS |
Q |
CalendarUnit#QUARTERS |
M |
CalendarUnit#MONTHS |
W |
CalendarUnit#WEEKS |
D |
CalendarUnit#DAYS |
h |
ClockUnit#HOURS |
m |
ClockUnit#MINUTES |
s |
ClockUnit#SECONDS |
, | decimal separator, comma is preferred |
. | decimal separator, dot is preferred |
f |
ClockUnit#NANOS as fraction, (1-9) chars |
' | apostroph, for escaping literal chars |
[] | optional section |
{} | section with plural forms, since v2.0 |
# | placeholder for an optional digit, since v3.0 |
| | joins two parsing sections by or-logic, since v3.26/4.22 |
All letters in range a-z and A-Z are always reserved chars
and must be escaped by apostrophes for interpretation as literals.
If such a letter is repeated then the count of symbols controls
the minimum width for formatted output. Such a minimum width also
reserves this area for parsing of any preceding item. If necessary a
number (of units) will be padded from left with the zero digit. The
unit symbol (with exception of "f") can be preceded by
any count of char "#" (>= 0). The sum of min width and
count of #-chars define the maximum width for formatted output and
parsing.
Optional sections
Optional sections enclosed by square brackets let the parser be error-tolerant
and continue with the next section in case of errors. Since v2.3: During printing,
an optional section will only be printed if there is any non-zero part. When parsing
an optional section will be skipped if the input to be parsed does not match the
expected pattern. For example: An input missing the hour part can be handled when
an optional section is applied on the hour part.
Enhancement since version v2.0: plural forms
Every expression inside curly brackets represents a combination
of amount, separator and pluralized unit name and has following
syntax:
{[symbol]:[separator]:[locale]:[CATEGORY=LITERAL][:...]}
The symbol is one of following chars:
I, C, E, Y, Q, M, W, D, h, m, s, f (legend see table above)
Afterwards the definition of separator chars follows. The
empty separator (represented by zero space between colons) is
permitted, too. The next section denotes the locale necessary
for determination of suitable plural rules. The form
[language]-[country]-[variant] can be used, for example
"en-US" or "en_US". At least the language
must be present. The underscore is an acceptable alternative
for the minus-sign. Finally there must be a sequence of
name-value-pairs in the form CATEGORY=LITERAL. Every category
label must be the name of a
net.time4j.format.PluralCategory.
The category OTHER must exist. Example:
Duration.Formatter<CalendarUnit> formatter =
Duration.Formatter.ofPattern(
CalendarUnit.class,
"{D: :en:ONE=day:OTHER=days}");
String s = formatter.format(Duration.of(3, DAYS));
System.out.println(s); // output: 3 days
Enhancement since version v3.0: numerical placeholders
Before version v3.0, the maximum numerical width was always 18. Now it is
the sum of min width and the count of preceding #-chars. Example:
Duration.Formatter<CalendarUnit> formatter1 =
Duration.Formatter.ofPattern(CalendarUnit.class, "D");
formatter1.format(Duration.of(123, DAYS)); throws IllegalArgumentException
Duration.Formatter<CalendarUnit> formatter2 =
Duration.Formatter.ofPattern(CalendarUnit.class, "##D");
String s = formatter2.format(Duration.of(123, DAYS));
System.out.println(s); // output: 123
Enhancement since version v3.26/4.22: or-logic
The character "|" starts a new section which will not be used for printing
but parsing in case of preceding errors. For example, following pattern enables parsing
a duration in days for two different languages:
"{D: :en:ONE=day:OTHER=days}|{D: :de:ONE=Tag:OTHER=Tage}"