net.time4j

Class Duration.Formatter<U extends IsoUnit>

java.lang.Object

net.time4j.Duration.Formatter<U>

Type Parameters:

U - generic type of time units

Enclosing class:

Duration<U extends IsoUnit>

public static final class Duration.Formatter<U extends IsoUnit>
extends Object

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

Note: For storing purposes users should normally use the canonical or ISO- or XML-representation of a duration, not this custom format. Otherwise, if users want a localized output then the class PrettyTime is usually the best choice. This class is mainly designed for handling non-standardized formats.

First example (parsing a Joda-Time-Period):

  String jodaPattern =
      "'P'[-Y'Y'][-M'M'][-W'W'][-D'D']['T'[-h'H'][-m'M']]";
  Duration.Formatter<IsoUnit> f =
      Duration.Formatter.ofPattern(IsoUnit.class, jodaPattern);
  Duration<?> dur = f.parse("P-2Y-15DT-30H-5M");
  System.out.println(dur); // output: -P2Y15DT30H5M
 

Second example (printing a wall-time-like duration):

  Duration.Formatter<ClockUnit> f =
      Duration.Formatter.ofPattern(ClockUnit.class, "+hh:mm:ss");
  String s = f.print(Duration.ofClockUnits(27, 30, 5));
  System.out.println(s); // output: +27:30:05
 

Since:

1.2

See Also:

Duration.toString(), Duration.parse(String), ofPattern(Class, String)

Method Summary

Methods

Modifier and Type	Method and Description
String	format(Duration<?> duration) Creates a textual output of given duration.
String	getPattern() Liefert das zugrundeliegende Formatmuster.
Class<U>	getType() Liefert den zugehörigen Zeiteinheitstyp.
static <U extends IsoUnit> Duration.Formatter<U>	ofPattern(Class<U> type, String pattern) Constructs a new instance of duration formatter.
static Duration.Formatter<IsoUnit>	ofPattern(String pattern) Equivalent to ofPattern(IsoUnit.class, pattern).
Duration<U>	parse(CharSequence text) Equivalent to parse(text, 0).
Duration<U>	parse(CharSequence text, int offset) Analyzes given text according to format pattern and parses the text to a duration.
void	print(Duration<?> duration, Appendable buffer) Creates a textual output of given duration and writes to the buffer.

Methods inherited from class java.lang.Object

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

Method Detail

ofPattern

public static Duration.Formatter<IsoUnit> ofPattern(String pattern)

Equivalent to ofPattern(IsoUnit.class, pattern).

Parameters:

pattern - format pattern

Returns:

new formatter instance

Since:

1.2

See Also:

ofPattern(Class, String)

ofPattern

public static <U extends IsoUnit> Duration.Formatter<U> ofPattern(Class<U> type,
                                                  String pattern)

Constructs a new instance of duration formatter.

Uses a pattern with symbols as followed:

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 for parsing
#{}	reserved chars for future use

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. If necessary a number (of units) will be padded from left with the zero digt. Optional sections let the parser be error-tolerant and continue with the next section in case of errors.

Type Parameters:

U - generic unit type

Parameters:

type - reified unit type

pattern - format pattern

Returns:

new formatter instance

Since:

1.2

getPattern

public String getPattern()

Liefert das zugrundeliegende Formatmuster.

Returns:

String

Since:

1.2

getType

public Class<U> getType()

Liefert den zugehörigen Zeiteinheitstyp.

Returns:

Class

Since:

1.2

format

public String format(Duration<?> duration)

Creates a textual output of given duration.

Parameters:

duration - duration object

Returns:

textual represenation of duration

Throws:

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

Since:

1.2

print

public void print(Duration<?> duration,
         Appendable buffer)
           throws IOException

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

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

Since:

1.2

parse

public Duration<U> parse(CharSequence text)
                                  throws ParseException

Equivalent to parse(text, 0).

Parameters:

text - custom textual representation to be parsed

Returns:

parsed duration

Throws:

ParseException - (for example in case of mixed signs)

Since:

1.2

See Also:

parse(CharSequence, int)

parse

public Duration<U> parse(CharSequence text,
                int offset)
                                  throws ParseException

Analyzes given text according to format pattern and parses the text to a duration.

Parameters:

text - custom textual representation to be parsed

offset - start position for the parser

Returns:

parsed duration

Throws:

ParseException - (for example in case of mixed signs)

Since:

1.2