From: Markus Scherer <markus.icu@gmail.com>
Date: Mon, 13 Feb 2012 23:54:23 +0000 (+0000)
Subject: ICU-8803 make Calendar::getType() public and improve API docs
X-Git-Tag: milestone-59-0-1~4059
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=2ea559eeb4e05a62e1ac7926f1d1e5de542e498b;p=icu

ICU-8803 make Calendar::getType() public and improve API docs

X-SVN-Rev: 31385
---

diff --git a/icu4c/source/i18n/unicode/calendar.h b/icu4c/source/i18n/unicode/calendar.h
index cf7f7355cd5..248eaf9f71d 100644
--- a/icu4c/source/i18n/unicode/calendar.h
+++ b/icu4c/source/i18n/unicode/calendar.h
@@ -1,6 +1,6 @@
 /*
 ********************************************************************************
-*   Copyright (C) 1997-2011, International Business Machines
+*   Copyright (C) 1997-2012, International Business Machines
 *   Corporation and others.  All Rights Reserved.
 ********************************************************************************
 *
@@ -1195,12 +1195,36 @@ public:
     virtual UClassID getDynamicClassID(void) const = 0;
 
     /**
-     * Returns the resource key string used for this calendar type.
-     * For example, prepending "Eras_" to this string could return "Eras_japanese"
-     * or "Eras_gregorian".
-     *
-     * @returns static string, for example, "gregorian" or "japanese"
-     * @internal
+     * Returns the calendar type name string for this Calendar object.
+     * The returned string is the legacy ICU calendar attribute value,
+     * for example, "gregorian" or "japanese".
+     *
+     * See type="old type name" for the calendar attribute of locale IDs
+     * at http://www.unicode.org/reports/tr35/#Key_Type_Definitions
+     *
+     * Sample code for getting the LDML/BCP 47 calendar key value:
+     * \code
+     * const char *calType = cal->getType();
+     * if (0 == strcmp(calType, "unknown")) {
+     *     // deal with unknown calendar type
+     * } else {
+     *     string localeID("root@calendar=");
+     *     localeID.append(calType);
+     *     char langTag[100];
+     *     UErrorCode errorCode = U_ZERO_ERROR;
+     *     int32_t length = uloc_toLanguageTag(localeID.c_str(), langTag, (int32_t)sizeof(langTag), TRUE, &errorCode);
+     *     if (U_FAILURE(errorCode)) {
+     *         // deal with errors & overflow
+     *     }
+     *     string lang(langTag, length);
+     *     size_t caPos = lang.find("-ca-");
+     *     lang.erase(0, caPos + 4);
+     *     // lang now contains the LDML calendar type
+     * }
+     * \endcode
+     *
+     * @return legacy calendar type name string
+     * @draft ICU 49
      */
     virtual const char * getType() const = 0;
 
diff --git a/icu4c/source/i18n/unicode/gregocal.h b/icu4c/source/i18n/unicode/gregocal.h
index ab83371426f..6ae08edec8e 100644
--- a/icu4c/source/i18n/unicode/gregocal.h
+++ b/icu4c/source/i18n/unicode/gregocal.h
@@ -1,5 +1,5 @@
 /*
-* Copyright (C) 1997-2011, International Business Machines Corporation and others.
+* Copyright (C) 1997-2012, International Business Machines Corporation and others.
 * All Rights Reserved.
 ********************************************************************************
 *
@@ -469,10 +469,14 @@ public:
     static UClassID U_EXPORT2 getStaticClassID(void);
 
     /**
-     * Get the calendar type, "gregorian", for use in DateFormatSymbols.
+     * Returns the calendar type name string for this Calendar object.
+     * The returned string is the legacy ICU calendar attribute value,
+     * for example, "gregorian" or "japanese".
      *
-     * @return calendar type
-     * @internal
+     * For more details see the Calendar::getType() documentation.
+     *
+     * @return legacy calendar type name string
+     * @draft ICU 49
      */
     virtual const char * getType() const;