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 #ifndef U_HIDE_DRAFT_API 54 55 56 /** 57 * An explicit sign option for a SimpleNumber. 58 * 59 * @draft ICU 73 60 */ 61 typedef enum USimpleNumberSign { 62 /** 63 * Render a plus sign. 64 * 65 * @draft ICU 73 66 */ 67 UNUM_SIMPLE_NUMBER_PLUS_SIGN, 68 /** 69 * Render no sign. 70 * 71 * @draft ICU 73 72 */ 73 UNUM_SIMPLE_NUMBER_NO_SIGN, 74 /** 75 * Render a minus sign. 76 * 77 * @draft ICU 73 78 */ 79 UNUM_SIMPLE_NUMBER_MINUS_SIGN, 80 } USimpleNumberSign; 81 82 83 struct USimpleNumber; 84 /** 85 * C-compatible version of icu::number::SimpleNumber. 86 * 87 * @draft ICU 73 88 */ 89 typedef struct USimpleNumber USimpleNumber; 90 91 92 struct USimpleNumberFormatter; 93 /** 94 * C-compatible version of icu::number::SimpleNumberFormatter. 95 * 96 * @draft ICU 73 97 */ 98 typedef struct USimpleNumberFormatter USimpleNumberFormatter; 99 100 101 /** 102 * Creates a new USimpleNumber to be formatted with a USimpleNumberFormatter. 103 * 104 * @draft ICU 73 105 */ 106 U_CAPI USimpleNumber* U_EXPORT2 107 usnum_openForInt64(int64_t value, UErrorCode* ec); 108 109 110 /** 111 * Overwrites the value in a USimpleNumber to an int64_t. 112 * 113 * This can be used to reset the number value after formatting. 114 * 115 * @draft ICU 73 116 */ 117 U_CAPI void U_EXPORT2 118 usnum_setToInt64(USimpleNumber* unumber, int64_t value, UErrorCode* ec); 119 120 121 /** 122 * Changes the value of the USimpleNumber by a power of 10. 123 * 124 * This function immediately mutates the inner value. 125 * 126 * @draft ICU 73 127 */ 128 U_CAPI void U_EXPORT2 129 usnum_multiplyByPowerOfTen(USimpleNumber* unumber, int32_t power, UErrorCode* ec); 130 131 132 /** 133 * Rounds the value currently stored in the USimpleNumber to the given power of 10. 134 * 135 * This function immediately mutates the inner value. 136 * 137 * @draft ICU 73 138 */ 139 U_CAPI void U_EXPORT2 140 usnum_roundTo(USimpleNumber* unumber, int32_t power, UNumberFormatRoundingMode roundingMode, UErrorCode* ec); 141 142 143 /** 144 * Pads the beginning of the number with zeros up to the given minimum number of integer digits. 145 * 146 * This setting is applied upon formatting the number. 147 * 148 * @draft ICU 73 149 */ 150 U_CAPI void U_EXPORT2 151 usnum_setMinimumIntegerDigits(USimpleNumber* unumber, int32_t minimumIntegerDigits, UErrorCode* ec); 152 153 154 /** 155 * Pads the end of the number with zeros up to the given minimum number of fraction digits. 156 * 157 * This setting is applied upon formatting the number. 158 * 159 * @draft ICU 73 160 */ 161 U_CAPI void U_EXPORT2 162 usnum_setMinimumFractionDigits(USimpleNumber* unumber, int32_t minimumFractionDigits, UErrorCode* ec); 163 164 165 /** 166 * Truncates digits from the beginning of the number to the given maximum number of integer digits. 167 * 168 * This function immediately mutates the inner value. 169 * 170 * @draft ICU 73 171 */ 172 U_CAPI void U_EXPORT2 173 usnum_truncateStart(USimpleNumber* unumber, int32_t maximumIntegerDigits, UErrorCode* ec); 174 175 176 /** 177 * Sets the sign of the number: an explicit plus sign, explicit minus sign, or no sign. 178 * 179 * This setting is applied upon formatting the number. 180 * 181 * NOTE: This does not support accounting sign notation. 182 * 183 * @draft ICU 73 184 */ 185 U_CAPI void U_EXPORT2 186 usnum_setSign(USimpleNumber* unumber, USimpleNumberSign sign, UErrorCode* ec); 187 188 189 /** 190 * Creates a new USimpleNumberFormatter with all locale defaults. 191 * 192 * @draft ICU 73 193 */ 194 U_CAPI USimpleNumberFormatter* U_EXPORT2 195 usnumf_openForLocale(const char* locale, UErrorCode* ec); 196 197 198 /** 199 * Creates a new USimpleNumberFormatter, overriding the grouping strategy. 200 * 201 * @draft ICU 73 202 */ 203 U_CAPI USimpleNumberFormatter* U_EXPORT2 204 usnumf_openForLocaleAndGroupingStrategy( 205 const char* locale, UNumberGroupingStrategy groupingStrategy, UErrorCode* ec); 206 207 208 /** 209 * Formats a number using this SimpleNumberFormatter. 210 * 211 * The USimpleNumber is cleared after calling this function. It can be re-used via 212 * usnum_setToInt64. 213 * 214 * @draft ICU 73 215 */ 216 U_CAPI void U_EXPORT2 217 usnumf_format( 218 const USimpleNumberFormatter* uformatter, 219 USimpleNumber* unumber, 220 UFormattedNumber* uresult, 221 UErrorCode* ec); 222 223 224 /** 225 * Formats an integer using this SimpleNumberFormatter. 226 * 227 * For more control over the formatting, use USimpleNumber. 228 * 229 * @draft ICU 73 230 */ 231 U_CAPI void U_EXPORT2 232 usnumf_formatInt64( 233 const USimpleNumberFormatter* uformatter, 234 int64_t value, 235 UFormattedNumber* uresult, 236 UErrorCode* ec); 237 238 239 /** 240 * Frees the memory held by a USimpleNumber. 241 * 242 * NOTE: Normally, a USimpleNumber should be adopted by usnumf_formatAndAdoptNumber. 243 * 244 * @draft ICU 73 245 */ 246 U_CAPI void U_EXPORT2 247 usnum_close(USimpleNumber* unumber); 248 249 250 /** 251 * Frees the memory held by a USimpleNumberFormatter. 252 * 253 * @draft ICU 73 254 */ 255 U_CAPI void U_EXPORT2 256 usnumf_close(USimpleNumberFormatter* uformatter); 257 258 259 #if U_SHOW_CPLUSPLUS_API 260 U_NAMESPACE_BEGIN 261 262 /** 263 * \class LocalUSimpleNumberPointer 264 * "Smart pointer" class; closes a USimpleNumber via usnum_close(). 265 * For most methods see the LocalPointerBase base class. 266 * 267 * NOTE: Normally, a USimpleNumber should be adopted by usnumf_formatAndAdoptNumber. 268 * If you use LocalUSimpleNumberPointer, call `.orphan()` when passing to that function. 269 * 270 * Usage: 271 * <pre> 272 * LocalUSimpleNumberPointer uformatter(usnumf_openForInteger(...)); 273 * // no need to explicitly call usnum_close() 274 * </pre> 275 * 276 * @see LocalPointerBase 277 * @see LocalPointer 278 * @draft ICU 73 279 */ 280 U_DEFINE_LOCAL_OPEN_POINTER(LocalUSimpleNumberPointer, USimpleNumber, usnum_close); 281 282 /** 283 * \class LocalUSimpleNumberFormatterPointer 284 * "Smart pointer" class; closes a USimpleNumberFormatter via usnumf_close(). 285 * For most methods see the LocalPointerBase base class. 286 * 287 * Usage: 288 * <pre> 289 * LocalUSimpleNumberFormatterPointer uformatter(usnumf_openForLocale(...)); 290 * // no need to explicitly call usnumf_close() 291 * </pre> 292 * 293 * @see LocalPointerBase 294 * @see LocalPointer 295 * @draft ICU 73 296 */ 297 U_DEFINE_LOCAL_OPEN_POINTER(LocalUSimpleNumberFormatterPointer, USimpleNumberFormatter, usnumf_close); 298 299 U_NAMESPACE_END 300 #endif // U_SHOW_CPLUSPLUS_API 301 302 #endif // U_HIDE_DRAFT_API 303 304 #endif /* #if !UCONFIG_NO_FORMATTING */ 305 #endif //__USIMPLENUMBERFORMATTER_H__ 306