net.time4j.format.expert

Class MultiFormatParser<T extends ChronoEntity<T>>

java.lang.Object

net.time4j.format.expert.MultiFormatParser<T>

Type Parameters:

T - generic type of chronological entity

All Implemented Interfaces:

ChronoParser<T>

public final class MultiFormatParser<T extends ChronoEntity<T>>
extends java.lang.Object
implements ChronoParser<T>

Serves for parsing of text input whose format is not yet known at compile time.

User who only need to parse different formats for one locale only might consider the simple alternative to concatenate all format pattern strings into one pattern with the "|"-symbol as separator.

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

General notes about usage:

a) If two patterns or formatters are combined then the order must be from the most complete pattern/formatter to the least complete one. Example: Use "MM/dd/yyyy HH:mm|MM/dd/yyyy" and not "MM/dd/yyyy|MM/dd/yyyy HH:mm". This is especially important if the formatter in question use default values because the single components will be processed before evaluating any default values (which is a late step in parsing).

b) If two patterns/formatters have the same degree of completeness then that component should be noted first which is more likely to be expected in input.

Since:

3.14/4.11

Method Summary

Modifier and Type	Method and Description
static <T extends ChronoEntity<T>> MultiFormatParser<T>	of(ChronoFormatter<T>... formats) Creates a new multiple format parser.
static <T extends ChronoEntity<T>> MultiFormatParser<T>	of(java.util.List<ChronoFormatter<T>> formats) Creates a new multiple format parser.
T	parse(java.lang.CharSequence text) Interpretes given text as chronological entity starting at the begin of text.
T	parse(java.lang.CharSequence text, ParseLog status) Interpretes given text as chronological entity starting at the specified position in parse log.
T	parse(java.lang.CharSequence text, ParseLog status, AttributeQuery attributes) Interpretes given text starting at the position defined in parse-log.

Methods inherited from class java.lang.Object

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

Method Detail

of

@SafeVarargs
public static <T extends ChronoEntity<T>> MultiFormatParser<T> of(ChronoFormatter<T>... formats)

Creates a new multiple format parser.

Type Parameters:

T - generic type of chronological entity

Parameters:

formats - array of multiple formats

Returns:

new immutable instance of MultiFormatParser

Since:

3.14/4.11

of

public static <T extends ChronoEntity<T>> MultiFormatParser<T> of(java.util.List<ChronoFormatter<T>> formats)

Creates a new multiple format parser.

Type Parameters:

T - generic type of chronological entity

Parameters:

formats - list of multiple formats

Returns:

new immutable instance of MultiFormatParser

Since:

3.14/4.11

parse

public T parse(java.lang.CharSequence text)
        throws java.text.ParseException

Interpretes given text as chronological entity starting at the begin of text.

Parameters:

text - text to be parsed

Returns:

parse result

Throws:

java.lang.IndexOutOfBoundsException - if the text is empty

java.text.ParseException - if the text is not parseable

Since:

3.14/4.11

See Also:

parse(CharSequence, ParseLog)

parse

public T parse(java.lang.CharSequence text,
               ParseLog status)

Interpretes given text as chronological entity starting at the specified position in parse log.

Following example demonstrates best coding practice if used in processing bulk data:

     static final MultiFormatParser<PlainDate> MULTI_FORMAT_PARSER;

     static {
         ChronoFormatter<PlainDate> germanStyle =
              ChronoFormatter.ofDatePattern("d. MMMM uuuu", PatternType.CLDR, Locale.GERMAN);
         ChronoFormatter<PlainDate> frenchStyle =
              ChronoFormatter.ofDatePattern("d. MMMM uuuu", PatternType.CLDR, Locale.FRENCH);
         ChronoFormatter<PlainDate> usStyle =
              ChronoFormatter.ofDatePattern("MM/dd/uuuu", PatternType.CLDR, Locale.US);
         MULTI_FORMAT_PARSER = MultiFormatParser.of(germanStyle, frenchStyle, usStyle);
     }

     public Collection<PlainDate> parse(Collection<String> data) {
         Collection<PlainDate> parsedDates = new ArrayList<>();
         ParseLog plog = new ParseLog();
         int index = 0;

         for (String text : data) {
             PlainDate date = MULTI_FORMAT_PARSER.parse(text, plog);
             if ((date == null) || plog.isError()) {
                 // users are encouraged to use any good logging framework here
                 System.out.println("Wrong entry found: " + text + " at position " + index);
             } else {
                 parsedDates.add(date);
             }
             index++;
         }

         return Collections.unmodifiableCollection(parsedDates);
     }
 

Note: This method tolerates trailing characters. If this behaviour is not useful then please consider the alternative method parse(CharSequence).

Parameters:

text - text to be parsed

status - parser information (always as new instance)

Returns:

result or null if parsing does not work

Throws:

java.lang.IndexOutOfBoundsException - if the start position is at end of text or even behind

Since:

3.14/4.11

parse

public T parse(java.lang.CharSequence text,
               ParseLog status,
               AttributeQuery attributes)

Description copied from interface: ChronoParser

Interpretes given text starting at the position defined in parse-log.

Implementation note: Any implementation will parse the text first at the position status.getPosition() and then set the new position in the parse log if successful. In case of error the error index in the parse log will be updated instead.

Specified by:

parse in interface ChronoParser<T extends ChronoEntity<T>>

Parameters:

text - text to be parsed

status - parser information (always as new instance)

attributes - control attributes

Returns:

result or null if parsing does not work