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

ICU-11851 NumberFormat API doc cleanup.

Browse source 
X-SVN-Rev: 38159
This commit is contained in:
Andy Heninger 2016-01-08 22:21:51 +00:00
parent 09819eab73
commit c8d863f1d4
2 changed files with 64 additions and 71 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

127
icu4c/source/i18n/unicode/numfmt.h
View file

@ -1,6 +1,6 @@
/*
********************************************************************************
* Copyright (C) 1997-2015, International Business Machines Corporation and others.
* Copyright (C) 1997-2016, International Business Machines Corporation and others.
* All Rights Reserved.
********************************************************************************
*
@ -56,6 +56,7 @@ class StringEnumeration;
* formatting and parsing a number. Also provides methods for
* determining which locales have number formats, and what their names
* are.
* \headerfile unicode/numfmt.h "unicode/numfmt.h"
* <P>
* NumberFormat helps you to format and parse numbers for any locale.
* Your code can be completely independent of the locale conventions
@ -64,16 +65,22 @@ class StringEnumeration;
* <P>
* To format a number for the current Locale, use one of the static
* factory methods:
* <pre>
* \code
* double myNumber = 7.0;
* UnicodeString myString;
* UErrorCode success = U_ZERO_ERROR;
* NumberFormat* nf = NumberFormat::createInstance(success)
* nf->format(myNumber, myString);
* cout << " Example 1: " << myString << endl;
* #include <iostream>
* #include "unicode/numfmt.h"
* #include "unicode/unistr.h"
* #include "unicode/ustream.h"
* using namespace std;
*
* int main() {
* double myNumber = 7.0;
* UnicodeString myString;
* UErrorCode success = U_ZERO_ERROR;
* NumberFormat* nf = NumberFormat::createInstance(success);
* nf->format(myNumber, myString);
* cout << " Example 1: " << myString << endl;
* }
* \endcode
* </pre>
* Note that there are additional factory methods within subclasses of
* NumberFormat.
* <P>
@ -81,68 +88,56 @@ class StringEnumeration;
* the format and use it multiple times so that the system doesn't
* have to fetch the information about the local language and country
* conventions multiple times.
* <pre>
* \code
* UnicodeString myString;
* UErrorCode success = U_ZERO_ERROR;
* nf = NumberFormat::createInstance( success );
* int32_t a[] = { 123, 3333, -1234567 };
* const int32_t a_len = sizeof(a) / sizeof(a[0]);
* myString.remove();
* for (int32_t i = 0; i < a_len; i++) {
* nf->format(a[i], myString);
* myString += " ; ";
* NumberFormat *nf = NumberFormat::createInstance( success );
* for (int32_t number: {123, 3333, -1234567}) {
* nf->format(number, myString);
* myString += "; ";
* }
* cout << " Example 2: " << myString << endl;
* \endcode
* </pre>
* To format a number for a different Locale, specify it in the
* call to createInstance().
* <pre>
* call to \c createInstance().
* \code
* nf = NumberFormat::createInstance( Locale::FRENCH, success );
* nf = NumberFormat::createInstance(Locale::getFrench(), success);
* \endcode
* </pre>
* You can use a NumberFormat to parse also.
* <pre>
* You can use a \c NumberFormat to parse also.
* \code
* UErrorCode success;
* Formattable result(-999); // initialized with error code
* nf->parse(myString, result, success);
* \endcode
* </pre>
* Use createInstance to get the normal number format for that country.
* There are other static factory methods available. Use getCurrency
* to get the currency number format for that country. Use getPercent
* Use \c createInstance() to get the normal number format for a \c Locale.
* There are other static factory methods available. Use \c createCurrencyInstance()
* to get the currency number format for that country. Use \c createPercentInstance()
* to get a format for displaying percentages. With this format, a
* fraction from 0.53 is displayed as 53%.
* <P>
* Starting from ICU 4.2, you can use createInstance() by passing in a 'style'
* as parameter to get the correct instance.
* For example,
* use createInstance(...kNumberStyle...) to get the normal number format,
* createInstance(...kPercentStyle...) to get a format for displaying
* percentage,
* createInstance(...kScientificStyle...) to get a format for displaying
* scientific number,
* createInstance(...kCurrencyStyle...) to get the currency number format,
* in which the currency is represented by its symbol, for example, "$3.00".
* createInstance(...kIsoCurrencyStyle...) to get the currency number format,
* in which the currency is represented by its ISO code, for example "USD3.00".
* createInstance(...kPluralCurrencyStyle...) to get the currency number format,
* The type of number formatting can be specified by passing a 'style' parameter to \c createInstance().
* For example, use\n
* \c createInstance(locale, UNUM_DECIMAL, errorCode) to get the normal number format,\n
* \c createInstance(locale, UNUM_PERCENT, errorCode) to get a format for displaying percentage,\n
* \c createInstance(locale, UNUM_SCIENTIFIC, errorCode) to get a format for displaying scientific number,\n
* \c createInstance(locale, UNUM_CURRENCY, errorCode) to get the currency number format,
* in which the currency is represented by its symbol, for example, "$3.00".\n
* \c createInstance(locale, UNUM_CURRENCY_ISO, errorCode) to get the currency number format,
* in which the currency is represented by its ISO code, for example "USD3.00".\n
* \c createInstance(locale, UNUM_CURRENCY_PLURAL, errorCode) to get the currency number format,
* in which the currency is represented by its full name in plural format,
* for example, "3.00 US dollars" or "1.00 US dollar".
* <P>
* You can also control the display of numbers with such methods as
* getMinimumFractionDigits. If you want even more control over the
* \c getMinimumFractionDigits(). If you want even more control over the
* format or parsing, or want to give your users more control, you can
* try casting the NumberFormat you get from the factory methods to a
* DecimalNumberFormat. This will work for the vast majority of
* countries; just remember to put it in a try block in case you
* try dynamic_casting the \c NumberFormat you get from the factory methods to a
* \c DecimalFormat. This will work for the vast majority of
* countries; just remember to test for NULL in case you
* encounter an unusual one.
* <P>
* You can also use forms of the parse and format methods with
* ParsePosition and FieldPosition to allow you to:
* \c ParsePosition and \c FieldPosition to allow you to:
* <ul type=round>
* <li>(a) progressively parse through pieces of a string.
* <li>(b) align the decimal point and other areas.
@ -150,8 +145,8 @@ class StringEnumeration;
* For example, you can align numbers in two ways.
* <P>
* If you are using a monospaced font with spacing for alignment, you
* can pass the FieldPosition in your format call, with field =
* INTEGER_FIELD. On output, getEndIndex will be set to the offset
* can pass the \c FieldPosition in your format call, with field =
* \c UNUM_INTEGER_FIELD. On output, \c getEndIndex will be set to the offset
* between the last character of the integer and the decimal. Add
* (desiredSpaceCount - getEndIndex) spaces at the front of the
* string.
@ -479,6 +474,7 @@ public:
* Result is appended to existing contents.
* @param pos On input: an alignment field, if desired.
* On output: the offsets of the alignment field.
* @param status Output param filled with success/failure status.
* @return Reference to 'appendTo' parameter.
* @internal
*/
@ -527,7 +523,7 @@ public:
UErrorCode& status) const;
public:
/**
* Format a decimal number.
* Format a decimal number.
* The number is a DigitList wrapper onto a floating point decimal number.
* The default implementation in NumberFormat converts the decimal number
* to a double and formats that. Subclasses of NumberFormat that want
@ -549,7 +545,7 @@ public:
UErrorCode& status) const;
/**
* Format a decimal number.
* Format a decimal number.
* The number is a DigitList wrapper onto a floating point decimal number.
* The default implementation in NumberFormat converts the decimal number
* to a double and formats that. Subclasses of NumberFormat that want
@ -659,8 +655,8 @@ public:
/**
* Sets whether lenient parsing should be enabled (it is off by default).
*
* @param enable <code>TRUE</code> if lenient parsing should be used,
* <code>FALSE</code> otherwise.
* @param enable \c TRUE if lenient parsing should be used,
* \c FALSE otherwise.
* @stable ICU 4.8
*/
virtual void setLenient(UBool enable);
@ -668,28 +664,23 @@ public:
/**
* Returns whether lenient parsing is enabled (it is off by default).
*
* @return <code>TRUE</code> if lenient parsing is enabled,
* <code>FALSE</code> otherwise.
* @return \c TRUE if lenient parsing is enabled,
* \c FALSE otherwise.
* @see #setLenient
* @stable ICU 4.8
*/
virtual UBool isLenient(void) const;
/**
* Returns the default number format for the current default
* locale. The default format is one of the styles provided by
* the other factory methods: getNumberInstance,
* getCurrencyInstance or getPercentInstance. Exactly which one
* is locale dependant.
* Create a default style NumberFormat for the current default locale.
* The default formatting style is locale dependent.
* @stable ICU 2.0
*/
static NumberFormat* U_EXPORT2 createInstance(UErrorCode&);
/**
* 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. Exactly which one is locale dependant.
* Create a default style NumberFormat for the specified locale.
* The default formatting style is locale dependent.
* @param inLocale the given locale.
* @stable ICU 2.0
*/
@ -697,7 +688,7 @@ public:
UErrorCode&);
/**
* Creates the specified decimal format style of the desired locale.
* Create a specific style NumberFormat for the specified locale.
* @param desiredLocale the given locale.
* @param style the given style.
* @param errorCode Output param filled with success/failure status.
@ -955,7 +946,7 @@ public:
* @param value The UDisplayContext value to set.
* @param status Input/output status. If at entry this indicates a failure
* status, the function will do nothing; otherwise this will be
* updated with any new status from the function.
* updated with any new status from the function.
* @stable ICU 53
*/
virtual void setContext(UDisplayContext value, UErrorCode& status);
@ -966,7 +957,7 @@ public:
* @param type The UDisplayContextType whose value to return
* @param status Input/output status. If at entry this indicates a failure
* status, the function will do nothing; otherwise this will be
* updated with any new status from the function.
* updated with any new status from the function.
* @return The UDisplayContextValue for the specified type.
* @stable ICU 53
*/
@ -1062,9 +1053,11 @@ private:
int32_t fMinFractionDigits;
protected:
/** \internal */
static const int32_t gDefaultMaxIntegerDigits;
/** \internal */
static const int32_t gDefaultMinIntegerDigits;
private:
UBool fParseIntegerOnly;
UBool fLenient; // TRUE => lenient parse is enabled

