tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

usimplenumberformatter.h (7481B)

      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 /**
    160 * Sets the number of integer digits to the given amount, truncating if necessary.
    161 *
    162 * @stable ICU 75
    163 */
    164 U_CAPI void U_EXPORT2
    165 usnum_setMaximumIntegerDigits(USimpleNumber* unumber, int32_t maximumIntegerDigits, UErrorCode* ec);
    166 
    167 
    168 /**
    169 * Sets the sign of the number: an explicit plus sign, explicit minus sign, or no sign.
    170 *
    171 * This setting is applied upon formatting the number.
    172 *
    173 * NOTE: This does not support accounting sign notation.
    174 *
    175 * @stable ICU 73
    176 */
    177 U_CAPI void U_EXPORT2
    178 usnum_setSign(USimpleNumber* unumber, USimpleNumberSign sign, UErrorCode* ec);
    179 
    180 
    181 /**
    182 * Creates a new USimpleNumberFormatter with all locale defaults.
    183 *
    184 * @stable ICU 73
    185 */
    186 U_CAPI USimpleNumberFormatter* U_EXPORT2
    187 usnumf_openForLocale(const char* locale, UErrorCode* ec);
    188 
    189 
    190 /**
    191 * Creates a new USimpleNumberFormatter, overriding the grouping strategy.
    192 *
    193 * @stable ICU 73
    194 */
    195 U_CAPI USimpleNumberFormatter* U_EXPORT2
    196 usnumf_openForLocaleAndGroupingStrategy(
    197       const char* locale, UNumberGroupingStrategy groupingStrategy, UErrorCode* ec);
    198 
    199 
    200 /**
    201 * Formats a number using this SimpleNumberFormatter.
    202 *
    203 * The USimpleNumber is cleared after calling this function. It can be re-used via
    204 * usnum_setToInt64.
    205 *
    206 * @stable ICU 73
    207 */
    208 U_CAPI void U_EXPORT2
    209 usnumf_format(
    210    const USimpleNumberFormatter* uformatter,
    211    USimpleNumber* unumber,
    212    UFormattedNumber* uresult,
    213    UErrorCode* ec);
    214 
    215 
    216 /**
    217 * Formats an integer using this SimpleNumberFormatter.
    218 *
    219 * For more control over the formatting, use USimpleNumber.
    220 *
    221 * @stable ICU 73
    222 */
    223 U_CAPI void U_EXPORT2
    224 usnumf_formatInt64(
    225    const USimpleNumberFormatter* uformatter,
    226    int64_t value,
    227    UFormattedNumber* uresult,
    228    UErrorCode* ec);
    229 
    230 
    231 /**
    232 * Frees the memory held by a USimpleNumber.
    233 *
    234 * NOTE: Normally, a USimpleNumber should be adopted by usnumf_formatAndAdoptNumber.
    235 *
    236 * @stable ICU 73
    237 */
    238 U_CAPI void U_EXPORT2
    239 usnum_close(USimpleNumber* unumber);
    240 
    241 
    242 /**
    243 * Frees the memory held by a USimpleNumberFormatter.
    244 *
    245 * @stable ICU 73
    246 */
    247 U_CAPI void U_EXPORT2
    248 usnumf_close(USimpleNumberFormatter* uformatter);
    249 
    250 
    251 #if U_SHOW_CPLUSPLUS_API
    252 U_NAMESPACE_BEGIN
    253 
    254 /**
    255 * \class LocalUSimpleNumberPointer
    256 * "Smart pointer" class; closes a USimpleNumber via usnum_close().
    257 * For most methods see the LocalPointerBase base class.
    258 *
    259 * NOTE: Normally, a USimpleNumber should be adopted by usnumf_formatAndAdoptNumber.
    260 * If you use LocalUSimpleNumberPointer, call `.orphan()` when passing to that function.
    261 *
    262 * Usage:
    263 * <pre>
    264 * LocalUSimpleNumberPointer uformatter(usnumf_openForInteger(...));
    265 * // no need to explicitly call usnum_close()
    266 * </pre>
    267 *
    268 * @see LocalPointerBase
    269 * @see LocalPointer
    270 * @stable ICU 73
    271 */
    272 U_DEFINE_LOCAL_OPEN_POINTER(LocalUSimpleNumberPointer, USimpleNumber, usnum_close);
    273 
    274 /**
    275 * \class LocalUSimpleNumberFormatterPointer
    276 * "Smart pointer" class; closes a USimpleNumberFormatter via usnumf_close().
    277 * For most methods see the LocalPointerBase base class.
    278 *
    279 * Usage:
    280 * <pre>
    281 * LocalUSimpleNumberFormatterPointer uformatter(usnumf_openForLocale(...));
    282 * // no need to explicitly call usnumf_close()
    283 * </pre>
    284 *
    285 * @see LocalPointerBase
    286 * @see LocalPointer
    287 * @stable ICU 73
    288 */
    289 U_DEFINE_LOCAL_OPEN_POINTER(LocalUSimpleNumberFormatterPointer, USimpleNumberFormatter, usnumf_close);
    290 
    291 U_NAMESPACE_END
    292 #endif // U_SHOW_CPLUSPLUS_API
    293 
    294 #endif /* #if !UCONFIG_NO_FORMATTING */
    295 #endif //__USIMPLENUMBERFORMATTER_H__