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

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
Author:
Meno Hochschild

  • Method Details

    • 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​(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​(CharSequence text) throws ParseException

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

      Specified by:
      parse in interface ChronoParser<T extends ChronoEntity<T>>
      Parameters:
      text - text to be parsed
      Returns:
      parse result
      Throws:
      IndexOutOfBoundsException - if the text is empty
      ParseException - if the text is not parseable
      Since:
      3.14/4.11
      See Also:
      parse(CharSequence, ParseLog)

    • parse

      public T parse​(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).

      Specified by:
      parse in interface ChronoParser<T extends ChronoEntity<T>>
      Parameters:
      text - text to be parsed
      status - parser information (always as new instance)
      Returns:
      result or null if parsing does not work
      Throws:
      IndexOutOfBoundsException - if the start position is at end of text or even behind
      Since:
      3.14/4.11

    • parse

      public T parse​(CharSequence text, ParseLog status, AttributeQuery attributes)
      Description copied from interface: ChronoParser

      Interpretes given text as chronological entity starting at the specified position 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