Package com.addicticks.texttime.formatters

Class DateTimeFormatterJS

  • public class DateTimeFormatterJS
extends Object
    Formatter-Parsers for ECMAScript (JavaScript) date-time values.

    The ECMAScript Date Time String format is based upon a simplification of the ISO 8601 Extended Format. The general format is as follows: 

        YYYY-MM-DDTHH:mm:ss.sssZ

    This format allows:

    • In the date-part:
      • Leaving out the month value. It will then default to 1 (January).
      • Leaving out the day-of-month value. It will then default to 1.
    • In the time-part:
      • Leaving out the minute value. It will then default to 0.
      • Leaving out the seconds value. It will then default to 0.
      • Leaving out the milliseconds value. It will then default to 0.
    • Suffix:
      • Leaving out timezone offset. It will then default to UTC. (same as using a 'Z' suffix).

    Predefined Formatters-Parsers overview

    Predefined Formatters
    Formatter Usage Description Examples
    JS_DATETIME_FORMATTER Formatting For formatting into ECMAScript Date-Time string value '2018-12-03T10:15:30+01:00'
    '2018-12-03T10:15:30Z'
    JS_DATETIME_PARSER Parsing For parsing ECMAScript Date-Time string value '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'
    '2018'
    '2018T10'
    '2018-12T10:15:30'
    See Also:
    ECMAScript Date Time String Format

    • Field Detail

      • JS_DATETIME_PARSER

        public static final DateTimeFormatter JS_DATETIME_PARSER
        For parsing of ECMAScript date-time value.

        This Formatter-Parser is suitable only for parsing, not for formatting. When used for formatting it may produce values which are not compliant with the ECMAScript specification. Instead JS_DATETIME_FORMATTER should be used for formatting.

        Lenient parsing is performed, meaning that certain non-compliant formats are accepted. These formats should not be encouraged but are accepted by this parser as a pragmatic compromise. Compared to the formal definition the following is accepted while parsing:

        • The delimiter between the date and the time value may be a 'T' or a ' ' (space). The formal definition only allows a 'T'.
        • Literals in the string, i.e. 'T' and 'Z', are accepted regardless of upper/lower-case. The formal specification mandates that these are in upper-case.
        • The seconds fraction field - if present - can have up to 9 digits. The formal definition mandates that this part of the string is exactly 3 digits (if present).

        Incompliance The formal definition says that '24:00' is a valid representation for midnight. This parser will not accept such value because it only accepts hour values in the range from 0 to 23.

        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. The pattern is allowed in the ISO 8601 specification (allowed as an exception: "by mutual agreement of the partners in information interchange"), but is indeed not allowed in the ECMAScript Date Time String format. It is allowed by this method as an exception because allowing it does not create ambiguity.

        See Also:
        ECMAScript Date Time String Format

    • Method Detail

      • parseIntoOffsetDateTime

        public static OffsetDateTime parseIntoOffsetDateTime​(String str)
        Parses an ECMAScript 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, meaning UTC).

        The string is parsed using JS_DATETIME_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

      • format

        public static String format​(OffsetDateTime dt)
        Formats an OffsetDateTime into a ECMAScript date-time string.

        If the input's time value is MIDNIGHT and input's timezone offset is UTC then the value is assumed to be a date-only value and will be output without time part, e.g. '2018-03-14'.

        Parameters:
        dt -
        Returns:
        ECMAScript date-time string