Package com.addicticks.texttime.formatters

Class DateTimeFormatterISO

  • public class DateTimeFormatterISO
extends Object
    Formatter-Parsers for ISO 8601 date and time values.

    These classes complement those in the JDK and provide additional features such as accepting a space as a the separator between the date and the time value and accepting the absence of the timezone offset.

    Predefined Formatters-Parsers overview

    Predefined Formatters
    Formatter Usage Description Examples
    ISO_OFFSET_DATE_TIME_PARSER Parsing For ISO-8601 date/time value parsing with mandatory offset '2018-12-03T10:15:30+01:00'
    '2018-12-03 10:15:30+01:00'
    '2018-12-03T10:15:30+01'
    '2018-12-03t10:15:30+01'
    '2018-12-03T10:15:30Z'
    '2018-12-03T10:15:30z'
    ISO_OPT_OFFSET_DATE_TIME_PARSER Parsing For ISO-8601 date/time value parsing with optional offset '2018-12-03T10:15:30+01:00'
    '2018-12-03 10:15:30+01:00'
    '2018-12-03T10:15:30+01'
    '2018-12-03t10:15:30+01'
    '2018-12-03T10:15:30Z'
    '2018-12-03T10:15:30z'
    '2018-12-03T10:15:30'
    ISO_OPT_OFFSET_DATE_PARSER Parsing For ISO-8601 date value parsing with optional offset '2018-12-03+01:00'
    '2018-12-03+01'
    '2018-12-03Z'
    '2018-12-03z'
    '2018-12-03'
    ISO_OPT_OFFSET_TIME_PARSER Parsing For ISO-8601 time value parsing with optional offset '10:15:30+01:00'
    '10:15:30+01'
    '10:15:30Z'
    '10:15:30z'
    '10:15:30'

    Parsing

    This class also provides convenience methods for parsing ISO-8601 date/time string values with optional offset.

    Formatting

    For producing ISO-8601 compliant string values you can simply use the classes in the JDK.
    See Also:
    Wikipedia ISO 8601

    • Field Detail

      • ISO_OFFSET_DATE_TIME_PARSER

        public static final DateTimeFormatter ISO_OFFSET_DATE_TIME_PARSER
        For parsing of ISO 8601 date-time values with mandatory offset.

        This Formatter-Parser is similar to the JDK's ISO_OFFSET_DATE_TIME except that while parsing it also accepts a space as the separator between the date and the time value (see note below).

        This Formatter-Parser is primarily intended for parsing. For formatting the JDK's ISO_OFFSET_DATE_TIME is a better option.

        Parsing
        This class is only intended for the use-case where the timezone offset is mandatory in the input and the absence of same will generate an exception. Very often the presence of the timezone offset cannot be guaranteed and in this case it is much better to use ISO_OPT_OFFSET_DATE_TIME_PARSER instead.

        There are two methods for parsing a date-time string with mandatory offset into an OffsetDateTime depending on your scenario:

        1. Use the static parse() method on this class. This method gracefully handles the situation where there are more then 9 digits on the seconds fractional value.
        2. Use this DateTimeFormatter directly: 
                     OffsetDateTime value 
               = DateTimeFormatterISO.ISO_OPT_OFFSET_DATE_TIME_PARSER.parse("2018-03-19:22:35:58", OffsetDateTime::from);


        Note: The date-time pattern where a space is used to separate the date and the time value is not a pattern which should be encouraged except perhaps for display purpose. The pattern is allowed in the ISO 8601 specification (allowed as an exception: "by mutual agreement of the partners in information interchange"), but it is strictly forbidden in the definition of xs:dateTime in the XML Schema Specification and also strictly forbidden in the W3C Date and Time Format. In conclusion: The pattern may be justifiable for display purpose, but for data exchange purpose the separator should always be an upper-case 'T'.

        See Also:
        DateTimeFormatter.ISO_OFFSET_DATE_TIME

      • ISO_OPT_OFFSET_DATE_TIME_PARSER

        public static final DateTimeFormatter ISO_OPT_OFFSET_DATE_TIME_PARSER
        For parsing of ISO 8601 date-time values with optional offset.

        This Formatter-Parser is similar to ISO_OFFSET_DATE_TIME_PARSER, however with the following extra features:

        • The timezone offset is optional while parsing.
        • The delimiter between the date and time value can optionally be a space character (see note below).

        This Formatter-Parser is primarily intended for parsing. For formatting the JDK's ISO_OFFSET_DATE_TIME is a better option.

        Parsing
        There are two methods for parsing a string into an OffsetDateTime depending on your scenario:

        1. Use the static parse() method on this class. This method gracefully handles the situation where there are more then 9 digits on the seconds fractional value.
        2. Creating a new DateTimeFormatter based on this one, but with a default ZoneId which is used during parsing if none is provided in the input. 
                     // This only need to be created once and can be re-used
           // (DateTimeFormatters are immutable and thread-safe)
           DateTimeFormatter dtf = DateTimeFormatterISO.ISO_OPT_OFFSET_DATE_TIME_PARSER.withZone(ZoneId.of("America/New_York"));
           // Parse the string value. Since no offset is given in the input, the New York TZ is assumed.
           OffsetDateTime value = dtf.parse("2018-03-19:22:35:58", OffsetDateTime::from);


        Note: The date-time pattern where a space is used to separate the date and the time value is not a pattern which should be encouraged except perhaps for display purpose. The pattern is allowed in the ISO 8601 specification (allowed as an exception: "by mutual agreement of the partners in information interchange"), but it is strictly forbidden in the definition of xs:dateTime in the XML Schema Specification and also strictly forbidden in the W3C Date and Time Format. In conclusion: The pattern may be justifiable for display purpose, but for data exchange purpose the separator should always be an upper-case 'T'.

        See Also:
        ISO_OFFSET_DATE_TIME_PARSER, DateTimeFormatter.ISO_OFFSET_DATE_TIME

      • ISO_OPT_OFFSET_DATE_PARSER

        public static final DateTimeFormatter ISO_OPT_OFFSET_DATE_PARSER
        For parsing of ISO 8601 date values with optional offset.

        This Formatter-Parser is similar to the JDK's DateTimeFormatter.ISO_OFFSET_DATE except that the timezone offset is optional while parsing.

        This Formatter-Parser is primarily intended for parsing. For formatting the JDK's DateTimeFormatter.ISO_OFFSET_DATE is a better option.

        Parsing
        There are two methods for parsing a date string into an OffsetDate/OffsetDateTime depending on your scenario:

        1. Use either of the static methods: on this class.
        2. Creating a new DateTimeFormatter based on this one, but with a default ZoneId which is used during parsing if none is provided in the input. 
                     // This only need to be created once and can be re-used
           // (DateTimeFormatters are immutable and thread-safe)
           DateTimeFormatter dtf = DateTimeFormatterISO.ISO_OPT_OFFSET_DATE_PARSER.withZone(ZoneId.of("America/New_York"));
           // Parse the string value. Since no offset is given in the input, the New York TZ is assumed.
           OffsetDate value = dtf.parse("2018-03-19", OffsetDate::from);

      • ISO_OPT_OFFSET_TIME_PARSER

        public static final DateTimeFormatter ISO_OPT_OFFSET_TIME_PARSER
        For parsing of ISO 8601 time values with optional offset.

        This Formatter-Parser is similar to the JDK's DateTimeFormatter.ISO_OFFSET_TIME except that the timezone offset is optional while parsing.

        This Formatter-Parser is primarily intended for parsing. For formatting the JDK's DateTimeFormatter.ISO_OFFSET_TIME is a better option.

        Parsing
        There are two methods for parsing a string into an OffsetTime depending on your scenario:

        1. Use the static parse() on this class. This method gracefully handles the situation where there are more then 9 digits on the seconds fractional value.
        2. Creating a new DateTimeFormatter based on this one, but with a default ZoneId which is used during parsing if none is provided in the input. 
                     // This only need to be created once and can be re-used
           // (DateTimeFormatters are immutable and thread-safe)
           DateTimeFormatter dtf = DateTimeFormatterISO.ISO_OPT_OFFSET_TIME_PARSER.withZone(ZoneId.of("America/New_York"));
           // Parse the string value. Since no offset is given in the input, the New York TZ is assumed.
           OffsetTime value = dtf.parse("22:33:58", OffsetTime::from);

    • Method Detail

      • parseIntoOffsetDateTime

        public static OffsetDateTime parseIntoOffsetDateTime​(String str)
        Parses an ISO-8601 date-time string with offset into an OffsetDateTime. For example a string on the form "2018-12-03T10:15:30+01:00". The timezone offset part is mandatory in the input.

        The string is parsed using ISO_OFFSET_DATE_TIME_PARSER.

        Furthermore, parsing is attempted in a two-step procedure: If first parsing attempt fails the method will evaluate if the problem is something which can likely be fixed and if so it will "fix" the input value, str, and perform a new parsing attempt.

        Parameters:
        str - the string to parse
        Returns:
        parsed value
        Throws:
        DateTimeParseException - if unable to parse the string, for example if the string has no timezone offset.

      • parseIntoOffsetDateTime

        public static OffsetDateTime parseIntoOffsetDateTime​(String str,
                                                     Function<LocalDateTime,​ZoneOffset> zoneOffsetProvider)
        Parses an ISO-8601 date-time string into an OffsetDateTime. For example a string on the form "2018-12-03T10:15:30+01:00" (value with offset) or "2018-12-03T10:15:30" (value without offset).

        The string is parsed using ISO_OPT_OFFSET_DATE_TIME_PARSER.

        Furthermore, parsing is attempted in a two-step procedure: If first parsing attempt fails the method will evaluate if the problem is something which can likely be fixed and if so it will "fix" the input value, str, and perform a new parsing attempt.

        Parameters:
        str - the string to parse
        zoneOffsetProvider - a function which will be called if no zone offset is present in the input string.
        Returns:
        parsed value
        Throws:
        DateTimeParseException - if unable to parse the string

      • parseIntoOffsetDate

        public static OffsetDate parseIntoOffsetDate​(String str,
                                             Function<LocalDate,​ZoneOffset> zoneOffsetProvider)
        Parses a ISO-8601 date string into an OffsetDate. For example a string on the form "2018-12-03+01:00" (value with offset) or "2018-12-03" (value without offset).

        The string is parsed using ISO_OPT_OFFSET_DATE_PARSER.

        Parameters:
        str - the string to parse
        zoneOffsetProvider - a function which will be called if no zone offset is present in the input string.
        Returns:
        parsed value
        Throws:
        DateTimeParseException - if unable to parse the string

      • parseIntoOffsetDateTimeNoTime

        public static OffsetDateTime parseIntoOffsetDateTimeNoTime​(String str,
                                                           Function<LocalDate,​ZoneOffset> zoneOffsetProvider)
        Parses a ISO-8601 date string into an OffsetDateTime. For example a string on the form "2018-12-03+01:00" (value with offset) or "2018-12-03" (value without offset).

        The string is parsed using ISO_OPT_OFFSET_DATE_PARSER.

        Parameters:
        str - the string to parse
        zoneOffsetProvider - a function which will be called if no zone offset is present in the input string.
        Returns:
        parsed value (with no time value, meaning time value is set to midnight)
        Throws:
        DateTimeParseException - if unable to parse the string

      • parseIntoOffsetTime

        public static OffsetTime parseIntoOffsetTime​(String str,
                                             Function<LocalTime,​ZoneOffset> zoneOffsetProvider)
        Parses a ISO-8601 time string into an OffsetTime. For example a string on the form "10:15:30+01:00" (value with offset) or "10:15:30" (value without offset).

        The string is parsed using ISO_OPT_OFFSET_TIME_PARSER.

        Furthermore, parsing is attempted in a two-step procedure: If first parsing attempt fails the method will evaluate if the problem is something which can likely be fixed and if so it will "fix" the input value, str, and perform a new parsing attempt.

        Parameters:
        str - the string to parse
        zoneOffsetProvider - a function which will be called if no zone offset is present in the input string.
        Returns:
        parsed value
        Throws:
        DateTimeParseException - if unable to parse the string