net.time4j

Class MachineTime.Formatter

java.lang.Object

net.time4j.format.TimeSpanFormatter<TimeUnit,MachineTime<TimeUnit>>

net.time4j.MachineTime.Formatter

Enclosing class:

MachineTime<U>

public static final class MachineTime.Formatter
extends TimeSpanFormatter<TimeUnit,MachineTime<TimeUnit>>

Non-localized and user-defined format for machine-time-durations based on a pattern containing some standard symbols and literals.

Example (printing a wall-time-like duration):

  MachineTime.Formatter f =
      MachineTime.Formatter.ofPattern("+hh:mm:ss");
  String s = f.print(MachineTime.of(27 * 3600 + 30 * 60 + 5, TimeUnit.SECONDS));
  System.out.println(s); // output: +27:30:05
 

Since:

3.26/4.22

See Also:

ofPattern(String)

Concurrency:

This class is immutable and can be used by multiple threads in parallel.

Method Summary

Modifier and Type	Method and Description
static MachineTime.Formatter	ofPattern(String pattern) Constructs a new instance of duration formatter.
void	print(TimeSpan<? super TimeUnit> duration, Appendable buffer) Creates a textual output of given duration and writes to the buffer.

Methods inherited from class net.time4j.format.TimeSpanFormatter

format, getPattern, getType, parse, parse

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

ofPattern

public static MachineTime.Formatter ofPattern(String pattern)

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 -
D	TimeUnit.DAYS
h	TimeUnit.HOURS
m	TimeUnit.MINUTES
s	TimeUnit.SECONDS
,	decimal separator, comma is preferred
.	decimal separator, dot is preferred
f	TimeUnit.NANOSECONDS as fraction, (1-9) chars
'	apostroph, for escaping literal chars
[]	optional section
{}	section with plural forms
#	placeholder for an optional digit
|	joins two parsing sections by or-logic

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. 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.

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: 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 plural category. The category OTHER must exist. Example:

  MachineTime.Formatter formatter =
      MachineTime.Formatter.ofPattern("{D: :en:ONE=day:OTHER=days}");
  String s = formatter.format(MachineTime.of(3, TimeUnit.DAYS));
  System.out.println(s); // output: 3 days
 

Numerical placeholders

The maximum numerical width is the sum of min width and the count of preceding #-chars. Example:

  MachineTime.Formatter formatter1 =
      MachineTime.Formatter.ofPattern("D");
  formatter1.format(MachineTime.of(123, TimeUnit.DAYS)); throws IllegalArgumentException

  MachineTime.Formatter formatter2 =
      MachineTime.Formatter.ofPattern("##D");
  String s = formatter2.format(MachineTime.of(123, TimeUnit.DAYS));
  System.out.println(s); // output: 123
 

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}"
 

Parameters:

pattern - format pattern

Returns:

new formatter instance

Throws:

IllegalArgumentException - in any case of pattern inconsistencies or failures

print

public void print(TimeSpan<? super TimeUnit> duration,
                  Appendable buffer)
           throws IOException

Creates a textual output of given duration and writes to the buffer.

Note: This method performs an automatical normalization such that the underlying format pattern will be respected in every possible way.

Overrides:

print in class TimeSpanFormatter<TimeUnit,MachineTime<TimeUnit>>

Parameters:

duration - duration object

buffer - I/O-buffer where the result is written to

Throws:

IllegalArgumentException - if some aspects of duration prevents printing (for example too many nanoseconds)

IOException - if writing into buffer fails