1 // © 2022 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 4 #ifndef __USIMPLENUMBERFORMATTER_H__ 5 #define __USIMPLENUMBERFORMATTER_H__ 6 7 #include "unicode/utypes.h" 8 9 #if !UCONFIG_NO_FORMATTING 10 11 #include "unicode/uformattednumber.h" 12 #include "unicode/unumberoptions.h" 13 14 /** 15 * \file 16 * \brief C API: Simple number formatting focused on low memory and code size. 17 * 18 * These functions render locale-aware number strings but without the bells and whistles found in 19 * other number formatting APIs such as those in unumberformatter.h, like units and currencies. 20 * 21 * Example using C++ helpers: 22 * 23 * <pre> 24 * LocalUSimpleNumberFormatterPointer uformatter(usnumf_openForLocale("de-CH", status)); 25 * LocalUFormattedNumberPointer uresult(unumf_openResult(status)); 26 * usnumf_formatInt64(uformatter.getAlias(), 55, uresult.getAlias(), status); 27 * assertEquals("", 28 * u"55", 29 * ufmtval_getString(unumf_resultAsValue(uresult.getAlias(), status), nullptr, status)); 30 * </pre> 31 * 32 * Example using pure C: 33 * 34 * <pre> 35 * UErrorCode ec = U_ZERO_ERROR; 36 * USimpleNumberFormatter* uformatter = usnumf_openForLocale("bn", &ec); 37 * USimpleNumber* unumber = usnum_openForInt64(1000007, &ec); 38 * UFormattedNumber* uresult = unumf_openResult(&ec); 39 * usnumf_format(uformatter, unumber, uresult, &ec); 40 * int32_t len; 41 * const UChar* str = ufmtval_getString(unumf_resultAsValue(uresult, &ec), &len, &ec); 42 * if (assertSuccess("Formatting end-to-end", &ec)) { 43 * assertUEquals("Should produce a result in Bangla digits", u"১০,০০,০০৭", str); 44 * } 45 46 * // Cleanup: 47 * unumf_closeResult(uresult); 48 * usnum_close(unumber); 49 * usnumf_close(uformatter); 50 * </pre> 51 */ 52 53 /** 54 * An explicit sign option for a SimpleNumber. 55 * 56 * @stable ICU 73 57 */ 58 typedef enum USimpleNumberSign { 59 /** 60 * Render a plus sign. 61 * 62 * @stable ICU 73 63 */ 64 UNUM_SIMPLE_NUMBER_PLUS_SIGN, 65 /** 66 * Render no sign. 67 * 68 * @stable ICU 73 69 */ 70 UNUM_SIMPLE_NUMBER_NO_SIGN, 71 /** 72 * Render a minus sign. 73 * 74 * @stable ICU 73 75 */ 76 UNUM_SIMPLE_NUMBER_MINUS_SIGN, 77 } USimpleNumberSign; 78 79 80 struct USimpleNumber; 81 /** 82 * C-compatible version of icu::number::SimpleNumber. 83 * 84 * @stable ICU 73 85 */ 86 typedef struct USimpleNumber USimpleNumber; 87 88 89 struct USimpleNumberFormatter; 90 /** 91 * C-compatible version of icu::number::SimpleNumberFormatter. 92 * 93 * @stable ICU 73 94 */ 95 typedef struct USimpleNumberFormatter USimpleNumberFormatter; 96 97 98 /** 99 * Creates a new USimpleNumber to be formatted with a USimpleNumberFormatter. 100 * 101 * @stable ICU 73 102 */ 103 U_CAPI USimpleNumber* U_EXPORT2 104 usnum_openForInt64(int64_t value, UErrorCode* ec); 105 106 107 /** 108 * Overwrites the value in a USimpleNumber to an int64_t. 109 * 110 * This can be used to reset the number value after formatting. 111 * 112 * @stable ICU 73 113 */ 114 U_CAPI void U_EXPORT2 115 usnum_setToInt64(USimpleNumber* unumber, int64_t value, UErrorCode* ec); 116 117 118 /** 119 * Changes the value of the USimpleNumber by a power of 10. 120 * 121 * This function immediately mutates the inner value. 122 * 123 * @stable ICU 73 124 */ 125 U_CAPI void U_EXPORT2 126 usnum_multiplyByPowerOfTen(USimpleNumber* unumber, int32_t power, UErrorCode* ec); 127 128 129 /** 130 * Rounds the value currently stored in the USimpleNumber to the given power of 10, 131 * which can be before or after the decimal separator. 132 * 133 * This function does not change minimum integer digits. 134 * 135 * @stable ICU 73 136 */ 137 U_CAPI void U_EXPORT2 138 usnum_roundTo(USimpleNumber* unumber, int32_t power, UNumberFormatRoundingMode roundingMode, UErrorCode* ec); 139 140 141 /** 142 * Pads the beginning of the number with zeros up to the given minimum number of integer digits. 143 * 144 * @stable ICU 73 145 */ 146 U_CAPI void U_EXPORT2 147 usnum_setMinimumIntegerDigits(USimpleNumber* unumber, int32_t minimumIntegerDigits, UErrorCode* ec); 148 149 150 /** 151 * Pads the end of the number with zeros up to the given minimum number of fraction digits. 152 * 153 * @stable ICU 73 154 */ 155 U_CAPI void U_EXPORT2 156 usnum_setMinimumFractionDigits(USimpleNumber* unumber, int32_t minimumFractionDigits, UErrorCode* ec); 157 158 159 #ifndef U_HIDE_DRAFT_API 160 /** 161 * Sets the number of integer digits to the given amount, truncating if necessary. 162 * 163 * @draft ICU 75 164 */ 165 U_CAPI void U_EXPORT2 166 usnum_setMaximumIntegerDigits(USimpleNumber* unumber, int32_t maximumIntegerDigits, UErrorCode* ec); 167 #endif // U_HIDE_DRAFT_API 168 169 170 /** 171 * Sets the sign of the number: an explicit plus sign, explicit minus sign, or no sign. 172 * 173 * This setting is applied upon formatting the number. 174 * 175 * NOTE: This does not support accounting sign notation. 176 * 177 * @stable ICU 73 178 */ 179 U_CAPI void U_EXPORT2 180 usnum_setSign(USimpleNumber* unumber, USimpleNumberSign sign, UErrorCode* ec); 181 182 183 /** 184 * Creates a new USimpleNumberFormatter with all locale defaults. 185 * 186 * @stable ICU 73 187 */ 188 U_CAPI USimpleNumberFormatter* U_EXPORT2 189 usnumf_openForLocale(const char* locale, UErrorCode* ec); 190 191 192 /** 193 * Creates a new USimpleNumberFormatter, overriding the grouping strategy. 194 * 195 * @stable ICU 73 196 */ 197 U_CAPI USimpleNumberFormatter* U_EXPORT2 198 usnumf_openForLocaleAndGroupingStrategy( 199 const char* locale, UNumberGroupingStrategy groupingStrategy, UErrorCode* ec); 200 201 202 /** 203 * Formats a number using this SimpleNumberFormatter. 204 * 205 * The USimpleNumber is cleared after calling this function. It can be re-used via 206 * usnum_setToInt64. 207 * 208 * @stable ICU 73 209 */ 210 U_CAPI void U_EXPORT2 211 usnumf_format( 212 const USimpleNumberFormatter* uformatter, 213 USimpleNumber* unumber, 214 UFormattedNumber* uresult, 215 UErrorCode* ec); 216 217 218 /** 219 * Formats an integer using this SimpleNumberFormatter. 220 * 221 * For more control over the formatting, use USimpleNumber. 222 * 223 * @stable ICU 73 224 */ 225 U_CAPI void U_EXPORT2 226 usnumf_formatInt64( 227 const USimpleNumberFormatter* uformatter, 228 int64_t value, 229 UFormattedNumber* uresult, 230 UErrorCode* ec); 231 232 233 /** 234 * Frees the memory held by a USimpleNumber. 235 * 236 * NOTE: Normally, a USimpleNumber should be adopted by usnumf_formatAndAdoptNumber. 237 * 238 * @stable ICU 73 239 */ 240 U_CAPI void U_EXPORT2 241 usnum_close(USimpleNumber* unumber); 242 243 244 /** 245 * Frees the memory held by a USimpleNumberFormatter. 246 * 247 * @stable ICU 73 248 */ 249 U_CAPI void U_EXPORT2 250 usnumf_close(USimpleNumberFormatter* uformatter); 251 252 253 #if U_SHOW_CPLUSPLUS_API 254 U_NAMESPACE_BEGIN 255 256 /** 257 * \class LocalUSimpleNumberPointer 258 * "Smart pointer" class; closes a USimpleNumber via usnum_close(). 259 * For most methods see the LocalPointerBase base class. 260 * 261 * NOTE: Normally, a USimpleNumber should be adopted by usnumf_formatAndAdoptNumber. 262 * If you use LocalUSimpleNumberPointer, call `.orphan()` when passing to that function. 263 * 264 * Usage: 265 * <pre> 266 * LocalUSimpleNumberPointer uformatter(usnumf_openForInteger(...)); 267 * // no need to explicitly call usnum_close() 268 * </pre> 269 * 270 * @see LocalPointerBase 271 * @see LocalPointer 272 * @stable ICU 73 273 */ 274 U_DEFINE_LOCAL_OPEN_POINTER(LocalUSimpleNumberPointer, USimpleNumber, usnum_close); 275 276 /** 277 * \class LocalUSimpleNumberFormatterPointer 278 * "Smart pointer" class; closes a USimpleNumberFormatter via usnumf_close(). 279 * For most methods see the LocalPointerBase base class. 280 * 281 * Usage: 282 * <pre> 283 * LocalUSimpleNumberFormatterPointer uformatter(usnumf_openForLocale(...)); 284 * // no need to explicitly call usnumf_close() 285 * </pre> 286 * 287 * @see LocalPointerBase 288 * @see LocalPointer 289 * @stable ICU 73 290 */ 291 U_DEFINE_LOCAL_OPEN_POINTER(LocalUSimpleNumberFormatterPointer, USimpleNumberFormatter, usnumf_close); 292 293 U_NAMESPACE_END 294 #endif // U_SHOW_CPLUSPLUS_API 295 296 #endif /* #if !UCONFIG_NO_FORMATTING */ 297 #endif //__USIMPLENUMBERFORMATTER_H__ 298