8
icu4c/source/test/intltest/numrgts.cpp
View file

@ -1,5 +1,5 @@
/***********************************************************************
* Copyright (c) 1997-2015, International Business Machines Corporation
* Copyright (c) 1997-2016, International Business Machines Corporation
* and others. All Rights Reserved.
***********************************************************************/
@ -921,7 +921,7 @@ void NumberFormatRegressionTest::Test4070798 (void)
delete formatter;
return;
}
failure(status, "NumberFormat::createNumberInstance", loc);
failure(status, "NumberFormat::createInstance", loc);
tempString = formatter->format (-5789.9876, tempString);
if (tempString == expectedDefault) {
@ -990,7 +990,7 @@ void NumberFormatRegressionTest::Test4071005 (void)
UErrorCode status = U_ZERO_ERROR;
formatter = NumberFormat::createInstance(Locale::getCanadaFrench(), status);
if (failure(status, "NumberFormat::createNumberInstance", Locale::getCanadaFrench(), TRUE)){
if (failure(status, "NumberFormat::createInstance", Locale::getCanadaFrench(), TRUE)){
delete formatter;
return;
};
@ -1058,7 +1058,7 @@ void NumberFormatRegressionTest::Test4071014 (void)
char loc[256]={0};
uloc_canonicalize("de_DE_PREEURO", loc, 256, &status);
formatter = NumberFormat::createInstance(Locale(loc), status);
if (failure(status, "NumberFormat::createNumberInstance", loc, TRUE)){
if (failure(status, "NumberFormat::createInstance", loc, TRUE)){
delete formatter;
return;
}