1 // © 2022 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 4 #ifndef __SIMPLENUMBERFORMATTERH__ 5 #define __SIMPLENUMBERFORMATTERH__ 6 7 #include "unicode/utypes.h" 8 9 #if U_SHOW_CPLUSPLUS_API 10 11 #if !UCONFIG_NO_FORMATTING 12 13 #include "unicode/dcfmtsym.h" 14 #include "unicode/usimplenumberformatter.h" 15 #include "unicode/formattednumber.h" 16 17 /** 18 * \file 19 * \brief C++ API: Simple number formatting focused on low memory and code size. 20 * 21 * These functions render locale-aware number strings but without the bells and whistles found in 22 * other number formatting APIs such as those in numberformatter.h, like units and currencies. 23 * 24 * <pre> 25 * SimpleNumberFormatter snf = SimpleNumberFormatter::forLocale("de-CH", status); 26 * FormattedNumber result = snf.formatInt64(-1000007, status); 27 * assertEquals("", u"-1’000’007", result.toString(status)); 28 * </pre> 29 */ 30 31 U_NAMESPACE_BEGIN 32 33 34 namespace number { // icu::number 35 36 37 namespace impl { 38 class UFormattedNumberData; 39 struct SimpleMicroProps; 40 class AdoptingSignumModifierStore; 41 } // icu::number::impl 42 43 44 #ifndef U_HIDE_DRAFT_API 45 46 47 /** 48 * An input type for SimpleNumberFormatter. 49 * 50 * This class is mutable and not intended for public subclassing. This class is movable but not copyable. 51 * 52 * @draft ICU 73 53 */ 54 class U_I18N_API SimpleNumber : public UMemory { 55 public: 56 /** 57 * Creates a SimpleNumber for an integer. 58 * 59 * @draft ICU 73 60 */ 61 static SimpleNumber forInt64(int64_t value, UErrorCode& status); 62 63 /** 64 * Changes the value of the SimpleNumber by a power of 10. 65 * 66 * This function immediately mutates the inner value. 67 * 68 * @draft ICU 73 69 */ 70 void multiplyByPowerOfTen(int32_t power, UErrorCode& status); 71 72 /** 73 * Rounds the value currently stored in the SimpleNumber to the given power of 10. 74 * 75 * This function immediately mutates the inner value. 76 * 77 * @draft ICU 73 78 */ 79 void roundTo(int32_t power, UNumberFormatRoundingMode roundingMode, UErrorCode& status); 80 81 /** 82 * Truncates the most significant digits to the given maximum number of integer digits. 83 * 84 * This function immediately mutates the inner value. 85 * 86 * @draft ICU 73 87 */ 88 void truncateStart(uint32_t maximumIntegerDigits, UErrorCode& status); 89 90 /** 91 * Pads the beginning of the number with zeros up to the given minimum number of integer digits. 92 * 93 * This setting is applied upon formatting the number. 94 * 95 * @draft ICU 73 96 */ 97 void setMinimumIntegerDigits(uint32_t minimumIntegerDigits, UErrorCode& status); 98 99 /** 100 * Pads the end of the number with zeros up to the given minimum number of fraction digits. 101 * 102 * This setting is applied upon formatting the number. 103 * 104 * @draft ICU 73 105 */ 106 void setMinimumFractionDigits(uint32_t minimumFractionDigits, UErrorCode& status); 107 108 /** 109 * Sets the sign of the number: an explicit plus sign, explicit minus sign, or no sign. 110 * 111 * This setting is applied upon formatting the number. 112 * 113 * NOTE: This does not support accounting sign notation. 114 * 115 * @draft ICU 73 116 */ 117 void setSign(USimpleNumberSign sign, UErrorCode& status); 118 119 /** 120 * Creates a new, empty SimpleNumber that does not contain a value. 121 * 122 * NOTE: This number will fail to format; use forInt64() to create a SimpleNumber with a value. 123 * 124 * @draft ICU 73 125 */ 126 SimpleNumber() = default; 127 128 /** 129 * Destruct this SimpleNumber, cleaning up any memory it might own. 130 * 131 * @draft ICU 73 132 */ ~SimpleNumber()133 ~SimpleNumber() { 134 cleanup(); 135 } 136 137 /** 138 * SimpleNumber move constructor. 139 * 140 * @draft ICU 73 141 */ SimpleNumber(SimpleNumber && other)142 SimpleNumber(SimpleNumber&& other) noexcept { 143 fData = other.fData; 144 fSign = other.fSign; 145 other.fData = nullptr; 146 } 147 148 /** 149 * SimpleNumber move assignment. 150 * 151 * @draft ICU 73 152 */ 153 SimpleNumber& operator=(SimpleNumber&& other) noexcept { 154 cleanup(); 155 fData = other.fData; 156 fSign = other.fSign; 157 other.fData = nullptr; 158 return *this; 159 } 160 161 private: 162 SimpleNumber(impl::UFormattedNumberData* data, UErrorCode& status); 163 SimpleNumber(const SimpleNumber&) = delete; 164 SimpleNumber& operator=(const SimpleNumber&) = delete; 165 166 void cleanup(); 167 168 impl::UFormattedNumberData* fData = nullptr; 169 USimpleNumberSign fSign = UNUM_SIMPLE_NUMBER_NO_SIGN; 170 171 friend class SimpleNumberFormatter; 172 }; 173 174 175 /** 176 * A special NumberFormatter focused on smaller binary size and memory use. 177 * 178 * SimpleNumberFormatter is capable of basic number formatting, including grouping separators, 179 * sign display, and rounding. It is not capable of currencies, compact notation, or units. 180 * 181 * This class is immutable and not intended for public subclassing. This class is movable but not copyable. 182 * 183 * @draft ICU 73 184 */ 185 class U_I18N_API SimpleNumberFormatter : public UMemory { 186 public: 187 /** 188 * Creates a new SimpleNumberFormatter with all locale defaults. 189 * 190 * @draft ICU 73 191 */ 192 static SimpleNumberFormatter forLocale( 193 const icu::Locale &locale, 194 UErrorCode &status); 195 196 /** 197 * Creates a new SimpleNumberFormatter, overriding the grouping strategy. 198 * 199 * @draft ICU 73 200 */ 201 static SimpleNumberFormatter forLocaleAndGroupingStrategy( 202 const icu::Locale &locale, 203 UNumberGroupingStrategy groupingStrategy, 204 UErrorCode &status); 205 206 /** 207 * Creates a new SimpleNumberFormatter, overriding the grouping strategy and symbols. 208 * 209 * IMPORTANT: For efficiency, this function borrows the symbols. The symbols MUST remain valid 210 * for the lifetime of the SimpleNumberFormatter. 211 * 212 * @draft ICU 73 213 */ 214 static SimpleNumberFormatter forLocaleAndSymbolsAndGroupingStrategy( 215 const icu::Locale &locale, 216 const DecimalFormatSymbols &symbols, 217 UNumberGroupingStrategy groupingStrategy, 218 UErrorCode &status); 219 220 /** 221 * Formats a value using this SimpleNumberFormatter. 222 * 223 * The SimpleNumber argument is "consumed". A new SimpleNumber object should be created for 224 * every formatting operation. 225 * 226 * @draft ICU 73 227 */ 228 FormattedNumber format(SimpleNumber value, UErrorCode &status) const; 229 230 /** 231 * Formats an integer using this SimpleNumberFormatter. 232 * 233 * For more control over the formatting, use SimpleNumber. 234 * 235 * @draft ICU 73 236 */ formatInt64(int64_t value,UErrorCode & status)237 FormattedNumber formatInt64(int64_t value, UErrorCode &status) const { 238 return format(SimpleNumber::forInt64(value, status), status); 239 } 240 241 #ifndef U_HIDE_INTERNAL_API 242 /** 243 * Run the formatter with the internal types. 244 * @internal 245 */ 246 void formatImpl(impl::UFormattedNumberData* data, USimpleNumberSign sign, UErrorCode& status) const; 247 #endif // U_HIDE_INTERNAL_API 248 249 /** 250 * Destruct this SimpleNumberFormatter, cleaning up any memory it might own. 251 * 252 * @draft ICU 73 253 */ ~SimpleNumberFormatter()254 ~SimpleNumberFormatter() { 255 cleanup(); 256 } 257 258 /** 259 * Creates a shell, initialized but non-functional SimpleNumberFormatter. 260 * 261 * @draft ICU 73 262 */ 263 SimpleNumberFormatter() = default; 264 265 /** 266 * SimpleNumberFormatter: Move constructor. 267 * 268 * @draft ICU 73 269 */ SimpleNumberFormatter(SimpleNumberFormatter && other)270 SimpleNumberFormatter(SimpleNumberFormatter&& other) noexcept { 271 fGroupingStrategy = other.fGroupingStrategy; 272 fOwnedSymbols = other.fOwnedSymbols; 273 fMicros = other.fMicros; 274 fPatternModifier = other.fPatternModifier; 275 other.fOwnedSymbols = nullptr; 276 other.fMicros = nullptr; 277 other.fPatternModifier = nullptr; 278 } 279 280 /** 281 * SimpleNumberFormatter: Move assignment. 282 * 283 * @draft ICU 73 284 */ 285 SimpleNumberFormatter& operator=(SimpleNumberFormatter&& other) noexcept { 286 cleanup(); 287 fGroupingStrategy = other.fGroupingStrategy; 288 fOwnedSymbols = other.fOwnedSymbols; 289 fMicros = other.fMicros; 290 fPatternModifier = other.fPatternModifier; 291 other.fOwnedSymbols = nullptr; 292 other.fMicros = nullptr; 293 other.fPatternModifier = nullptr; 294 return *this; 295 } 296 297 private: 298 void initialize( 299 const icu::Locale &locale, 300 const DecimalFormatSymbols &symbols, 301 UNumberGroupingStrategy groupingStrategy, 302 UErrorCode &status); 303 304 void cleanup(); 305 306 SimpleNumberFormatter(const SimpleNumberFormatter&) = delete; 307 308 SimpleNumberFormatter& operator=(const SimpleNumberFormatter&) = delete; 309 310 UNumberGroupingStrategy fGroupingStrategy = UNUM_GROUPING_AUTO; 311 312 // Owned Pointers: 313 DecimalFormatSymbols* fOwnedSymbols = nullptr; // can be empty 314 impl::SimpleMicroProps* fMicros = nullptr; 315 impl::AdoptingSignumModifierStore* fPatternModifier = nullptr; 316 }; 317 318 319 #endif // U_HIDE_DRAFT_API 320 321 } // namespace number 322 U_NAMESPACE_END 323 324 #endif /* #if !UCONFIG_NO_FORMATTING */ 325 326 #endif /* U_SHOW_CPLUSPLUS_API */ 327 328 #endif // __SIMPLENUMBERFORMATTERH__ 329 330