Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/numberrangeformatter.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 // © 2018 and later: Unicode, Inc. and others.
jpayne@69 2 // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69 3
jpayne@69 4 #ifndef __NUMBERRANGEFORMATTER_H__
jpayne@69 5 #define __NUMBERRANGEFORMATTER_H__
jpayne@69 6
jpayne@69 7 #include "unicode/utypes.h"
jpayne@69 8
jpayne@69 9 #if U_SHOW_CPLUSPLUS_API
jpayne@69 10
jpayne@69 11 #if !UCONFIG_NO_FORMATTING
jpayne@69 12
jpayne@69 13 #include <atomic>
jpayne@69 14 #include "unicode/appendable.h"
jpayne@69 15 #include "unicode/fieldpos.h"
jpayne@69 16 #include "unicode/formattedvalue.h"
jpayne@69 17 #include "unicode/fpositer.h"
jpayne@69 18 #include "unicode/numberformatter.h"
jpayne@69 19
jpayne@69 20 /**
jpayne@69 21 * \file
jpayne@69 22 * \brief C++ API: Library for localized formatting of number, currency, and unit ranges.
jpayne@69 23 *
jpayne@69 24 * The main entrypoint to the formatting of ranges of numbers, including currencies and other units of measurement.
jpayne@69 25 * <p>
jpayne@69 26 * Usage example:
jpayne@69 27 * <p>
jpayne@69 28 * <pre>
jpayne@69 29 * NumberRangeFormatter::with()
jpayne@69 30 * .identityFallback(UNUM_IDENTITY_FALLBACK_APPROXIMATELY_OR_SINGLE_VALUE)
jpayne@69 31 * .numberFormatterFirst(NumberFormatter::with().adoptUnit(MeasureUnit::createMeter()))
jpayne@69 32 * .numberFormatterSecond(NumberFormatter::with().adoptUnit(MeasureUnit::createKilometer()))
jpayne@69 33 * .locale("en-GB")
jpayne@69 34 * .formatRange(750, 1.2, status)
jpayne@69 35 * .toString(status);
jpayne@69 36 * // => "750 m - 1.2 km"
jpayne@69 37 * </pre>
jpayne@69 38 * <p>
jpayne@69 39 * Like NumberFormatter, NumberRangeFormatter instances (i.e., LocalizedNumberRangeFormatter
jpayne@69 40 * and UnlocalizedNumberRangeFormatter) are immutable and thread-safe. This API is based on the
jpayne@69 41 * <em>fluent</em> design pattern popularized by libraries such as Google's Guava.
jpayne@69 42 *
jpayne@69 43 * @author Shane Carr
jpayne@69 44 */
jpayne@69 45
jpayne@69 46
jpayne@69 47 /**
jpayne@69 48 * Defines how to merge fields that are identical across the range sign.
jpayne@69 49 *
jpayne@69 50 * @stable ICU 63
jpayne@69 51 */
jpayne@69 52 typedef enum UNumberRangeCollapse {
jpayne@69 53 /**
jpayne@69 54 * Use locale data and heuristics to determine how much of the string to collapse. Could end up collapsing none,
jpayne@69 55 * some, or all repeated pieces in a locale-sensitive way.
jpayne@69 56 *
jpayne@69 57 * The heuristics used for this option are subject to change over time.
jpayne@69 58 *
jpayne@69 59 * @stable ICU 63
jpayne@69 60 */
jpayne@69 61 UNUM_RANGE_COLLAPSE_AUTO,
jpayne@69 62
jpayne@69 63 /**
jpayne@69 64 * Do not collapse any part of the number. Example: "3.2 thousand kilograms – 5.3 thousand kilograms"
jpayne@69 65 *
jpayne@69 66 * @stable ICU 63
jpayne@69 67 */
jpayne@69 68 UNUM_RANGE_COLLAPSE_NONE,
jpayne@69 69
jpayne@69 70 /**
jpayne@69 71 * Collapse the unit part of the number, but not the notation, if present. Example: "3.2 thousand – 5.3 thousand
jpayne@69 72 * kilograms"
jpayne@69 73 *
jpayne@69 74 * @stable ICU 63
jpayne@69 75 */
jpayne@69 76 UNUM_RANGE_COLLAPSE_UNIT,
jpayne@69 77
jpayne@69 78 /**
jpayne@69 79 * Collapse any field that is equal across the range sign. May introduce ambiguity on the magnitude of the
jpayne@69 80 * number. Example: "3.2 – 5.3 thousand kilograms"
jpayne@69 81 *
jpayne@69 82 * @stable ICU 63
jpayne@69 83 */
jpayne@69 84 UNUM_RANGE_COLLAPSE_ALL
jpayne@69 85 } UNumberRangeCollapse;
jpayne@69 86
jpayne@69 87 /**
jpayne@69 88 * Defines the behavior when the two numbers in the range are identical after rounding. To programmatically detect
jpayne@69 89 * when the identity fallback is used, compare the lower and upper BigDecimals via FormattedNumber.
jpayne@69 90 *
jpayne@69 91 * @stable ICU 63
jpayne@69 92 * @see NumberRangeFormatter
jpayne@69 93 */
jpayne@69 94 typedef enum UNumberRangeIdentityFallback {
jpayne@69 95 /**
jpayne@69 96 * Show the number as a single value rather than a range. Example: "$5"
jpayne@69 97 *
jpayne@69 98 * @stable ICU 63
jpayne@69 99 */
jpayne@69 100 UNUM_IDENTITY_FALLBACK_SINGLE_VALUE,
jpayne@69 101
jpayne@69 102 /**
jpayne@69 103 * Show the number using a locale-sensitive approximation pattern. If the numbers were the same before rounding,
jpayne@69 104 * show the single value. Example: "~$5" or "$5"
jpayne@69 105 *
jpayne@69 106 * @stable ICU 63
jpayne@69 107 */
jpayne@69 108 UNUM_IDENTITY_FALLBACK_APPROXIMATELY_OR_SINGLE_VALUE,
jpayne@69 109
jpayne@69 110 /**
jpayne@69 111 * Show the number using a locale-sensitive approximation pattern. Use the range pattern always, even if the
jpayne@69 112 * inputs are the same. Example: "~$5"
jpayne@69 113 *
jpayne@69 114 * @stable ICU 63
jpayne@69 115 */
jpayne@69 116 UNUM_IDENTITY_FALLBACK_APPROXIMATELY,
jpayne@69 117
jpayne@69 118 /**
jpayne@69 119 * Show the number as the range of two equal values. Use the range pattern always, even if the inputs are the
jpayne@69 120 * same. Example (with RangeCollapse.NONE): "$5 – $5"
jpayne@69 121 *
jpayne@69 122 * @stable ICU 63
jpayne@69 123 */
jpayne@69 124 UNUM_IDENTITY_FALLBACK_RANGE
jpayne@69 125 } UNumberRangeIdentityFallback;
jpayne@69 126
jpayne@69 127 /**
jpayne@69 128 * Used in the result class FormattedNumberRange to indicate to the user whether the numbers formatted in the range
jpayne@69 129 * were equal or not, and whether or not the identity fallback was applied.
jpayne@69 130 *
jpayne@69 131 * @stable ICU 63
jpayne@69 132 * @see NumberRangeFormatter
jpayne@69 133 */
jpayne@69 134 typedef enum UNumberRangeIdentityResult {
jpayne@69 135 /**
jpayne@69 136 * Used to indicate that the two numbers in the range were equal, even before any rounding rules were applied.
jpayne@69 137 *
jpayne@69 138 * @stable ICU 63
jpayne@69 139 * @see NumberRangeFormatter
jpayne@69 140 */
jpayne@69 141 UNUM_IDENTITY_RESULT_EQUAL_BEFORE_ROUNDING,
jpayne@69 142
jpayne@69 143 /**
jpayne@69 144 * Used to indicate that the two numbers in the range were equal, but only after rounding rules were applied.
jpayne@69 145 *
jpayne@69 146 * @stable ICU 63
jpayne@69 147 * @see NumberRangeFormatter
jpayne@69 148 */
jpayne@69 149 UNUM_IDENTITY_RESULT_EQUAL_AFTER_ROUNDING,
jpayne@69 150
jpayne@69 151 /**
jpayne@69 152 * Used to indicate that the two numbers in the range were not equal, even after rounding rules were applied.
jpayne@69 153 *
jpayne@69 154 * @stable ICU 63
jpayne@69 155 * @see NumberRangeFormatter
jpayne@69 156 */
jpayne@69 157 UNUM_IDENTITY_RESULT_NOT_EQUAL,
jpayne@69 158
jpayne@69 159 #ifndef U_HIDE_INTERNAL_API
jpayne@69 160 /**
jpayne@69 161 * The number of entries in this enum.
jpayne@69 162 * @internal
jpayne@69 163 */
jpayne@69 164 UNUM_IDENTITY_RESULT_COUNT
jpayne@69 165 #endif
jpayne@69 166
jpayne@69 167 } UNumberRangeIdentityResult;
jpayne@69 168
jpayne@69 169 U_NAMESPACE_BEGIN
jpayne@69 170
jpayne@69 171 namespace number { // icu::number
jpayne@69 172
jpayne@69 173 // Forward declarations:
jpayne@69 174 class UnlocalizedNumberRangeFormatter;
jpayne@69 175 class LocalizedNumberRangeFormatter;
jpayne@69 176 class FormattedNumberRange;
jpayne@69 177
jpayne@69 178 namespace impl {
jpayne@69 179
jpayne@69 180 // Forward declarations:
jpayne@69 181 struct RangeMacroProps;
jpayne@69 182 class DecimalQuantity;
jpayne@69 183 class UFormattedNumberRangeData;
jpayne@69 184 class NumberRangeFormatterImpl;
jpayne@69 185
jpayne@69 186 } // namespace impl
jpayne@69 187
jpayne@69 188 /**
jpayne@69 189 * \cond
jpayne@69 190 * Export an explicit template instantiation. See datefmt.h
jpayne@69 191 * (When building DLLs for Windows this is required.)
jpayne@69 192 */
jpayne@69 193 #if U_PLATFORM == U_PF_WINDOWS && !defined(U_IN_DOXYGEN)
jpayne@69 194 } // namespace icu::number
jpayne@69 195 U_NAMESPACE_END
jpayne@69 196
jpayne@69 197 template struct U_I18N_API std::atomic< U_NAMESPACE_QUALIFIER number::impl::NumberRangeFormatterImpl*>;
jpayne@69 198
jpayne@69 199 U_NAMESPACE_BEGIN
jpayne@69 200 namespace number { // icu::number
jpayne@69 201 #endif
jpayne@69 202 /** \endcond */
jpayne@69 203
jpayne@69 204 // Other helper classes would go here, but there are none.
jpayne@69 205
jpayne@69 206 namespace impl { // icu::number::impl
jpayne@69 207
jpayne@69 208 // Do not enclose entire MacroProps with #ifndef U_HIDE_INTERNAL_API, needed for a protected field
jpayne@69 209 /** @internal */
jpayne@69 210 struct U_I18N_API RangeMacroProps : public UMemory {
jpayne@69 211 /** @internal */
jpayne@69 212 UnlocalizedNumberFormatter formatter1; // = NumberFormatter::with();
jpayne@69 213
jpayne@69 214 /** @internal */
jpayne@69 215 UnlocalizedNumberFormatter formatter2; // = NumberFormatter::with();
jpayne@69 216
jpayne@69 217 /** @internal */
jpayne@69 218 bool singleFormatter = true;
jpayne@69 219
jpayne@69 220 /** @internal */
jpayne@69 221 UNumberRangeCollapse collapse = UNUM_RANGE_COLLAPSE_AUTO;
jpayne@69 222
jpayne@69 223 /** @internal */
jpayne@69 224 UNumberRangeIdentityFallback identityFallback = UNUM_IDENTITY_FALLBACK_APPROXIMATELY;
jpayne@69 225
jpayne@69 226 /** @internal */
jpayne@69 227 Locale locale;
jpayne@69 228
jpayne@69 229 // NOTE: Uses default copy and move constructors.
jpayne@69 230
jpayne@69 231 /**
jpayne@69 232 * Check all members for errors.
jpayne@69 233 * @internal
jpayne@69 234 */
jpayne@69 235 bool copyErrorTo(UErrorCode &status) const {
jpayne@69 236 return formatter1.copyErrorTo(status) || formatter2.copyErrorTo(status);
jpayne@69 237 }
jpayne@69 238 };
jpayne@69 239
jpayne@69 240 } // namespace impl
jpayne@69 241
jpayne@69 242 /**
jpayne@69 243 * An abstract base class for specifying settings related to number formatting. This class is implemented by
jpayne@69 244 * {@link UnlocalizedNumberRangeFormatter} and {@link LocalizedNumberRangeFormatter}. This class is not intended for
jpayne@69 245 * public subclassing.
jpayne@69 246 */
jpayne@69 247 template<typename Derived>
jpayne@69 248 class U_I18N_API NumberRangeFormatterSettings {
jpayne@69 249 public:
jpayne@69 250 /**
jpayne@69 251 * Sets the NumberFormatter instance to use for the numbers in the range. The same formatter is applied to both
jpayne@69 252 * sides of the range.
jpayne@69 253 * <p>
jpayne@69 254 * The NumberFormatter instances must not have a locale applied yet; the locale specified on the
jpayne@69 255 * NumberRangeFormatter will be used.
jpayne@69 256 *
jpayne@69 257 * @param formatter
jpayne@69 258 * The formatter to use for both numbers in the range.
jpayne@69 259 * @return The fluent chain.
jpayne@69 260 * @stable ICU 63
jpayne@69 261 */
jpayne@69 262 Derived numberFormatterBoth(const UnlocalizedNumberFormatter &formatter) const &;
jpayne@69 263
jpayne@69 264 /**
jpayne@69 265 * Overload of numberFormatterBoth() for use on an rvalue reference.
jpayne@69 266 *
jpayne@69 267 * @param formatter
jpayne@69 268 * The formatter to use for both numbers in the range.
jpayne@69 269 * @return The fluent chain.
jpayne@69 270 * @see #numberFormatterBoth
jpayne@69 271 * @stable ICU 63
jpayne@69 272 */
jpayne@69 273 Derived numberFormatterBoth(const UnlocalizedNumberFormatter &formatter) &&;
jpayne@69 274
jpayne@69 275 /**
jpayne@69 276 * Overload of numberFormatterBoth() for use on an rvalue reference.
jpayne@69 277 *
jpayne@69 278 * @param formatter
jpayne@69 279 * The formatter to use for both numbers in the range.
jpayne@69 280 * @return The fluent chain.
jpayne@69 281 * @see #numberFormatterBoth
jpayne@69 282 * @stable ICU 63
jpayne@69 283 */
jpayne@69 284 Derived numberFormatterBoth(UnlocalizedNumberFormatter &&formatter) const &;
jpayne@69 285
jpayne@69 286 /**
jpayne@69 287 * Overload of numberFormatterBoth() for use on an rvalue reference.
jpayne@69 288 *
jpayne@69 289 * @param formatter
jpayne@69 290 * The formatter to use for both numbers in the range.
jpayne@69 291 * @return The fluent chain.
jpayne@69 292 * @see #numberFormatterBoth
jpayne@69 293 * @stable ICU 63
jpayne@69 294 */
jpayne@69 295 Derived numberFormatterBoth(UnlocalizedNumberFormatter &&formatter) &&;
jpayne@69 296
jpayne@69 297 /**
jpayne@69 298 * Sets the NumberFormatter instance to use for the first number in the range.
jpayne@69 299 * <p>
jpayne@69 300 * The NumberFormatter instances must not have a locale applied yet; the locale specified on the
jpayne@69 301 * NumberRangeFormatter will be used.
jpayne@69 302 *
jpayne@69 303 * @param formatterFirst
jpayne@69 304 * The formatter to use for the first number in the range.
jpayne@69 305 * @return The fluent chain.
jpayne@69 306 * @stable ICU 63
jpayne@69 307 */
jpayne@69 308 Derived numberFormatterFirst(const UnlocalizedNumberFormatter &formatterFirst) const &;
jpayne@69 309
jpayne@69 310 /**
jpayne@69 311 * Overload of numberFormatterFirst() for use on an rvalue reference.
jpayne@69 312 *
jpayne@69 313 * @param formatterFirst
jpayne@69 314 * The formatter to use for the first number in the range.
jpayne@69 315 * @return The fluent chain.
jpayne@69 316 * @see #numberFormatterFirst
jpayne@69 317 * @stable ICU 63
jpayne@69 318 */
jpayne@69 319 Derived numberFormatterFirst(const UnlocalizedNumberFormatter &formatterFirst) &&;
jpayne@69 320
jpayne@69 321 /**
jpayne@69 322 * Overload of numberFormatterFirst() for use on an rvalue reference.
jpayne@69 323 *
jpayne@69 324 * @param formatterFirst
jpayne@69 325 * The formatter to use for the first number in the range.
jpayne@69 326 * @return The fluent chain.
jpayne@69 327 * @see #numberFormatterFirst
jpayne@69 328 * @stable ICU 63
jpayne@69 329 */
jpayne@69 330 Derived numberFormatterFirst(UnlocalizedNumberFormatter &&formatterFirst) const &;
jpayne@69 331
jpayne@69 332 /**
jpayne@69 333 * Overload of numberFormatterFirst() for use on an rvalue reference.
jpayne@69 334 *
jpayne@69 335 * @param formatterFirst
jpayne@69 336 * The formatter to use for the first number in the range.
jpayne@69 337 * @return The fluent chain.
jpayne@69 338 * @see #numberFormatterFirst
jpayne@69 339 * @stable ICU 63
jpayne@69 340 */
jpayne@69 341 Derived numberFormatterFirst(UnlocalizedNumberFormatter &&formatterFirst) &&;
jpayne@69 342
jpayne@69 343 /**
jpayne@69 344 * Sets the NumberFormatter instance to use for the second number in the range.
jpayne@69 345 * <p>
jpayne@69 346 * The NumberFormatter instances must not have a locale applied yet; the locale specified on the
jpayne@69 347 * NumberRangeFormatter will be used.
jpayne@69 348 *
jpayne@69 349 * @param formatterSecond
jpayne@69 350 * The formatter to use for the second number in the range.
jpayne@69 351 * @return The fluent chain.
jpayne@69 352 * @stable ICU 63
jpayne@69 353 */
jpayne@69 354 Derived numberFormatterSecond(const UnlocalizedNumberFormatter &formatterSecond) const &;
jpayne@69 355
jpayne@69 356 /**
jpayne@69 357 * Overload of numberFormatterSecond() for use on an rvalue reference.
jpayne@69 358 *
jpayne@69 359 * @param formatterSecond
jpayne@69 360 * The formatter to use for the second number in the range.
jpayne@69 361 * @return The fluent chain.
jpayne@69 362 * @see #numberFormatterSecond
jpayne@69 363 * @stable ICU 63
jpayne@69 364 */
jpayne@69 365 Derived numberFormatterSecond(const UnlocalizedNumberFormatter &formatterSecond) &&;
jpayne@69 366
jpayne@69 367 /**
jpayne@69 368 * Overload of numberFormatterSecond() for use on an rvalue reference.
jpayne@69 369 *
jpayne@69 370 * @param formatterSecond
jpayne@69 371 * The formatter to use for the second number in the range.
jpayne@69 372 * @return The fluent chain.
jpayne@69 373 * @see #numberFormatterSecond
jpayne@69 374 * @stable ICU 63
jpayne@69 375 */
jpayne@69 376 Derived numberFormatterSecond(UnlocalizedNumberFormatter &&formatterSecond) const &;
jpayne@69 377
jpayne@69 378 /**
jpayne@69 379 * Overload of numberFormatterSecond() for use on an rvalue reference.
jpayne@69 380 *
jpayne@69 381 * @param formatterSecond
jpayne@69 382 * The formatter to use for the second number in the range.
jpayne@69 383 * @return The fluent chain.
jpayne@69 384 * @see #numberFormatterSecond
jpayne@69 385 * @stable ICU 63
jpayne@69 386 */
jpayne@69 387 Derived numberFormatterSecond(UnlocalizedNumberFormatter &&formatterSecond) &&;
jpayne@69 388
jpayne@69 389 /**
jpayne@69 390 * Sets the aggressiveness of "collapsing" fields across the range separator. Possible values:
jpayne@69 391 * <p>
jpayne@69 392 * <ul>
jpayne@69 393 * <li>ALL: "3-5K miles"</li>
jpayne@69 394 * <li>UNIT: "3K - 5K miles"</li>
jpayne@69 395 * <li>NONE: "3K miles - 5K miles"</li>
jpayne@69 396 * <li>AUTO: usually UNIT or NONE, depending on the locale and formatter settings</li>
jpayne@69 397 * </ul>
jpayne@69 398 * <p>
jpayne@69 399 * The default value is AUTO.
jpayne@69 400 *
jpayne@69 401 * @param collapse
jpayne@69 402 * The collapsing strategy to use for this range.
jpayne@69 403 * @return The fluent chain.
jpayne@69 404 * @stable ICU 63
jpayne@69 405 */
jpayne@69 406 Derived collapse(UNumberRangeCollapse collapse) const &;
jpayne@69 407
jpayne@69 408 /**
jpayne@69 409 * Overload of collapse() for use on an rvalue reference.
jpayne@69 410 *
jpayne@69 411 * @param collapse
jpayne@69 412 * The collapsing strategy to use for this range.
jpayne@69 413 * @return The fluent chain.
jpayne@69 414 * @see #collapse
jpayne@69 415 * @stable ICU 63
jpayne@69 416 */
jpayne@69 417 Derived collapse(UNumberRangeCollapse collapse) &&;
jpayne@69 418
jpayne@69 419 /**
jpayne@69 420 * Sets the behavior when the two sides of the range are the same. This could happen if the same two numbers are
jpayne@69 421 * passed to the formatRange function, or if different numbers are passed to the function but they become the same
jpayne@69 422 * after rounding rules are applied. Possible values:
jpayne@69 423 * <p>
jpayne@69 424 * <ul>
jpayne@69 425 * <li>SINGLE_VALUE: "5 miles"</li>
jpayne@69 426 * <li>APPROXIMATELY_OR_SINGLE_VALUE: "~5 miles" or "5 miles", depending on whether the number was the same before
jpayne@69 427 * rounding was applied</li>
jpayne@69 428 * <li>APPROXIMATELY: "~5 miles"</li>
jpayne@69 429 * <li>RANGE: "5-5 miles" (with collapse=UNIT)</li>
jpayne@69 430 * </ul>
jpayne@69 431 * <p>
jpayne@69 432 * The default value is APPROXIMATELY.
jpayne@69 433 *
jpayne@69 434 * @param identityFallback
jpayne@69 435 * The strategy to use when formatting two numbers that end up being the same.
jpayne@69 436 * @return The fluent chain.
jpayne@69 437 * @stable ICU 63
jpayne@69 438 */
jpayne@69 439 Derived identityFallback(UNumberRangeIdentityFallback identityFallback) const &;
jpayne@69 440
jpayne@69 441 /**
jpayne@69 442 * Overload of identityFallback() for use on an rvalue reference.
jpayne@69 443 *
jpayne@69 444 * @param identityFallback
jpayne@69 445 * The strategy to use when formatting two numbers that end up being the same.
jpayne@69 446 * @return The fluent chain.
jpayne@69 447 * @see #identityFallback
jpayne@69 448 * @stable ICU 63
jpayne@69 449 */
jpayne@69 450 Derived identityFallback(UNumberRangeIdentityFallback identityFallback) &&;
jpayne@69 451
jpayne@69 452 /**
jpayne@69 453 * Returns the current (Un)LocalizedNumberRangeFormatter as a LocalPointer
jpayne@69 454 * wrapping a heap-allocated copy of the current object.
jpayne@69 455 *
jpayne@69 456 * This is equivalent to new-ing the move constructor with a value object
jpayne@69 457 * as the argument.
jpayne@69 458 *
jpayne@69 459 * @return A wrapped (Un)LocalizedNumberRangeFormatter pointer, or a wrapped
jpayne@69 460 * nullptr on failure.
jpayne@69 461 * @stable ICU 64
jpayne@69 462 */
jpayne@69 463 LocalPointer<Derived> clone() const &;
jpayne@69 464
jpayne@69 465 /**
jpayne@69 466 * Overload of clone for use on an rvalue reference.
jpayne@69 467 *
jpayne@69 468 * @return A wrapped (Un)LocalizedNumberRangeFormatter pointer, or a wrapped
jpayne@69 469 * nullptr on failure.
jpayne@69 470 * @stable ICU 64
jpayne@69 471 */
jpayne@69 472 LocalPointer<Derived> clone() &&;
jpayne@69 473
jpayne@69 474 /**
jpayne@69 475 * Sets the UErrorCode if an error occurred in the fluent chain.
jpayne@69 476 * Preserves older error codes in the outErrorCode.
jpayne@69 477 * @return TRUE if U_FAILURE(outErrorCode)
jpayne@69 478 * @stable ICU 63
jpayne@69 479 */
jpayne@69 480 UBool copyErrorTo(UErrorCode &outErrorCode) const {
jpayne@69 481 if (U_FAILURE(outErrorCode)) {
jpayne@69 482 // Do not overwrite the older error code
jpayne@69 483 return TRUE;
jpayne@69 484 }
jpayne@69 485 fMacros.copyErrorTo(outErrorCode);
jpayne@69 486 return U_FAILURE(outErrorCode);
jpayne@69 487 }
jpayne@69 488
jpayne@69 489 // NOTE: Uses default copy and move constructors.
jpayne@69 490
jpayne@69 491 private:
jpayne@69 492 impl::RangeMacroProps fMacros;
jpayne@69 493
jpayne@69 494 // Don't construct me directly! Use (Un)LocalizedNumberFormatter.
jpayne@69 495 NumberRangeFormatterSettings() = default;
jpayne@69 496
jpayne@69 497 friend class LocalizedNumberRangeFormatter;
jpayne@69 498 friend class UnlocalizedNumberRangeFormatter;
jpayne@69 499 };
jpayne@69 500
jpayne@69 501 /**
jpayne@69 502 * A NumberRangeFormatter that does not yet have a locale. In order to format, a locale must be specified.
jpayne@69 503 *
jpayne@69 504 * Instances of this class are immutable and thread-safe.
jpayne@69 505 *
jpayne@69 506 * @see NumberRangeFormatter
jpayne@69 507 * @stable ICU 63
jpayne@69 508 */
jpayne@69 509 class U_I18N_API UnlocalizedNumberRangeFormatter
jpayne@69 510 : public NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>, public UMemory {
jpayne@69 511
jpayne@69 512 public:
jpayne@69 513 /**
jpayne@69 514 * Associate the given locale with the number range formatter. The locale is used for picking the
jpayne@69 515 * appropriate symbols, formats, and other data for number display.
jpayne@69 516 *
jpayne@69 517 * @param locale
jpayne@69 518 * The locale to use when loading data for number formatting.
jpayne@69 519 * @return The fluent chain.
jpayne@69 520 * @stable ICU 63
jpayne@69 521 */
jpayne@69 522 LocalizedNumberRangeFormatter locale(const icu::Locale &locale) const &;
jpayne@69 523
jpayne@69 524 /**
jpayne@69 525 * Overload of locale() for use on an rvalue reference.
jpayne@69 526 *
jpayne@69 527 * @param locale
jpayne@69 528 * The locale to use when loading data for number formatting.
jpayne@69 529 * @return The fluent chain.
jpayne@69 530 * @see #locale
jpayne@69 531 * @stable ICU 63
jpayne@69 532 */
jpayne@69 533 LocalizedNumberRangeFormatter locale(const icu::Locale &locale) &&;
jpayne@69 534
jpayne@69 535 /**
jpayne@69 536 * Default constructor: puts the formatter into a valid but undefined state.
jpayne@69 537 *
jpayne@69 538 * @stable ICU 63
jpayne@69 539 */
jpayne@69 540 UnlocalizedNumberRangeFormatter() = default;
jpayne@69 541
jpayne@69 542 /**
jpayne@69 543 * Returns a copy of this UnlocalizedNumberRangeFormatter.
jpayne@69 544 * @stable ICU 63
jpayne@69 545 */
jpayne@69 546 UnlocalizedNumberRangeFormatter(const UnlocalizedNumberRangeFormatter &other);
jpayne@69 547
jpayne@69 548 /**
jpayne@69 549 * Move constructor:
jpayne@69 550 * The source UnlocalizedNumberRangeFormatter will be left in a valid but undefined state.
jpayne@69 551 * @stable ICU 63
jpayne@69 552 */
jpayne@69 553 UnlocalizedNumberRangeFormatter(UnlocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
jpayne@69 554
jpayne@69 555 /**
jpayne@69 556 * Copy assignment operator.
jpayne@69 557 * @stable ICU 63
jpayne@69 558 */
jpayne@69 559 UnlocalizedNumberRangeFormatter& operator=(const UnlocalizedNumberRangeFormatter& other);
jpayne@69 560
jpayne@69 561 /**
jpayne@69 562 * Move assignment operator:
jpayne@69 563 * The source UnlocalizedNumberRangeFormatter will be left in a valid but undefined state.
jpayne@69 564 * @stable ICU 63
jpayne@69 565 */
jpayne@69 566 UnlocalizedNumberRangeFormatter& operator=(UnlocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
jpayne@69 567
jpayne@69 568 private:
jpayne@69 569 explicit UnlocalizedNumberRangeFormatter(
jpayne@69 570 const NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>& other);
jpayne@69 571
jpayne@69 572 explicit UnlocalizedNumberRangeFormatter(
jpayne@69 573 NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>&& src) U_NOEXCEPT;
jpayne@69 574
jpayne@69 575 // To give the fluent setters access to this class's constructor:
jpayne@69 576 friend class NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>;
jpayne@69 577
jpayne@69 578 // To give NumberRangeFormatter::with() access to this class's constructor:
jpayne@69 579 friend class NumberRangeFormatter;
jpayne@69 580 };
jpayne@69 581
jpayne@69 582 /**
jpayne@69 583 * A NumberRangeFormatter that has a locale associated with it; this means .formatRange() methods are available.
jpayne@69 584 *
jpayne@69 585 * Instances of this class are immutable and thread-safe.
jpayne@69 586 *
jpayne@69 587 * @see NumberFormatter
jpayne@69 588 * @stable ICU 63
jpayne@69 589 */
jpayne@69 590 class U_I18N_API LocalizedNumberRangeFormatter
jpayne@69 591 : public NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>, public UMemory {
jpayne@69 592 public:
jpayne@69 593 /**
jpayne@69 594 * Format the given Formattables to a string using the settings specified in the NumberRangeFormatter fluent setting
jpayne@69 595 * chain.
jpayne@69 596 *
jpayne@69 597 * @param first
jpayne@69 598 * The first number in the range, usually to the left in LTR locales.
jpayne@69 599 * @param second
jpayne@69 600 * The second number in the range, usually to the right in LTR locales.
jpayne@69 601 * @param status
jpayne@69 602 * Set if an error occurs while formatting.
jpayne@69 603 * @return A FormattedNumberRange object; call .toString() to get the string.
jpayne@69 604 * @stable ICU 63
jpayne@69 605 */
jpayne@69 606 FormattedNumberRange formatFormattableRange(
jpayne@69 607 const Formattable& first, const Formattable& second, UErrorCode& status) const;
jpayne@69 608
jpayne@69 609 /**
jpayne@69 610 * Default constructor: puts the formatter into a valid but undefined state.
jpayne@69 611 *
jpayne@69 612 * @stable ICU 63
jpayne@69 613 */
jpayne@69 614 LocalizedNumberRangeFormatter() = default;
jpayne@69 615
jpayne@69 616 /**
jpayne@69 617 * Returns a copy of this LocalizedNumberRangeFormatter.
jpayne@69 618 * @stable ICU 63
jpayne@69 619 */
jpayne@69 620 LocalizedNumberRangeFormatter(const LocalizedNumberRangeFormatter &other);
jpayne@69 621
jpayne@69 622 /**
jpayne@69 623 * Move constructor:
jpayne@69 624 * The source LocalizedNumberRangeFormatter will be left in a valid but undefined state.
jpayne@69 625 * @stable ICU 63
jpayne@69 626 */
jpayne@69 627 LocalizedNumberRangeFormatter(LocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
jpayne@69 628
jpayne@69 629 /**
jpayne@69 630 * Copy assignment operator.
jpayne@69 631 * @stable ICU 63
jpayne@69 632 */
jpayne@69 633 LocalizedNumberRangeFormatter& operator=(const LocalizedNumberRangeFormatter& other);
jpayne@69 634
jpayne@69 635 /**
jpayne@69 636 * Move assignment operator:
jpayne@69 637 * The source LocalizedNumberRangeFormatter will be left in a valid but undefined state.
jpayne@69 638 * @stable ICU 63
jpayne@69 639 */
jpayne@69 640 LocalizedNumberRangeFormatter& operator=(LocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
jpayne@69 641
jpayne@69 642 #ifndef U_HIDE_INTERNAL_API
jpayne@69 643
jpayne@69 644 /**
jpayne@69 645 * @param results
jpayne@69 646 * The results object. This method will mutate it to save the results.
jpayne@69 647 * @param equalBeforeRounding
jpayne@69 648 * Whether the number was equal before copying it into a DecimalQuantity.
jpayne@69 649 * Used for determining the identity fallback behavior.
jpayne@69 650 * @param status
jpayne@69 651 * Set if an error occurs while formatting.
jpayne@69 652 * @internal
jpayne@69 653 */
jpayne@69 654 void formatImpl(impl::UFormattedNumberRangeData& results, bool equalBeforeRounding,
jpayne@69 655 UErrorCode& status) const;
jpayne@69 656
jpayne@69 657 #endif /* U_HIDE_INTERNAL_API */
jpayne@69 658
jpayne@69 659 /**
jpayne@69 660 * Destruct this LocalizedNumberRangeFormatter, cleaning up any memory it might own.
jpayne@69 661 * @stable ICU 63
jpayne@69 662 */
jpayne@69 663 ~LocalizedNumberRangeFormatter();
jpayne@69 664
jpayne@69 665 private:
jpayne@69 666 std::atomic<impl::NumberRangeFormatterImpl*> fAtomicFormatter = {};
jpayne@69 667
jpayne@69 668 const impl::NumberRangeFormatterImpl* getFormatter(UErrorCode& stauts) const;
jpayne@69 669
jpayne@69 670 explicit LocalizedNumberRangeFormatter(
jpayne@69 671 const NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>& other);
jpayne@69 672
jpayne@69 673 explicit LocalizedNumberRangeFormatter(
jpayne@69 674 NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>&& src) U_NOEXCEPT;
jpayne@69 675
jpayne@69 676 LocalizedNumberRangeFormatter(const impl::RangeMacroProps &macros, const Locale &locale);
jpayne@69 677
jpayne@69 678 LocalizedNumberRangeFormatter(impl::RangeMacroProps &&macros, const Locale &locale);
jpayne@69 679
jpayne@69 680 void clear();
jpayne@69 681
jpayne@69 682 // To give the fluent setters access to this class's constructor:
jpayne@69 683 friend class NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>;
jpayne@69 684 friend class NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>;
jpayne@69 685
jpayne@69 686 // To give UnlocalizedNumberRangeFormatter::locale() access to this class's constructor:
jpayne@69 687 friend class UnlocalizedNumberRangeFormatter;
jpayne@69 688 };
jpayne@69 689
jpayne@69 690 /**
jpayne@69 691 * The result of a number range formatting operation. This class allows the result to be exported in several data types,
jpayne@69 692 * including a UnicodeString and a FieldPositionIterator.
jpayne@69 693 *
jpayne@69 694 * Instances of this class are immutable and thread-safe.
jpayne@69 695 *
jpayne@69 696 * @stable ICU 63
jpayne@69 697 */
jpayne@69 698 class U_I18N_API FormattedNumberRange : public UMemory, public FormattedValue {
jpayne@69 699 public:
jpayne@69 700 // Copybrief: this method is older than the parent method
jpayne@69 701 /**
jpayne@69 702 * @copybrief FormattedValue::toString()
jpayne@69 703 *
jpayne@69 704 * For more information, see FormattedValue::toString()
jpayne@69 705 *
jpayne@69 706 * @stable ICU 63
jpayne@69 707 */
jpayne@69 708 UnicodeString toString(UErrorCode& status) const U_OVERRIDE;
jpayne@69 709
jpayne@69 710 // Copydoc: this method is new in ICU 64
jpayne@69 711 /** @copydoc FormattedValue::toTempString() */
jpayne@69 712 UnicodeString toTempString(UErrorCode& status) const U_OVERRIDE;
jpayne@69 713
jpayne@69 714 // Copybrief: this method is older than the parent method
jpayne@69 715 /**
jpayne@69 716 * @copybrief FormattedValue::appendTo()
jpayne@69 717 *
jpayne@69 718 * For more information, see FormattedValue::appendTo()
jpayne@69 719 *
jpayne@69 720 * @stable ICU 63
jpayne@69 721 */
jpayne@69 722 Appendable &appendTo(Appendable &appendable, UErrorCode& status) const U_OVERRIDE;
jpayne@69 723
jpayne@69 724 // Copydoc: this method is new in ICU 64
jpayne@69 725 /** @copydoc FormattedValue::nextPosition() */
jpayne@69 726 UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const U_OVERRIDE;
jpayne@69 727
jpayne@69 728 #ifndef U_HIDE_DRAFT_API
jpayne@69 729 /**
jpayne@69 730 * Export the first formatted number as a decimal number. This endpoint
jpayne@69 731 * is useful for obtaining the exact number being printed after scaling
jpayne@69 732 * and rounding have been applied by the number range formatting pipeline.
jpayne@69 733 *
jpayne@69 734 * The syntax of the unformatted number is a "numeric string"
jpayne@69 735 * as defined in the Decimal Arithmetic Specification, available at
jpayne@69 736 * http://speleotrove.com/decimal
jpayne@69 737 *
jpayne@69 738 * @return A decimal representation of the first formatted number.
jpayne@69 739 * @draft ICU 63
jpayne@69 740 * @see NumberRangeFormatter
jpayne@69 741 * @see #getSecondDecimal
jpayne@69 742 */
jpayne@69 743 UnicodeString getFirstDecimal(UErrorCode& status) const;
jpayne@69 744
jpayne@69 745 /**
jpayne@69 746 * Export the second formatted number as a decimal number. This endpoint
jpayne@69 747 * is useful for obtaining the exact number being printed after scaling
jpayne@69 748 * and rounding have been applied by the number range formatting pipeline.
jpayne@69 749 *
jpayne@69 750 * The syntax of the unformatted number is a "numeric string"
jpayne@69 751 * as defined in the Decimal Arithmetic Specification, available at
jpayne@69 752 * http://speleotrove.com/decimal
jpayne@69 753 *
jpayne@69 754 * @return A decimal representation of the second formatted number.
jpayne@69 755 * @draft ICU 63
jpayne@69 756 * @see NumberRangeFormatter
jpayne@69 757 * @see #getFirstDecimal
jpayne@69 758 */
jpayne@69 759 UnicodeString getSecondDecimal(UErrorCode& status) const;
jpayne@69 760 #endif // U_HIDE_DRAFT_API
jpayne@69 761
jpayne@69 762 /**
jpayne@69 763 * Returns whether the pair of numbers was successfully formatted as a range or whether an identity fallback was
jpayne@69 764 * used. For example, if the first and second number were the same either before or after rounding occurred, an
jpayne@69 765 * identity fallback was used.
jpayne@69 766 *
jpayne@69 767 * @return An indication the resulting identity situation in the formatted number range.
jpayne@69 768 * @stable ICU 63
jpayne@69 769 * @see UNumberRangeIdentityFallback
jpayne@69 770 */
jpayne@69 771 UNumberRangeIdentityResult getIdentityResult(UErrorCode& status) const;
jpayne@69 772
jpayne@69 773 /**
jpayne@69 774 * Copying not supported; use move constructor instead.
jpayne@69 775 */
jpayne@69 776 FormattedNumberRange(const FormattedNumberRange&) = delete;
jpayne@69 777
jpayne@69 778 /**
jpayne@69 779 * Copying not supported; use move assignment instead.
jpayne@69 780 */
jpayne@69 781 FormattedNumberRange& operator=(const FormattedNumberRange&) = delete;
jpayne@69 782
jpayne@69 783 /**
jpayne@69 784 * Move constructor:
jpayne@69 785 * Leaves the source FormattedNumberRange in an undefined state.
jpayne@69 786 * @stable ICU 63
jpayne@69 787 */
jpayne@69 788 FormattedNumberRange(FormattedNumberRange&& src) U_NOEXCEPT;
jpayne@69 789
jpayne@69 790 /**
jpayne@69 791 * Move assignment:
jpayne@69 792 * Leaves the source FormattedNumberRange in an undefined state.
jpayne@69 793 * @stable ICU 63
jpayne@69 794 */
jpayne@69 795 FormattedNumberRange& operator=(FormattedNumberRange&& src) U_NOEXCEPT;
jpayne@69 796
jpayne@69 797 /**
jpayne@69 798 * Destruct an instance of FormattedNumberRange, cleaning up any memory it might own.
jpayne@69 799 * @stable ICU 63
jpayne@69 800 */
jpayne@69 801 ~FormattedNumberRange();
jpayne@69 802
jpayne@69 803 private:
jpayne@69 804 // Can't use LocalPointer because UFormattedNumberRangeData is forward-declared
jpayne@69 805 const impl::UFormattedNumberRangeData *fData;
jpayne@69 806
jpayne@69 807 // Error code for the terminal methods
jpayne@69 808 UErrorCode fErrorCode;
jpayne@69 809
jpayne@69 810 /**
jpayne@69 811 * Internal constructor from data type. Adopts the data pointer.
jpayne@69 812 */
jpayne@69 813 explicit FormattedNumberRange(impl::UFormattedNumberRangeData *results)
jpayne@69 814 : fData(results), fErrorCode(U_ZERO_ERROR) {}
jpayne@69 815
jpayne@69 816 explicit FormattedNumberRange(UErrorCode errorCode)
jpayne@69 817 : fData(nullptr), fErrorCode(errorCode) {}
jpayne@69 818
jpayne@69 819 void getAllFieldPositionsImpl(FieldPositionIteratorHandler& fpih, UErrorCode& status) const;
jpayne@69 820
jpayne@69 821 // To give LocalizedNumberRangeFormatter format methods access to this class's constructor:
jpayne@69 822 friend class LocalizedNumberRangeFormatter;
jpayne@69 823 };
jpayne@69 824
jpayne@69 825 /**
jpayne@69 826 * See the main description in numberrangeformatter.h for documentation and examples.
jpayne@69 827 *
jpayne@69 828 * @stable ICU 63
jpayne@69 829 */
jpayne@69 830 class U_I18N_API NumberRangeFormatter final {
jpayne@69 831 public:
jpayne@69 832 /**
jpayne@69 833 * Call this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is not currently
jpayne@69 834 * known at the call site.
jpayne@69 835 *
jpayne@69 836 * @return An {@link UnlocalizedNumberRangeFormatter}, to be used for chaining.
jpayne@69 837 * @stable ICU 63
jpayne@69 838 */
jpayne@69 839 static UnlocalizedNumberRangeFormatter with();
jpayne@69 840
jpayne@69 841 /**
jpayne@69 842 * Call this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is known at the call
jpayne@69 843 * site.
jpayne@69 844 *
jpayne@69 845 * @param locale
jpayne@69 846 * The locale from which to load formats and symbols for number range formatting.
jpayne@69 847 * @return A {@link LocalizedNumberRangeFormatter}, to be used for chaining.
jpayne@69 848 * @stable ICU 63
jpayne@69 849 */
jpayne@69 850 static LocalizedNumberRangeFormatter withLocale(const Locale &locale);
jpayne@69 851
jpayne@69 852 /**
jpayne@69 853 * Use factory methods instead of the constructor to create a NumberFormatter.
jpayne@69 854 */
jpayne@69 855 NumberRangeFormatter() = delete;
jpayne@69 856 };
jpayne@69 857
jpayne@69 858 } // namespace number
jpayne@69 859 U_NAMESPACE_END
jpayne@69 860
jpayne@69 861 #endif /* #if !UCONFIG_NO_FORMATTING */
jpayne@69 862
jpayne@69 863 #endif /* U_SHOW_CPLUSPLUS_API */
jpayne@69 864
jpayne@69 865 #endif // __NUMBERRANGEFORMATTER_H__
jpayne@69 866