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