include/unicode/formattednumber.h

0001 // © 2022 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003
0004 #ifndef __FORMATTEDNUMBER_H__
0005 #define __FORMATTEDNUMBER_H__
0006
0007 #include "unicode/utypes.h"
0008
0009 #if U_SHOW_CPLUSPLUS_API
0010
0011 #if !UCONFIG_NO_FORMATTING
0012
0013 #include "unicode/uobject.h"
0014 #include "unicode/formattedvalue.h"
0015 #include "unicode/measunit.h"
0016 #include "unicode/udisplayoptions.h"
0017
0018 /**
0019  * \file
0020  * \brief C API: Formatted number result from various number formatting functions.
0021  *
0022  * See also {@link icu::FormattedValue} for additional things you can do with a FormattedNumber.
0023  */
0024
0025 U_NAMESPACE_BEGIN
0026
0027 class FieldPositionIteratorHandler;
0028
0029 namespace number {  // icu::number
0030
0031 namespace impl {
0032 class DecimalQuantity;
0033 class UFormattedNumberData;
0034 struct UFormattedNumberImpl;
0035 }  // icu::number::impl
0036
0037
0038
0039 /**
0040  * The result of a number formatting operation. This class allows the result to be exported in several data types,
0041  * including a UnicodeString and a FieldPositionIterator.
0042  *
0043  * Instances of this class are immutable and thread-safe.
0044  *
0045  * @stable ICU 60
0046  */
0047 class U_I18N_API FormattedNumber : public UMemory, public FormattedValue {
0048   public:
0049
0050     /**
0051      * Default constructor; makes an empty FormattedNumber.
0052      * @stable ICU 64
0053      */
0054     FormattedNumber()
0055         : fData(nullptr), fErrorCode(U_INVALID_STATE_ERROR) {}
0056
0057     /**
0058      * Move constructor: Leaves the source FormattedNumber in an undefined state.
0059      * @stable ICU 62
0060      */
0061     FormattedNumber(FormattedNumber&& src) noexcept;
0062
0063     /**
0064      * Destruct an instance of FormattedNumber.
0065      * @stable ICU 60
0066      */
0067     virtual ~FormattedNumber() override;
0068
0069     /** Copying not supported; use move constructor instead. */
0070     FormattedNumber(const FormattedNumber&) = delete;
0071
0072     /** Copying not supported; use move assignment instead. */
0073     FormattedNumber& operator=(const FormattedNumber&) = delete;
0074
0075     /**
0076      * Move assignment: Leaves the source FormattedNumber in an undefined state.
0077      * @stable ICU 62
0078      */
0079     FormattedNumber& operator=(FormattedNumber&& src) noexcept;
0080
0081     // Copybrief: this method is older than the parent method
0082     /**
0083      * @copybrief FormattedValue::toString()
0084      *
0085      * For more information, see FormattedValue::toString()
0086      *
0087      * @stable ICU 62
0088      */
0089     UnicodeString toString(UErrorCode& status) const override;
0090
0091     // Copydoc: this method is new in ICU 64
0092     /** @copydoc FormattedValue::toTempString() */
0093     UnicodeString toTempString(UErrorCode& status) const override;
0094
0095     // Copybrief: this method is older than the parent method
0096     /**
0097      * @copybrief FormattedValue::appendTo()
0098      *
0099      * For more information, see FormattedValue::appendTo()
0100      *
0101      * @stable ICU 62
0102      */
0103     Appendable &appendTo(Appendable& appendable, UErrorCode& status) const override;
0104
0105     // Copydoc: this method is new in ICU 64
0106     /** @copydoc FormattedValue::nextPosition() */
0107     UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const override;
0108
0109     /**
0110      * Export the formatted number as a "numeric string" conforming to the
0111      * syntax defined in the Decimal Arithmetic Specification, available at
0112      * http://speleotrove.com/decimal
0113      *
0114      * This endpoint is useful for obtaining the exact number being printed
0115      * after scaling and rounding have been applied by the number formatter.
0116      *
0117      * Example call site:
0118      *
0119      *     auto decimalNumber = fn.toDecimalNumber<std::string>(status);
0120      *
0121      * @tparam StringClass A string class compatible with StringByteSink;
0122      *         for example, std::string.
0123      * @param status Set if an error occurs.
0124      * @return A StringClass containing the numeric string.
0125      * @stable ICU 65
0126      */
0127     template<typename StringClass>
0128     inline StringClass toDecimalNumber(UErrorCode& status) const;
0129
0130     /**
0131      * Gets the resolved output unit.
0132      *
0133      * The output unit is dependent upon the localized preferences for the usage
0134      * specified via NumberFormatterSettings::usage(), and may be a unit with
0135      * UMEASURE_UNIT_MIXED unit complexity (MeasureUnit::getComplexity()), such
0136      * as "foot-and-inch" or "hour-and-minute-and-second".
0137      *
0138      * @return `MeasureUnit`.
0139      * @stable ICU 68
0140      */
0141     MeasureUnit getOutputUnit(UErrorCode& status) const;
0142
0143     /**
0144      * Gets the noun class of the formatted output. Returns `UNDEFINED` when the noun class
0145      * is not supported yet.
0146      *
0147      * @return UDisplayOptionsNounClass
0148      * @stable ICU 72
0149      */
0150     UDisplayOptionsNounClass getNounClass(UErrorCode &status) const;
0151
0152 #ifndef U_HIDE_INTERNAL_API
0153
0154     /**
0155      *  Gets the raw DecimalQuantity for plural rule selection.
0156      *  @internal
0157      */
0158     void getDecimalQuantity(impl::DecimalQuantity& output, UErrorCode& status) const;
0159
0160     /**
0161      * Populates the mutable builder type FieldPositionIteratorHandler.
0162      * @internal
0163      */
0164     void getAllFieldPositionsImpl(FieldPositionIteratorHandler& fpih, UErrorCode& status) const;
0165
0166 #endif  /* U_HIDE_INTERNAL_API */
0167
0168   private:
0169     // Can't use LocalPointer because UFormattedNumberData is forward-declared
0170     impl::UFormattedNumberData *fData;
0171
0172     // Error code for the terminal methods
0173     UErrorCode fErrorCode;
0174
0175     /**
0176      * Internal constructor from data type. Adopts the data pointer.
0177      * @internal (private)
0178      */
0179     explicit FormattedNumber(impl::UFormattedNumberData *results)
0180         : fData(results), fErrorCode(U_ZERO_ERROR) {}
0181
0182     explicit FormattedNumber(UErrorCode errorCode)
0183         : fData(nullptr), fErrorCode(errorCode) {}
0184
0185     void toDecimalNumber(ByteSink& sink, UErrorCode& status) const;
0186
0187     // To give LocalizedNumberFormatter format methods access to this class's constructor:
0188     friend class LocalizedNumberFormatter;
0189     friend class SimpleNumberFormatter;
0190
0191     // To give C API access to internals
0192     friend struct impl::UFormattedNumberImpl;
0193 };
0194
0195 template<typename StringClass>
0196 StringClass FormattedNumber::toDecimalNumber(UErrorCode& status) const {
0197     StringClass result;
0198     StringByteSink<StringClass> sink(&result);
0199     toDecimalNumber(sink, status);
0200     return result;
0201 }
0202
0203 }  // namespace number
0204 U_NAMESPACE_END
0205
0206 #endif /* #if !UCONFIG_NO_FORMATTING */
0207
0208 #endif /* U_SHOW_CPLUSPLUS_API */
0209
0210 #endif // __FORMATTEDNUMBER_H__
0211