organicmaps/icu
13
Fork 0
mirror of https://github.com/unicode-org/icu.git synced 2025-04-20 20:19:32 +00:00
Code Issues 1 Projects Releases Wiki Activity Actions 1

ICU-9044 Improve parse method documentation, note that parsing Chinese cal dates may be ambiguous (J)

Browse source 
X-SVN-Rev: 31281
This commit is contained in:
Peter Edberg 2012-01-31 08:13:43 +00:00
parent e3edca9be5
commit 044e9d07c0
3 changed files with 64 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
icu4j/main/classes/core/src/com/ibm/icu/text/DateFormat.java
View file

@ -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.
*
* <p> 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).
*
* <p> 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.
*
* <p> 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).
*
* <p> 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

5
icu4j/main/classes/core/src/com/ibm/icu/text/SimpleDateFormat.java
View file

@ -73,7 +73,7 @@ import com.ibm.icu.util.ULocale.Category;
* y&#x2020; 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;
* <p>
* <strong>(Text & Number)</strong>: 3 or over, use text, otherwise use number.
* <p>
* <strong>(Text,NumFallback)</strong>: Behaves like Text if there is supporting
* data, like Number otherwise.
* <p>
* 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

13
icu4j/main/tests/core/src/com/ibm/icu/dev/test/calendar/ChineseTest.java
View file

@ -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;
}