Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8331207

Misleading example in DateFormat#parse docs

XMLWordPrintable

    • Icon: Bug Bug
    • Resolution: Fixed
    • Icon: P4 P4
    • 23
    • None
    • core-libs
    • b21

      The docs for DateFormat#parse mention

      > Parse a date/time string according to the given parse position. For
      > example, a time text {@code "07/10/96 4:5 PM, PDT"} will be parsed into a {@code Date}
      > that is equivalent to {@code Date(837039900000L)}.

      The "07/10/96 4:5 PM, PDT" example is potentially misleading because DateFormat.getInstance() uses "M/d/yy, h:mm a". Prior to the switch to the CLDR Locale provider it would still parse strings like the example with a time zone at the end, but after the switch to CLDR it will not:

      class T {
        public static void main(String[] args) throws Exception {
          System.err.println(java.text.DateFormat.getInstance().parse(args[0]).getTime());
        }
      }

      $ java -Djava.locale.providers=COMPAT T "07/10/96 4:5 PM, PDT"
      837039900000

      $ java -Djava.locale.providers=CLDR T "07/10/96 4:5 PM, PDT"
      Exception in thread "main" java.text.ParseException: Unparseable date: "07/10/96 4:5 PM, PDT"
              at java.base/java.text.DateFormat.parse(DateFormat.java:396)
              at T.main(T.java:3)

      Using an explicit pattern "M/d/yy h:m a, z" allows the example to be parsed.

      I think it could be clearer to use an example that can be parsed by DateFormat.getInstance(), or else to emphasize in the docs that the example depends on a compatible pattern.

            jlu Justin Lu
            cushon Liam Miller-Cushon
            Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

              Created:
              Updated:
              Resolved: