1 // © 2022 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 4 #ifndef __UFORMATTEDNUMBER_H__ 5 #define __UFORMATTEDNUMBER_H__ 6 7 #include "unicode/utypes.h" 8 9 #if !UCONFIG_NO_FORMATTING 10 11 #include "unicode/ufieldpositer.h" 12 #include "unicode/uformattedvalue.h" 13 #include "unicode/umisc.h" 14 15 /** 16 * \file 17 * \brief C API: Formatted number result from various number formatting functions. 18 * 19 * Create a `UFormattedNumber` to hold the result of a number formatting operation. The same 20 * `UFormattedNumber` can be reused multiple times. 21 * 22 * <pre> 23 * LocalUFormattedNumberPointer uresult(unumf_openResult(status)); 24 * 25 * // pass uresult.getAlias() to your number formatter 26 * 27 * int32_t length; 28 * const UChar* s = ufmtval_getString(unumf_resultAsValue(uresult.getAlias(), status), &length, status)); 29 * 30 * // The string result is in `s` with the given `length` (it is also NUL-terminated). 31 * </pre> 32 */ 33 34 35 struct UFormattedNumber; 36 /** 37 * C-compatible version of icu::number::FormattedNumber. 38 * 39 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead. 40 * 41 * @stable ICU 62 42 */ 43 typedef struct UFormattedNumber UFormattedNumber; 44 45 46 /** 47 * Creates an object to hold the result of a UNumberFormatter 48 * operation. The object can be used repeatedly; it is cleared whenever 49 * passed to a format function. 50 * 51 * @param ec Set if an error occurs. 52 * @stable ICU 62 53 */ 54 U_CAPI UFormattedNumber* U_EXPORT2 55 unumf_openResult(UErrorCode* ec); 56 57 58 /** 59 * Returns a representation of a UFormattedNumber as a UFormattedValue, 60 * which can be subsequently passed to any API requiring that type. 61 * 62 * The returned object is owned by the UFormattedNumber and is valid 63 * only as long as the UFormattedNumber is present and unchanged in memory. 64 * 65 * You can think of this method as a cast between types. 66 * 67 * @param uresult The object containing the formatted string. 68 * @param ec Set if an error occurs. 69 * @return A UFormattedValue owned by the input object. 70 * @stable ICU 64 71 */ 72 U_CAPI const UFormattedValue* U_EXPORT2 73 unumf_resultAsValue(const UFormattedNumber* uresult, UErrorCode* ec); 74 75 76 /** 77 * Extracts the result number string out of a UFormattedNumber to a UChar buffer if possible. 78 * If bufferCapacity is greater than the required length, a terminating NUL is written. 79 * If bufferCapacity is less than the required length, an error code is set. 80 * 81 * Also see ufmtval_getString, which returns a NUL-terminated string: 82 * 83 * int32_t len; 84 * const UChar* str = ufmtval_getString(unumf_resultAsValue(uresult, &ec), &len, &ec); 85 * 86 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead. 87 * 88 * @param uresult The object containing the formatted number. 89 * @param buffer Where to save the string output. 90 * @param bufferCapacity The number of UChars available in the buffer. 91 * @param ec Set if an error occurs. 92 * @return The required length. 93 * @stable ICU 62 94 */ 95 U_CAPI int32_t U_EXPORT2 96 unumf_resultToString(const UFormattedNumber* uresult, UChar* buffer, int32_t bufferCapacity, 97 UErrorCode* ec); 98 99 100 /** 101 * Determines the start and end indices of the next occurrence of the given <em>field</em> in the 102 * output string. This allows you to determine the locations of, for example, the integer part, 103 * fraction part, or symbols. 104 * 105 * This is a simpler but less powerful alternative to {@link ufmtval_nextPosition}. 106 * 107 * If a field occurs just once, calling this method will find that occurrence and return it. If a 108 * field occurs multiple times, this method may be called repeatedly with the following pattern: 109 * 110 * <pre> 111 * UFieldPosition ufpos = {UNUM_GROUPING_SEPARATOR_FIELD, 0, 0}; 112 * while (unumf_resultNextFieldPosition(uresult, ufpos, &ec)) { 113 * // do something with ufpos. 114 * } 115 * </pre> 116 * 117 * This method is useful if you know which field to query. If you want all available field position 118 * information, use unumf_resultGetAllFieldPositions(). 119 * 120 * NOTE: All fields of the UFieldPosition must be initialized before calling this method. 121 * 122 * @param uresult The object containing the formatted number. 123 * @param ufpos 124 * Input+output variable. On input, the "field" property determines which field to look up, 125 * and the "endIndex" property determines where to begin the search. On output, the 126 * "beginIndex" field is set to the beginning of the first occurrence of the field after the 127 * input "endIndex", and "endIndex" is set to the end of that occurrence of the field 128 * (exclusive index). If a field position is not found, the FieldPosition is not changed and 129 * the method returns false. 130 * @param ec Set if an error occurs. 131 * @stable ICU 62 132 */ 133 U_CAPI UBool U_EXPORT2 134 unumf_resultNextFieldPosition(const UFormattedNumber* uresult, UFieldPosition* ufpos, UErrorCode* ec); 135 136 137 /** 138 * Populates the given iterator with all fields in the formatted output string. This allows you to 139 * determine the locations of the integer part, fraction part, and sign. 140 * 141 * This is an alternative to the more powerful {@link ufmtval_nextPosition} API. 142 * 143 * If you need information on only one field, use {@link ufmtval_nextPosition} or 144 * {@link unumf_resultNextFieldPosition}. 145 * 146 * @param uresult The object containing the formatted number. 147 * @param ufpositer 148 * A pointer to a UFieldPositionIterator created by {@link #ufieldpositer_open}. Iteration 149 * information already present in the UFieldPositionIterator is deleted, and the iterator is reset 150 * to apply to the fields in the formatted string created by this function call. The field values 151 * and indexes returned by {@link #ufieldpositer_next} represent fields denoted by 152 * the UNumberFormatFields enum. Fields are not returned in a guaranteed order. Fields cannot 153 * overlap, but they may nest. For example, 1234 could format as "1,234" which might consist of a 154 * grouping separator field for ',' and an integer field encompassing the entire string. 155 * @param ec Set if an error occurs. 156 * @stable ICU 62 157 */ 158 U_CAPI void U_EXPORT2 159 unumf_resultGetAllFieldPositions(const UFormattedNumber* uresult, UFieldPositionIterator* ufpositer, 160 UErrorCode* ec); 161 162 163 /** 164 * Extracts the formatted number as a "numeric string" conforming to the 165 * syntax defined in the Decimal Arithmetic Specification, available at 166 * http://speleotrove.com/decimal 167 * 168 * This endpoint is useful for obtaining the exact number being printed 169 * after scaling and rounding have been applied by the number formatter. 170 * 171 * @param uresult The input object containing the formatted number. 172 * @param dest the 8-bit char buffer into which the decimal number is placed 173 * @param destCapacity The size, in chars, of the destination buffer. May be zero 174 * for precomputing the required size. 175 * @param ec receives any error status. 176 * If U_BUFFER_OVERFLOW_ERROR: Returns number of chars for 177 * preflighting. 178 * @return Number of chars in the data. Does not include a trailing NUL. 179 * @stable ICU 68 180 */ 181 U_CAPI int32_t U_EXPORT2 182 unumf_resultToDecimalNumber( 183 const UFormattedNumber* uresult, 184 char* dest, 185 int32_t destCapacity, 186 UErrorCode* ec); 187 188 189 /** 190 * Releases the UFormattedNumber created by unumf_openResult(). 191 * 192 * @param uresult An object created by unumf_openResult(). 193 * @stable ICU 62 194 */ 195 U_CAPI void U_EXPORT2 196 unumf_closeResult(UFormattedNumber* uresult); 197 198 199 #if U_SHOW_CPLUSPLUS_API 200 U_NAMESPACE_BEGIN 201 202 /** 203 * \class LocalUFormattedNumberPointer 204 * "Smart pointer" class; closes a UFormattedNumber via unumf_closeResult(). 205 * For most methods see the LocalPointerBase base class. 206 * 207 * Usage: 208 * <pre> 209 * LocalUFormattedNumberPointer uformatter(unumf_openResult(...)); 210 * // no need to explicitly call unumf_closeResult() 211 * </pre> 212 * 213 * @see LocalPointerBase 214 * @see LocalPointer 215 * @stable ICU 62 216 */ 217 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedNumberPointer, UFormattedNumber, unumf_closeResult); 218 219 U_NAMESPACE_END 220 #endif // U_SHOW_CPLUSPLUS_API 221 222 223 #endif /* #if !UCONFIG_NO_FORMATTING */ 224 #endif //__UFORMATTEDNUMBER_H__ 225