From 044e9d07c0903c0e931a927c533dc8dc437c364f Mon Sep 17 00:00:00 2001 From: Peter Edberg Date: Tue, 31 Jan 2012 08:13:43 +0000 Subject: [PATCH] ICU-9044 Improve parse method documentation, note that parsing Chinese cal dates may be ambiguous (J) X-SVN-Rev: 31281 --- .../core/src/com/ibm/icu/text/DateFormat.java | 58 ++++++++++++++++--- .../com/ibm/icu/text/SimpleDateFormat.java | 5 +- .../icu/dev/test/calendar/ChineseTest.java | 13 ++++- 3 files changed, 64 insertions(+), 12 deletions(-) diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/DateFormat.java b/icu4j/main/classes/core/src/com/ibm/icu/text/DateFormat.java index 0cccc703b8d..ec2db1c7ee1 100644 --- a/icu4j/main/classes/core/src/com/ibm/icu/text/DateFormat.java +++ b/icu4j/main/classes/core/src/com/ibm/icu/text/DateFormat.java @@ -499,7 +499,29 @@ public abstract class DateFormat extends UFormat { } /** - * Parses a date/time string. + * Parses a date/time string. For example, a time text "07/10/96 4:5 PM, PDT" + * will be parsed into a Date that is equivalent to Date(837039928046). + * Parsing begins at the beginning of the string and proceeds as far as + * possible. Assuming no parse errors were encountered, this function + * doesn't return any information about how much of the string was consumed + * by the parsing. If you need that information, use a version of + * parse() that takes a ParsePosition. + * + *

By default, parsing is lenient: If the input is not in the form used + * by this object's format method but can still be parsed as a date, then + * the parse succeeds. Clients may insist on strict adherence to the + * format by calling setLenient(false). + * + *

Note that the normal date formats associated with some calendars - such + * as the Chinese lunar calendar - do not specify enough fields to enable + * dates to be parsed unambiguously. In the case of the Chinese lunar + * calendar, while the year within the current 60-year cycle is specified, + * the number of such cycles since the start date of the calendar (in the + * ERA field of the Calendar object) is not normally part of the format, + * and parsing may assume the wrong era. For cases such as this it is + * recommended that clients parse using the parse method that takes a Calendar + * with the Calendar passed in set to the current date, or to a date + * within the era/cycle that should be assumed if absent in the format. * * @param text The date/time string to be parsed * @@ -523,9 +545,15 @@ public abstract class DateFormat extends UFormat { /** * Parses a date/time string according to the given parse position. * For example, a time text "07/10/96 4:5 PM, PDT" will be parsed - * into a Calendar that is equivalent to Date(837039928046). The - * caller should clear the calendar before calling this method, - * unless existing field information is to be kept. + * into a Calendar that is equivalent to Date(837039928046). Before + * calling this method the caller should initialize the calendar + * in one of two ways (unless existing field information is to be kept): + * (1) clear the calendar, or (2) set the calendar to the current date + * (or to any date whose fields should be used to supply values that + * are missing in the parsed date). For example, Chinese calendar dates + * do not normally provide an era/cycle; in this case the calendar that + * is passed in should be set to a date within the era that should be + * assumed, normally the current era. * *

By default, parsing is lenient: If the input is not in the form used * by this object's format method but can still be parsed as a date, then @@ -536,10 +564,13 @@ public abstract class DateFormat extends UFormat { * * @param text The date/time string to be parsed * - * @param cal The calendar into which parsed data will be stored. - * In general, this should be cleared before calling this - * method. If this parse fails, the calendar may still - * have been modified. When the calendar type is different + * @param cal The calendar set on input to the date and time to be used + * for missing values in the date/time string being parsed, + * and set on output to the parsed date/time. In general, this + * should be initialized before calling this method - either + * cleared or set to the current date, depending on desired + * behavior. If this parse fails, the calendar may still + * have been modified. When the calendar type is different * from the internal calendar held by this DateFormat * instance, calendar field values will be parsed based * on the internal calendar initialized with the time and @@ -564,6 +595,17 @@ public abstract class DateFormat extends UFormat { * the parse succeeds. Clients may insist on strict adherence to the * format by calling setLenient(false). * + *

Note that the normal date formats associated with some calendars - such + * as the Chinese lunar calendar - do not specify enough fields to enable + * dates to be parsed unambiguously. In the case of the Chinese lunar + * calendar, while the year within the current 60-year cycle is specified, + * the number of such cycles since the start date of the calendar (in the + * ERA field of the Calendar object) is not normally part of the format, + * and parsing may assume the wrong era. For cases such as this it is + * recommended that clients parse using the parse method that takes a Calendar + * with the Calendar passed in set to the current date, or to a date + * within the era/cycle that should be assumed if absent in the format. + * * @see #setLenient(boolean) * * @param text The date/time string to be parsed diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/SimpleDateFormat.java b/icu4j/main/classes/core/src/com/ibm/icu/text/SimpleDateFormat.java index 951ac69c61f..1dd2db5584c 100644 --- a/icu4j/main/classes/core/src/com/ibm/icu/text/SimpleDateFormat.java +++ b/icu4j/main/classes/core/src/com/ibm/icu/text/SimpleDateFormat.java @@ -73,7 +73,7 @@ import com.ibm.icu.util.ULocale.Category; * y† year (Number) 1996 * Y* year (week of year) (Number) 1997 * u* extended year (Number) 4601 - * U* cyclic year name (Text) ren-chen + * U* cyclic year name (Text,NumFallback) ren-chen (29) * M month in year (Text & Number) July & 07 * d day in month (Number) 10 * h hour in am/pm (1~12) (Number) 12 @@ -124,6 +124,9 @@ import com.ibm.icu.util.ULocale.Category; *

* (Text & Number): 3 or over, use text, otherwise use number. *

+ * (Text,NumFallback): Behaves like Text if there is supporting + * data, like Number otherwise. + *

* Any characters in the pattern that are not in the ranges of ['a'..'z'] * and ['A'..'Z'] will be treated as quoted text. For instance, characters * like ':', '.', ' ', '#' and '@' will appear in the resulting time text diff --git a/icu4j/main/tests/core/src/com/ibm/icu/dev/test/calendar/ChineseTest.java b/icu4j/main/tests/core/src/com/ibm/icu/dev/test/calendar/ChineseTest.java index 83fc921b271..0e9e27461cd 100644 --- a/icu4j/main/tests/core/src/com/ibm/icu/dev/test/calendar/ChineseTest.java +++ b/icu4j/main/tests/core/src/com/ibm/icu/dev/test/calendar/ChineseTest.java @@ -1,5 +1,5 @@ /********************************************************************* - * Copyright (C) 2000-2011, International Business Machines Corporation and + * Copyright (C) 2000-2012, International Business Machines Corporation and * others. All Rights Reserved. ********************************************************************* */ @@ -250,6 +250,13 @@ public class ChineseTest extends CalendarTest { /** * Test formatting. + * Q: Why is this in Calendar tests instead of Format tests? + * Note: This test assumes that Chinese calendar formatted dates can be parsed + * unambiguously to recover the original Date that was formatted. This is not + * currently true since Chinese calendar formatted dates do not include an era. + * To address this will require formatting/parsing of fields from some other + * associated calendar, as per ICU ticket #9043. This test should be timebombed + * until that ticket is addressed. */ public void TestFormat() { ChineseCalendar cal = new ChineseCalendar(); @@ -259,8 +266,8 @@ public class ChineseTest extends CalendarTest { java.util.Calendar tempcal = java.util.Calendar.getInstance(); tempcal.clear(); - // time bomb test until Chinese calendar is fixed in ICU4J to use monthPatterns, etc. - if (VersionInfo.ICU_VERSION.compareTo(VersionInfo.getInstance(49,0,2)) <= 0) { + // time bomb test until ticket #9043 fixes the ambiguous era problem. + if (VersionInfo.ICU_VERSION.compareTo(VersionInfo.getInstance(50,0,2)) <= 0) { return; } -- 2.40.0