From: Shane Carr Date: Tue, 13 Mar 2018 02:14:29 +0000 (+0000) Subject: ICU-13402 Tweaking NumberFormatter pointers and adding additional pointers on the... X-Git-Tag: release-62-rc~215 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=24431ce7a986d11fed192e536068200d7d7a81af;p=icu ICU-13402 Tweaking NumberFormatter pointers and adding additional pointers on the factory methods in ICU4C and ICU4J. X-SVN-Rev: 41096 --- diff --git a/icu4c/source/i18n/unicode/decimfmt.h b/icu4c/source/i18n/unicode/decimfmt.h index dbc27d3a65e..b062208d9b1 100644 --- a/icu4c/source/i18n/unicode/decimfmt.h +++ b/icu4c/source/i18n/unicode/decimfmt.h @@ -77,7 +77,7 @@ template class U_I18N_API EnumSetIMPORTANT: New users are strongly encouraged to see if * numberformatter.h fits their use case. Although not deprecated, this header - * is on life support and is provided for backwards compatibility only. + * is provided for backwards compatibility only. *
* * DecimalFormat is a concrete subclass of NumberFormat that formats decimal @@ -694,6 +694,9 @@ public: * on NumberFormat such as createInstance. These factories will * return the most appropriate sub-class of NumberFormat for a given * locale. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of DecimalFormat. * @param status Output param set to success/failure code. If the * pattern is invalid this will be set to a failure code. * @stable ICU 2.0 @@ -709,6 +712,9 @@ public: * on NumberFormat such as createInstance. These factories will * return the most appropriate sub-class of NumberFormat for a given * locale. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of DecimalFormat. * @param pattern A non-localized pattern string. * @param status Output param set to success/failure code. If the * pattern is invalid this will be set to a failure code. @@ -727,6 +733,9 @@ public: * createInstance or createCurrencyInstance. If you need only minor adjustments * to a standard format, you can modify the format returned by * a NumberFormat factory method. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of DecimalFormat. * * @param pattern a non-localized pattern string * @param symbolsToAdopt the set of symbols to be used. The caller should not @@ -832,6 +841,9 @@ public: * createInstance or createCurrencyInstance. If you need only minor adjustments * to a standard format, you can modify the format returned by * a NumberFormat factory method. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of DecimalFormat. * * @param pattern a non-localized pattern string * @param symbolsToAdopt the set of symbols to be used. The caller should not @@ -855,6 +867,9 @@ public: * createInstance or createCurrencyInstance. If you need only minor adjustments * to a standard format, you can modify the format returned by * a NumberFormat factory method. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of DecimalFormat. * * @param pattern a non-localized pattern string * @param symbols the set of symbols to be used diff --git a/icu4c/source/i18n/unicode/measfmt.h b/icu4c/source/i18n/unicode/measfmt.h index c80d2446f1b..00f2d47a004 100644 --- a/icu4c/source/i18n/unicode/measfmt.h +++ b/icu4c/source/i18n/unicode/measfmt.h @@ -89,7 +89,7 @@ class DateFormat; /** *

IMPORTANT: New users are strongly encouraged to see if * numberformatter.h fits their use case. Although not deprecated, this header - * is on life support and is provided for backwards compatibility only. + * is provided for backwards compatibility only. * * @see Format * @author Alan Liu @@ -102,6 +102,9 @@ class U_I18N_API MeasureFormat : public Format { /** * Constructor. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. * @stable ICU 53 */ MeasureFormat( @@ -109,6 +112,9 @@ class U_I18N_API MeasureFormat : public Format { /** * Constructor. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. * @stable ICU 53 */ MeasureFormat( @@ -228,6 +234,9 @@ class U_I18N_API MeasureFormat : public Format { /** * Return a formatter for CurrencyAmount objects in the given * locale. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. * @param locale desired locale * @param ec input-output error code * @return a formatter object, or NULL upon error @@ -239,6 +248,9 @@ class U_I18N_API MeasureFormat : public Format { /** * Return a formatter for CurrencyAmount objects in the default * locale. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. * @param ec input-output error code * @return a formatter object, or NULL upon error * @stable ICU 3.0 diff --git a/icu4c/source/i18n/unicode/numfmt.h b/icu4c/source/i18n/unicode/numfmt.h index 4a8e049f931..39379851b0f 100644 --- a/icu4c/source/i18n/unicode/numfmt.h +++ b/icu4c/source/i18n/unicode/numfmt.h @@ -55,7 +55,7 @@ class StringEnumeration; /** *

IMPORTANT: New users are strongly encouraged to see if * numberformatter.h fits their use case. Although not deprecated, this header - * is on life support and is provided for backwards compatibility only. + * is provided for backwards compatibility only. *

* * Abstract base class for all number formats. Provides interface for @@ -708,6 +708,9 @@ public: /** * Create a default style NumberFormat for the current default locale. * The default formatting style is locale dependent. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. * @stable ICU 2.0 */ static NumberFormat* U_EXPORT2 createInstance(UErrorCode&); @@ -716,6 +719,9 @@ public: * Create a default style NumberFormat for the specified locale. * The default formatting style is locale dependent. * @param inLocale the given locale. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. * @stable ICU 2.0 */ static NumberFormat* U_EXPORT2 createInstance(const Locale& inLocale, @@ -723,6 +729,9 @@ public: /** * Create a specific style NumberFormat for the specified locale. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. * @param desiredLocale the given locale. * @param style the given style. * @param errorCode Output param filled with success/failure status. @@ -759,12 +768,18 @@ public: /** * Returns a currency format for the current default locale. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. * @stable ICU 2.0 */ static NumberFormat* U_EXPORT2 createCurrencyInstance(UErrorCode&); /** * Returns a currency format for the specified locale. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. * @param inLocale the given locale. * @stable ICU 2.0 */ @@ -773,12 +788,18 @@ public: /** * Returns a percentage format for the current default locale. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. * @stable ICU 2.0 */ static NumberFormat* U_EXPORT2 createPercentInstance(UErrorCode&); /** * Returns a percentage format for the specified locale. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. * @param inLocale the given locale. * @stable ICU 2.0 */ @@ -787,12 +808,18 @@ public: /** * Returns a scientific format for the current default locale. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. * @stable ICU 2.0 */ static NumberFormat* U_EXPORT2 createScientificInstance(UErrorCode&); /** * Returns a scientific format for the specified locale. + *

+ * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. * @param inLocale the given locale. * @stable ICU 2.0 */ diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/CompactDecimalFormat.java b/icu4j/main/classes/core/src/com/ibm/icu/text/CompactDecimalFormat.java index 18e1ee1b35c..e185a54ecb7 100644 --- a/icu4j/main/classes/core/src/com/ibm/icu/text/CompactDecimalFormat.java +++ b/icu4j/main/classes/core/src/com/ibm/icu/text/CompactDecimalFormat.java @@ -23,8 +23,7 @@ import com.ibm.icu.util.ULocale; *

* IMPORTANT: New users are strongly encouraged to see if * {@link NumberFormatter} fits their use case. Although not deprecated, this - * class, CompactDecimalFormat, is on life support and is provided for - * backwards compatibility only. + * class, CompactDecimalFormat, is provided for backwards compatibility only. *

* * The CompactDecimalFormat produces abbreviated numbers, suitable for display in environments will @@ -80,6 +79,9 @@ public class CompactDecimalFormat extends DecimalFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* Creates a CompactDecimalFormat appropriate for a locale. The result may be affected by the * number system in the locale, such as ar-u-nu-latn. * @@ -92,6 +94,9 @@ public class CompactDecimalFormat extends DecimalFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* Creates a CompactDecimalFormat appropriate for a locale. The result may be affected by the * number system in the locale, such as ar-u-nu-latn. * diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/DecimalFormat.java b/icu4j/main/classes/core/src/com/ibm/icu/text/DecimalFormat.java index cf56e20aab0..c7bb125782b 100644 --- a/icu4j/main/classes/core/src/com/ibm/icu/text/DecimalFormat.java +++ b/icu4j/main/classes/core/src/com/ibm/icu/text/DecimalFormat.java @@ -39,8 +39,7 @@ import com.ibm.icu.util.ULocale.Category; *

* IMPORTANT: New users are strongly encouraged to see if * {@link NumberFormatter} fits their use case. Although not deprecated, this - * class, DecimalFormat, is on life support and is only provided for - * java.text.DecimalFormat compatibility. + * class, DecimalFormat, is only provided for java.text.DecimalFormat compatibility. *

* * DecimalFormat is the primary diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/MeasureFormat.java b/icu4j/main/classes/core/src/com/ibm/icu/text/MeasureFormat.java index 9ae8eb69f78..cf0d2dcdda2 100644 --- a/icu4j/main/classes/core/src/com/ibm/icu/text/MeasureFormat.java +++ b/icu4j/main/classes/core/src/com/ibm/icu/text/MeasureFormat.java @@ -58,8 +58,7 @@ import com.ibm.icu.util.UResourceBundle; *

* IMPORTANT: New users are strongly encouraged to see if * {@link NumberFormatter} fits their use case. Although not deprecated, this - * class, MeasureFormat, is on life support and is provided for - * backwards compatibility only. + * class, MeasureFormat, is provided for backwards compatibility only. *

* *

diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/NumberFormat.java b/icu4j/main/classes/core/src/com/ibm/icu/text/NumberFormat.java index 38885def708..63d2a109c40 100644 --- a/icu4j/main/classes/core/src/com/ibm/icu/text/NumberFormat.java +++ b/icu4j/main/classes/core/src/com/ibm/icu/text/NumberFormat.java @@ -39,8 +39,7 @@ import com.ibm.icu.util.UResourceBundle; *

* IMPORTANT: New users are strongly encouraged to see if * {@link NumberFormatter} fits their use case. Although not deprecated, this - * class, NumberFormat, is on life support and is only provided for - * java.text.NumberFormat compatibility. + * class, NumberFormat, is only provided for java.text.NumberFormat compatibility. *

* * NumberFormat is the abstract base class for all number @@ -585,6 +584,9 @@ public abstract class NumberFormat extends UFormat { //============== Locale Stuff ===================== /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* Returns the default number format for the current default FORMAT locale. * The default format is one of the styles provided by the other * factory methods: getNumberInstance, getIntegerInstance, @@ -599,6 +601,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* Returns the default number format for the specified locale. * The default format is one of the styles provided by the other * factory methods: getNumberInstance, getCurrencyInstance or getPercentInstance. @@ -610,6 +615,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* {@icu} Returns the default number format for the specified locale. * The default format is one of the styles provided by the other * factory methods: getNumberInstance, getCurrencyInstance or getPercentInstance. @@ -621,6 +629,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* {@icu} Returns a specific style number format for default FORMAT locale. * @param style number format style * @see Category#FORMAT @@ -631,6 +642,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* {@icu} Returns a specific style number format for a specific locale. * @param inLocale the specific locale. * @param style number format style @@ -642,6 +656,9 @@ public abstract class NumberFormat extends UFormat { /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* Returns a general-purpose number format for the current default FORMAT locale. * @see Category#FORMAT * @stable ICU 2.0 @@ -651,6 +668,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* Returns a general-purpose number format for the specified locale. * @stable ICU 2.0 */ @@ -659,6 +679,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* {@icu} Returns a general-purpose number format for the specified locale. * @stable ICU 3.2 */ @@ -667,6 +690,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* Returns an integer number format for the current default FORMAT locale. The * returned number format is configured to round floating point numbers * to the nearest integer using IEEE half-even rounding (see {@link @@ -684,6 +710,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* Returns an integer number format for the specified locale. The * returned number format is configured to round floating point numbers * to the nearest integer using IEEE half-even rounding (see {@link @@ -701,6 +730,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* {@icu} Returns an integer number format for the specified locale. The * returned number format is configured to round floating point numbers * to the nearest integer using IEEE half-even rounding (see {@link @@ -717,6 +749,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* Returns a currency format for the current default FORMAT locale. * @return a number format for currency * @see Category#FORMAT @@ -727,6 +762,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* Returns a currency format for the specified locale. * @return a number format for currency * @stable ICU 2.0 @@ -736,6 +774,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* {@icu} Returns a currency format for the specified locale. * @return a number format for currency * @stable ICU 3.2 @@ -745,6 +786,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* Returns a percentage format for the current default FORMAT locale. * @return a number format for percents * @see Category#FORMAT @@ -755,6 +799,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* Returns a percentage format for the specified locale. * @return a number format for percents * @stable ICU 2.0 @@ -764,6 +811,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* {@icu} Returns a percentage format for the specified locale. * @return a number format for percents * @stable ICU 3.2 @@ -773,6 +823,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* {@icu} Returns a scientific format for the current default FORMAT locale. * @return a scientific number format * @see Category#FORMAT @@ -783,6 +836,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* {@icu} Returns a scientific format for the specified locale. * @return a scientific number format * @stable ICU 2.0 @@ -792,6 +848,9 @@ public abstract class NumberFormat extends UFormat { } /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* {@icu} Returns a scientific format for the specified locale. * @return a scientific number format * @stable ICU 3.2 @@ -1345,6 +1404,9 @@ public abstract class NumberFormat extends UFormat { /** + * NOTE: New users are strongly encouraged to use + * {@link NumberFormatter} instead of NumberFormat. + *
* Returns a specific style number format for a specific locale. * @param desiredLocale the specific locale. * @param choice number format style