Class DateTimeFormatter


  • public final class DateTimeFormatter
    extends java.lang.Object
    Formatter for printing and parsing calendricals.

    This class provides the main application entry point for printing and parsing. Instances of DateTimeFormatter are constructed using DateTimeFormatterBuilder or by using one of the predefined constants on DateTimeFormatters.

    Some aspects of printing and parsing are dependent on the locale. The locale can be changed using the withLocale(Locale) method which returns a new formatter in the requested locale.

    Not all formatters can print and parse. Some can only print, while others can only parse. The isPrintSupported() and isParseSupported() methods determine which operations are available.

    Some applications may need to use the older Format class for formatting. The toFormat() method returns an implementation of the old API.

    DateTimeFormatter is immutable and thread-safe.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      (package private) class  DateTimeFormatter.ClassicFormat
      Implements the classic Java Format API.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      (package private) static void checkNotNull​(java.lang.Object object, java.lang.String errorMessage)
      Validates that the input value is not null.
      java.util.Locale getLocale()
      Gets the locale to be used during formatting.
      boolean isParseSupported()
      Checks whether this formatter can parse.
      boolean isPrintSupported()
      Checks whether this formatter can print.
      CalendricalMerger parse​(java.lang.String text)
      Fully parses the text returning a merger that can be used to manage the merging of separate parsed fields to a meaningful calendrical.
      DateTimeParseContext parse​(java.lang.String text, java.text.ParsePosition position)
      Parses the text into a Calendrical.
      <T> T parse​(java.lang.String text, CalendricalRule<T> rule)
      Fully parses the text producing an object of the type defined by the rule.
      java.lang.String print​(Calendrical calendrical)
      Prints the calendrical using this formatter.
      void print​(Calendrical calendrical, java.lang.Appendable appendable)
      Prints the calendrical to an Appendable using this formatter.
      java.text.Format toFormat()
      Returns this formatter as a java.text.Format instance.
      (package private) CompositePrinterParser toPrinterParser​(boolean optional)
      Returns the formatter as a composite printer parser.
      java.lang.String toString()
      Returns a description of the underlying formatters.
      DateTimeFormatter withLocale​(java.util.Locale locale)
      Returns a copy of this DateTimeFormatter with a new locale.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • DateTimeFormatter

        DateTimeFormatter​(java.util.Locale locale,
                          CompositePrinterParser printerParser)
        Constructor.
        Parameters:
        locale - the locale to use for text formatting, not null
        printerParser - the printer/parser to use, not null
      • DateTimeFormatter

        private DateTimeFormatter​(DateTimeFormatSymbols symbols,
                                  CompositePrinterParser printerParser)
        Constructor used by immutable copying.
        Parameters:
        symbols - the symbols to use for text formatting, not null
        asciiNumerics - whether to use ASCII numerics (true) or locale numerics (false)
        printerParser - the printer/parser to use, not null
    • Method Detail

      • checkNotNull

        static void checkNotNull​(java.lang.Object object,
                                 java.lang.String errorMessage)
        Validates that the input value is not null.
        Parameters:
        object - the object to check
        errorMessage - the error to throw
        Throws:
        java.lang.NullPointerException - if the object is null
      • getLocale

        public java.util.Locale getLocale()
        Gets the locale to be used during formatting.
        Returns:
        the locale of this DateTimeFormatter, never null
      • withLocale

        public DateTimeFormatter withLocale​(java.util.Locale locale)
        Returns a copy of this DateTimeFormatter with a new locale.

        This instance is immutable and unaffected by this method call.

        Parameters:
        locale - the new locale, not null
        Returns:
        a new DateTimeFormatter with the same format and the new locale, never null
      • isPrintSupported

        public boolean isPrintSupported()
        Checks whether this formatter can print.

        Depending on how this formatter is initialized, it may not be possible for it to print at all. This method allows the caller to check whether the print methods will throw UnsupportedOperationException or not.

        Returns:
        true if the formatter supports printing
      • print

        public java.lang.String print​(Calendrical calendrical)
        Prints the calendrical using this formatter.

        This method prints the calendrical to a String.

        Parameters:
        calendrical - the calendrical to print, not null
        Returns:
        the printed string, never null
        Throws:
        java.lang.UnsupportedOperationException - if this formatter cannot print
        java.lang.NullPointerException - if the calendrical is null
        CalendricalPrintException - if an error occurs during printing
      • print

        public void print​(Calendrical calendrical,
                          java.lang.Appendable appendable)
        Prints the calendrical to an Appendable using this formatter.

        This method prints the calendrical to the specified Appendable. Appendable is a general purpose interface that is implemented by all key character output classes including StringBuffer, StringBuilder, PrintStream and Writer.

        Although Appendable methods throw an IOException, this method does not. Instead, any IOException is wrapped in a runtime exception. See CalendricalPrintException.rethrowIOException() for a means to extract the IOException.

        Parameters:
        calendrical - the calendrical to print, not null
        appendable - the appendable to print to, not null
        Throws:
        java.lang.UnsupportedOperationException - if this formatter cannot print
        java.lang.NullPointerException - if the calendrical or appendable is null
        CalendricalPrintException - if an error occurs during printing
      • isParseSupported

        public boolean isParseSupported()
        Checks whether this formatter can parse.

        Depending on how this formatter is initialized, it may not be possible for it to parse at all. This method allows the caller to check whether the parse methods will throw UnsupportedOperationException or not.

        Returns:
        true if the formatter supports parsing
      • parse

        public <T> T parse​(java.lang.String text,
                           CalendricalRule<T> rule)
        Fully parses the text producing an object of the type defined by the rule.

        This parses the entire text to produce the required calendrical value. For example:

         LocalDateTime dt = parser.parse(str, LocalDateTime.rule());
         
        If the parse completes without reading the entire length of the text, or a problem occurs during parsing or merging, then an exception is thrown.
        Parameters:
        text - the text to parse, not null
        Returns:
        the parsed date, never null
        Throws:
        java.lang.UnsupportedOperationException - if this formatter cannot parse
        java.lang.NullPointerException - if the text is null
        CalendricalParseException - if the parse fails
      • parse

        public CalendricalMerger parse​(java.lang.String text)
        Fully parses the text returning a merger that can be used to manage the merging of separate parsed fields to a meaningful calendrical.

        If the parse completes without reading the entire length of the text, or a problem occurs during parsing, then an exception is thrown.

        The result may be invalid including out of range values such as a month of 65. The methods on the calendrical allow you to handle the invalid input. For example:

         LocalDateTime dt = parser.parse(str).merge().get(LocalDateTime.rule());
         
        Parameters:
        text - the text to parse, not null
        Returns:
        the parsed text, never null
        Throws:
        java.lang.UnsupportedOperationException - if this formatter cannot parse
        java.lang.NullPointerException - if the text is null
        CalendricalParseException - if the parse fails
      • parse

        public DateTimeParseContext parse​(java.lang.String text,
                                          java.text.ParsePosition position)
        Parses the text into a Calendrical.

        The result may be invalid including out of range values such as a month of 65. The methods on the calendrical allow you to handle the invalid input. For example:

         LocalDateTime dt = parser.parse(str).mergeStrict().toLocalDateTime();
         
        Parameters:
        text - the text to parse, not null
        position - the position to parse from, updated with length parsed and the index of any error, not null
        Returns:
        the parsed text, null only if the parse results in an error
        Throws:
        java.lang.UnsupportedOperationException - if this formatter cannot parse
        java.lang.NullPointerException - if the text or position is null
        java.lang.IndexOutOfBoundsException - if the position is invalid
      • toPrinterParser

        CompositePrinterParser toPrinterParser​(boolean optional)
        Returns the formatter as a composite printer parser.
        Parameters:
        optional - whether the printer/parser should be optional
        Returns:
        the printer/parser, never null
      • toFormat

        public java.text.Format toFormat()
        Returns this formatter as a java.text.Format instance.

        The Format instance will print any Calendrical and parses to a merged CalendricalMerger.

        The format will throw UnsupportedOperationException and IndexOutOfBoundsException in line with those thrown by the print and parse methods.

        The format does not support attributing of the returned format string.

        Returns:
        this formatter as a classic format instance, never null
      • toString

        public java.lang.String toString()
        Returns a description of the underlying formatters.
        Overrides:
        toString in class java.lang.Object
        Returns:
        the pattern that will be used, never null