* NOTE: When formatting a double, this method, along with {@link #minFraction} and - * {@link #minDigits}, will trigger complex algorithm similar to Dragon4 to determine the low-order digits - * and the number of digits to display based on the value of the double. If the number of fraction places or - * significant digits can be bounded, consider using {@link #maxFraction} or {@link #maxDigits} instead to maximize - * performance. For more information, read the following blog post. + * {@link #minSignificantDigits}, will trigger complex algorithm similar to Dragon4 to determine the + * low-order digits and the number of digits to display based on the value of the double. + * If the number of fraction places or significant digits can be bounded, consider using {@link #maxFraction} + * or {@link #maxSignificantDigits} instead to maximize performance. + * For more information, read the following blog post. * *
* http://www.serpentine.com/blog/2011/06/29/here-be-dragons-advances-in-problems-you-didnt-even-know-you-had/ @@ -555,7 +556,7 @@ class U_I18N_API Precision : public UMemory { * pad with zeros to ensure that this number of significant digits/figures are always shown. * *
- * This method is equivalent to {@link #minMaxDigits} with both arguments equal. + * This method is equivalent to {@link #minMaxSignificantDigits} with both arguments equal. * * @param minMaxSignificantDigits * The minimum and maximum number of significant digits to display (rounding if too long or padding with @@ -2436,6 +2437,8 @@ class U_I18N_API FormattedNumber : public UMemory, public FormattedValue { * field in the output string. This allows you to determine the locations of, for example, * the integer part, fraction part, or symbols. * + * This is a simpler but less powerful alternative to {@link #nextPosition}. + * * If a field occurs just once, calling this method will find that occurrence and return it. If a * field occurs multiple times, this method may be called repeatedly with the following pattern: * @@ -2447,7 +2450,7 @@ class U_I18N_API FormattedNumber : public UMemory, public FormattedValue { * * * This method is useful if you know which field to query. If you want all available field position - * information, use #getAllFieldPositions(). + * information, use {@link #nextPosition} or {@link #getAllFieldPositions}. * * @param fieldPosition * Input+output variable. On input, the "field" property determines which field to look @@ -2468,7 +2471,9 @@ class U_I18N_API FormattedNumber : public UMemory, public FormattedValue { * Export the formatted number to a FieldPositionIterator. This allows you to determine which characters in * the output string correspond to which fields, such as the integer part, fraction part, and sign. * - * If information on only one field is needed, use #nextFieldPosition() instead. + * This is an alternative to the more powerful #nextPosition() API. + * + * If information on only one field is needed, use #nextPosition() or #nextFieldPosition() instead. * * @param iterator * The FieldPositionIterator to populate with all of the fields present in the formatted number. diff --git a/icu4c/source/i18n/unicode/unumberformatter.h b/icu4c/source/i18n/unicode/unumberformatter.h index c2e406147e6..96bbbd263dc 100644 --- a/icu4c/source/i18n/unicode/unumberformatter.h +++ b/icu4c/source/i18n/unicode/unumberformatter.h @@ -571,6 +571,11 @@ unumf_resultAsFormattedValue(const UFormattedNumber* uresult, UErrorCode* ec); * If bufferCapacity is greater than the required length, a terminating NUL is written. * If bufferCapacity is less than the required length, an error code is set. * + * Also see ufmtval_getString, which returns a NUL-terminated string: + * + * int32_t len; + * const UChar* str = ufmtval_getString(unumf_resultAsFormattedValue(uresult, &ec), &len, &ec); + * * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead. * * @param uresult The object containing the formatted number. @@ -590,6 +595,8 @@ unumf_resultToString(const UFormattedNumber* uresult, UChar* buffer, int32_t buf * output string. This allows you to determine the locations of, for example, the integer part, * fraction part, or symbols. * + * This is a simpler but less powerful alternative to {@link ufmtval_nextPosition}. + * * If a field occurs just once, calling this method will find that occurrence and return it. If a * field occurs multiple times, this method may be called repeatedly with the following pattern: * @@ -624,7 +631,10 @@ unumf_resultNextFieldPosition(const UFormattedNumber* uresult, UFieldPosition* u * Populates the given iterator with all fields in the formatted output string. This allows you to * determine the locations of the integer part, fraction part, and sign. * - * If you need information on only one field, use unumf_resultNextFieldPosition(). + * This is an alternative to the more powerful {@link ufmtval_nextPosition} API. + * + * If you need information on only one field, use {@link ufmtval_nextPosition} or + * {@link unumf_resultNextFieldPosition}. * * @param uresult The object containing the formatted number. * @param ufpositer diff --git a/icu4j/main/classes/core/src/com/ibm/icu/number/FormattedNumber.java b/icu4j/main/classes/core/src/com/ibm/icu/number/FormattedNumber.java index 4e411ff99e9..24a78ae04a9 100644 --- a/icu4j/main/classes/core/src/com/ibm/icu/number/FormattedNumber.java +++ b/icu4j/main/classes/core/src/com/ibm/icu/number/FormattedNumber.java @@ -105,9 +105,11 @@ public class FormattedNumber implements FormattedValue { } /** - * Determines the start and end indices of the next occurrence of the given field in the - * output string. This allows you to determine the locations of, for example, the integer part, - * fraction part, or symbols. + * Determines the start (inclusive) and end (exclusive) indices of the next occurrence of the + * given field in the output string. This allows you to determine the locations of, + * for example, the integer part, fraction part, or symbols. + *
+ * This is a simpler but less powerful alternative to {@link #nextPosition}. *
* If a field occurs just once, calling this method will find that occurrence and return it. If a * field occurs multiple times, this method may be called repeatedly with the following pattern: @@ -120,7 +122,7 @@ public class FormattedNumber implements FormattedValue { * *
* This method is useful if you know which field to query. If you want all available field position - * information, use {@link #toCharacterIterator()}. + * information, use {@link #nextPosition} or {@link #toCharacterIterator()}. * * @param fieldPosition * Input+output variable. On input, the "field" property determines which field to look