ICU 64.2 64.2

numberrangeformatter.h
Go to the documentation of this file.
1 // © 2018 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3
4 #if !UCONFIG_NO_FORMATTING
5 #ifndef __NUMBERRANGEFORMATTER_H__
6 #define __NUMBERRANGEFORMATTER_H__
7
8 #include <atomic>
9 #include "unicode/appendable.h"
10 #include "unicode/fieldpos.h"
11 #include "unicode/formattedvalue.h"
12 #include "unicode/fpositer.h"
13 #include "unicode/numberformatter.h"
14
15 #ifndef U_HIDE_DRAFT_API
16
49 typedef enum UNumberRangeCollapse {
58 UNUM_RANGE_COLLAPSE_AUTO,
59
65 UNUM_RANGE_COLLAPSE_NONE,
66
73 UNUM_RANGE_COLLAPSE_UNIT,
74
81 UNUM_RANGE_COLLAPSE_ALL
82 } UNumberRangeCollapse;
83
91 typedef enum UNumberRangeIdentityFallback {
97 UNUM_IDENTITY_FALLBACK_SINGLE_VALUE,
98
105 UNUM_IDENTITY_FALLBACK_APPROXIMATELY_OR_SINGLE_VALUE,
106
113 UNUM_IDENTITY_FALLBACK_APPROXIMATELY,
114
121 UNUM_IDENTITY_FALLBACK_RANGE
122 } UNumberRangeIdentityFallback;
123
131 typedef enum UNumberRangeIdentityResult {
138 UNUM_IDENTITY_RESULT_EQUAL_BEFORE_ROUNDING,
139
146 UNUM_IDENTITY_RESULT_EQUAL_AFTER_ROUNDING,
147
154 UNUM_IDENTITY_RESULT_NOT_EQUAL,
155
156 #ifndef U_HIDE_INTERNAL_API
157
161 UNUM_IDENTITY_RESULT_COUNT
162 #endif
163
164 } UNumberRangeIdentityResult;
165
166 U_NAMESPACE_BEGIN
167
168 namespace number { // icu::number
169
170 // Forward declarations:
171 class UnlocalizedNumberRangeFormatter;
172 class LocalizedNumberRangeFormatter;
173 class FormattedNumberRange;
174
175 namespace impl {
176
177 // Forward declarations:
178 struct RangeMacroProps;
179 class DecimalQuantity;
180 class UFormattedNumberRangeData;
181 class NumberRangeFormatterImpl;
182
183 } // namespace impl
184
190 #if U_PLATFORM == U_PF_WINDOWS && !defined(U_IN_DOXYGEN)
191 } // namespace icu::number
192 U_NAMESPACE_END
193
194 template struct U_I18N_API std::atomic< U_NAMESPACE_QUALIFIER number::impl::NumberRangeFormatterImpl*>;
195
196 U_NAMESPACE_BEGIN
197 namespace number { // icu::number
198 #endif
199
201 // Other helper classes would go here, but there are none.
202
203 namespace impl { // icu::number::impl
204
205 // Do not enclose entire MacroProps with #ifndef U_HIDE_INTERNAL_API, needed for a protected field
207 struct U_I18N_API RangeMacroProps : public UMemory {
209 UnlocalizedNumberFormatter formatter1; // = NumberFormatter::with();
210
212 UnlocalizedNumberFormatter formatter2; // = NumberFormatter::with();
213
215 bool singleFormatter = true;
216
218 UNumberRangeCollapse collapse = UNUM_RANGE_COLLAPSE_AUTO;
219
221 UNumberRangeIdentityFallback identityFallback = UNUM_IDENTITY_FALLBACK_APPROXIMATELY;
222
224 Locale locale;
225
226 // NOTE: Uses default copy and move constructors.
227
232 bool copyErrorTo(UErrorCode &status) const {
233 return formatter1.copyErrorTo(status) || formatter2.copyErrorTo(status);
234 }
235 };
236
237 } // namespace impl
238
244 template<typename Derived>
245 class U_I18N_API NumberRangeFormatterSettings {
246 public:
259 Derived numberFormatterBoth(const UnlocalizedNumberFormatter &formatter) const &;
260
270 Derived numberFormatterBoth(const UnlocalizedNumberFormatter &formatter) &&;
271
281 Derived numberFormatterBoth(UnlocalizedNumberFormatter &&formatter) const &;
282
292 Derived numberFormatterBoth(UnlocalizedNumberFormatter &&formatter) &&;
293
305 Derived numberFormatterFirst(const UnlocalizedNumberFormatter &formatterFirst) const &;
306
316 Derived numberFormatterFirst(const UnlocalizedNumberFormatter &formatterFirst) &&;
317
327 Derived numberFormatterFirst(UnlocalizedNumberFormatter &&formatterFirst) const &;
328
338 Derived numberFormatterFirst(UnlocalizedNumberFormatter &&formatterFirst) &&;
339
351 Derived numberFormatterSecond(const UnlocalizedNumberFormatter &formatterSecond) const &;
352
362 Derived numberFormatterSecond(const UnlocalizedNumberFormatter &formatterSecond) &&;
363
373 Derived numberFormatterSecond(UnlocalizedNumberFormatter &&formatterSecond) const &;
374
384 Derived numberFormatterSecond(UnlocalizedNumberFormatter &&formatterSecond) &&;
385
403 Derived collapse(UNumberRangeCollapse collapse) const &;
404
414 Derived collapse(UNumberRangeCollapse collapse) &&;
415
436 Derived identityFallback(UNumberRangeIdentityFallback identityFallback) const &;
437
447 Derived identityFallback(UNumberRangeIdentityFallback identityFallback) &&;
448
460 LocalPointer<Derived> clone() const &;
461
469 LocalPointer<Derived> clone() &&;
470
477 UBool copyErrorTo(UErrorCode &outErrorCode) const {
478 if (U_FAILURE(outErrorCode)) {
479 // Do not overwrite the older error code
480 return TRUE;
481 }
482 fMacros.copyErrorTo(outErrorCode);
483 return U_FAILURE(outErrorCode);
484 }
485
486 // NOTE: Uses default copy and move constructors.
487
488 private:
489 impl::RangeMacroProps fMacros;
490
491 // Don't construct me directly! Use (Un)LocalizedNumberFormatter.
492 NumberRangeFormatterSettings() = default;
493
494 friend class LocalizedNumberRangeFormatter;
495 friend class UnlocalizedNumberRangeFormatter;
496 };
497
506 class U_I18N_API UnlocalizedNumberRangeFormatter
507 : public NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>, public UMemory {
508
509 public:
519 LocalizedNumberRangeFormatter locale(const icu::Locale &locale) const &;
520
530 LocalizedNumberRangeFormatter locale(const icu::Locale &locale) &&;
531
537 UnlocalizedNumberRangeFormatter() = default;
538
543 UnlocalizedNumberRangeFormatter(const UnlocalizedNumberRangeFormatter &other);
544
550 UnlocalizedNumberRangeFormatter(UnlocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
551
556 UnlocalizedNumberRangeFormatter& operator=(const UnlocalizedNumberRangeFormatter& other);
557
563 UnlocalizedNumberRangeFormatter& operator=(UnlocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
564
565 private:
566 explicit UnlocalizedNumberRangeFormatter(
567 const NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>& other);
568
569 explicit UnlocalizedNumberRangeFormatter(
570 NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>&& src) U_NOEXCEPT;
571
572 // To give the fluent setters access to this class's constructor:
573 friend class NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>;
574
575 // To give NumberRangeFormatter::with() access to this class's constructor:
576 friend class NumberRangeFormatter;
577 };
578
587 class U_I18N_API LocalizedNumberRangeFormatter
588 : public NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>, public UMemory {
589 public:
603 FormattedNumberRange formatFormattableRange(
604 const Formattable& first, const Formattable& second, UErrorCode& status) const;
605
611 LocalizedNumberRangeFormatter() = default;
612
617 LocalizedNumberRangeFormatter(const LocalizedNumberRangeFormatter &other);
618
624 LocalizedNumberRangeFormatter(LocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
625
630 LocalizedNumberRangeFormatter& operator=(const LocalizedNumberRangeFormatter& other);
631
637 LocalizedNumberRangeFormatter& operator=(LocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
638
639 #ifndef U_HIDE_INTERNAL_API
640
651 void formatImpl(impl::UFormattedNumberRangeData& results, bool equalBeforeRounding,
652 UErrorCode& status) const;
653
654 #endif
655
660 ~LocalizedNumberRangeFormatter();
661
662 private:
663 std::atomic<impl::NumberRangeFormatterImpl*> fAtomicFormatter = {};
664
665 const impl::NumberRangeFormatterImpl* getFormatter(UErrorCode& stauts) const;
666
667 explicit LocalizedNumberRangeFormatter(
668 const NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>& other);
669
670 explicit LocalizedNumberRangeFormatter(
671 NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>&& src) U_NOEXCEPT;
672
673 LocalizedNumberRangeFormatter(const impl::RangeMacroProps &macros, const Locale &locale);
674
675 LocalizedNumberRangeFormatter(impl::RangeMacroProps &&macros, const Locale &locale);
676
677 void clear();
678
679 // To give the fluent setters access to this class's constructor:
680 friend class NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>;
681 friend class NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>;
682
683 // To give UnlocalizedNumberRangeFormatter::locale() access to this class's constructor:
684 friend class UnlocalizedNumberRangeFormatter;
685 };
686
695 class U_I18N_API FormattedNumberRange : public UMemory, public FormattedValue {
696 public:
697 // Copybrief: this method is older than the parent method
705 UnicodeString toString(UErrorCode& status) const U_OVERRIDE;
706
707 // Copydoc: this method is new in ICU 64
709 UnicodeString toTempString(UErrorCode& status) const U_OVERRIDE;
710
711 // Copybrief: this method is older than the parent method
719 Appendable &appendTo(Appendable &appendable, UErrorCode& status) const U_OVERRIDE;
720
721 // Copydoc: this method is new in ICU 64
723 UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const U_OVERRIDE;
724
754 UBool nextFieldPosition(FieldPosition& fieldPosition, UErrorCode& status) const;
755
769 void getAllFieldPositions(FieldPositionIterator &iterator, UErrorCode &status) const;
770
785 UnicodeString getFirstDecimal(UErrorCode& status) const;
786
801 UnicodeString getSecondDecimal(UErrorCode& status) const;
802
812 UNumberRangeIdentityResult getIdentityResult(UErrorCode& status) const;
813
817 FormattedNumberRange(const FormattedNumberRange&) = delete;
818
822 FormattedNumberRange& operator=(const FormattedNumberRange&) = delete;
823
829 FormattedNumberRange(FormattedNumberRange&& src) U_NOEXCEPT;
830
836 FormattedNumberRange& operator=(FormattedNumberRange&& src) U_NOEXCEPT;
837
842 ~FormattedNumberRange();
843
844 private:
845 // Can't use LocalPointer because UFormattedNumberRangeData is forward-declared
846 const impl::UFormattedNumberRangeData *fData;
847
848 // Error code for the terminal methods
849 UErrorCode fErrorCode;
850
855 explicit FormattedNumberRange(impl::UFormattedNumberRangeData *results)
856 : fData(results), fErrorCode(U_ZERO_ERROR) {}
857
858 explicit FormattedNumberRange(UErrorCode errorCode)
859 : fData(nullptr), fErrorCode(errorCode) {}
860
861 void getAllFieldPositionsImpl(FieldPositionIteratorHandler& fpih, UErrorCode& status) const;
862
863 // To give LocalizedNumberRangeFormatter format methods access to this class's constructor:
864 friend class LocalizedNumberRangeFormatter;
865 };
866
872 class U_I18N_API NumberRangeFormatter final {
873 public:
881 static UnlocalizedNumberRangeFormatter with();
882
892 static LocalizedNumberRangeFormatter withLocale(const Locale &locale);
893
897 NumberRangeFormatter() = delete;
898 };
899
900 } // namespace number
901 U_NAMESPACE_END
902
903 #endif // U_HIDE_DRAFT_API
904
905 #endif // __NUMBERRANGEFORMATTER_H__
906
907 #endif /* #if !UCONFIG_NO_FORMATTING */
formattedvalue.h
C++ API: Abstract operations for localized strings.
UNUM_RANGE_COLLAPSE_UNIT
Collapse the unit part of the number, but not the notation, if present.
Definition: numberrangeformatter.h:73
U_OVERRIDE
#define U_OVERRIDE
Defined to the C++11 "override" keyword if available.
Definition: umachine.h:129
U_FAILURE
#define U_FAILURE(x)
Does the error code indicate a failure?
Definition: utypes.h:695
icu::number::FormattedNumberRange
The result of a number range formatting operation.
Definition: numberrangeformatter.h:695
fpositer.h
C++ API: FieldPosition Iterator.
UNUM_IDENTITY_RESULT_EQUAL_BEFORE_ROUNDING
Used to indicate that the two numbers in the range were equal, even before any rounding rules were ap...
Definition: numberrangeformatter.h:138
icu::LocalPointer
"Smart pointer" class, deletes objects via the standard C++ delete operator.
Definition: localpointer.h:191
icu::number::NumberRangeFormatter
See the main description in numberrangeformatter.h for documentation and examples.
Definition: numberrangeformatter.h:872
icu::number::LocalizedNumberRangeFormatter
A NumberRangeFormatter that has a locale associated with it; this means .formatRange() methods are av...
Definition: numberrangeformatter.h:587
UNUM_IDENTITY_FALLBACK_APPROXIMATELY
Show the number using a locale-sensitive approximation pattern.
Definition: numberrangeformatter.h:113
appendable.h
C++ API: Appendable class: Sink for Unicode code points and 16-bit code units (char16_ts).
icu::number::impl::RangeMacroProps::locale
Locale locale
Definition: numberrangeformatter.h:224
UNumberRangeIdentityResult
UNumberRangeIdentityResult
Used in the result class FormattedNumberRange to indicate to the user whether the numbers formatted i...
Definition: numberrangeformatter.h:131
U_ZERO_ERROR
No error, no warning.
Definition: utypes.h:435
UNUM_IDENTITY_RESULT_EQUAL_AFTER_ROUNDING
Used to indicate that the two numbers in the range were equal, but only after rounding rules were app...
Definition: numberrangeformatter.h:146
icu::number::NumberRangeFormatterSettings
An abstract base class for specifying settings related to number formatting.
Definition: numberrangeformatter.h:245
icu::FormattedValue
An abstract formatted value: a string with associated field attributes.
Definition: formattedvalue.h:241
UNUM_IDENTITY_RESULT_NOT_EQUAL
Used to indicate that the two numbers in the range were not equal, even after rounding rules were app...
Definition: numberrangeformatter.h:154
U_I18N_API
#define U_I18N_API
Set to export library symbols from inside the i18n library, and to import them from outside.
Definition: utypes.h:301
fieldpos.h
C++ API: FieldPosition identifies the fields in a formatted output.
icu::number::impl::RangeMacroProps
Definition: numberrangeformatter.h:207
U_NAMESPACE_BEGIN
#define U_NAMESPACE_BEGIN
This is used to begin a declaration of a public ICU C++ API.
Definition: uversion.h:137
UNUM_IDENTITY_FALLBACK_APPROXIMATELY_OR_SINGLE_VALUE
Show the number using a locale-sensitive approximation pattern.
Definition: numberrangeformatter.h:105
UNumberRangeCollapse
UNumberRangeCollapse
Defines how to merge fields that are identical across the range sign.
Definition: numberrangeformatter.h:49
icu::FieldPositionIterator
FieldPositionIterator returns the field ids and their start/limit positions generated by a call to Fo...
Definition: fpositer.h:55
UNUM_IDENTITY_FALLBACK_RANGE
Show the number as the range of two equal values.
Definition: numberrangeformatter.h:121
icu::number::NumberRangeFormatterSettings::copyErrorTo
UBool copyErrorTo(UErrorCode &outErrorCode) const
Sets the UErrorCode if an error occurred in the fluent chain.
Definition: numberrangeformatter.h:477
icu::number::NumberFormatterSettings::copyErrorTo
UBool copyErrorTo(UErrorCode &outErrorCode) const
Sets the UErrorCode if an error occurred in the fluent chain.
Definition: numberformatter.h:2111
UNUM_RANGE_COLLAPSE_AUTO
Use locale data and heuristics to determine how much of the string to collapse.
Definition: numberrangeformatter.h:58
icu::number::UnlocalizedNumberRangeFormatter
A NumberRangeFormatter that does not yet have a locale.
Definition: numberrangeformatter.h:506
UNUM_RANGE_COLLAPSE_NONE
Do not collapse any part of the number.
Definition: numberrangeformatter.h:65
TRUE
#define TRUE
The TRUE value of a UBool.
Definition: umachine.h:229
UNUM_IDENTITY_FALLBACK_SINGLE_VALUE
Show the number as a single value rather than a range.
Definition: numberrangeformatter.h:97
icu::ConstrainedFieldPosition
Represents a span of a string containing a given field.
Definition: formattedvalue.h:40
U_NOEXCEPT
#define U_NOEXCEPT
"noexcept" if supported, otherwise empty.
Definition: platform.h:503
UNUM_IDENTITY_RESULT_COUNT
The number of entries in this enum.
Definition: numberrangeformatter.h:161
icu::number::UnlocalizedNumberFormatter
A NumberFormatter that does not yet have a locale.
Definition: numberformatter.h:2144
U_NAMESPACE_END
#define U_NAMESPACE_END
This is used to end a declaration of a public ICU C++ API.
Definition: uversion.h:138
icu::number::impl::RangeMacroProps::formatter2
UnlocalizedNumberFormatter formatter2
Definition: numberrangeformatter.h:212
UNumberRangeIdentityFallback
UNumberRangeIdentityFallback
Defines the behavior when the two numbers in the range are identical after rounding.
Definition: numberrangeformatter.h:91
UErrorCode
UErrorCode
Error code to replace exception handling, so that the code is compatible with all C++ compilers,...
Definition: utypes.h:401
icu::FieldPosition
FieldPosition is a simple class used by Format and its subclasses to identify fields in formatted out...
Definition: fieldpos.h:108
icu::number::impl::RangeMacroProps::formatter1
UnlocalizedNumberFormatter formatter1
Definition: numberrangeformatter.h:209
icu::UnicodeString
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition: unistr.h:289
icu::Formattable
Formattable objects can be passed to the Format class or its subclasses for formatting.
Definition: fmtable.h:62
icu::UMemory
UMemory is the common ICU base class.
Definition: uobject.h:112
numberformatter.h
C++ API: Library for localized number formatting introduced in ICU 60.
UNUM_RANGE_COLLAPSE_ALL
Collapse any field that is equal across the range sign.
Definition: numberrangeformatter.h:81
icu::number::impl::RangeMacroProps::copyErrorTo
bool copyErrorTo(UErrorCode &status) const
Check all members for errors.
Definition: numberrangeformatter.h:232
UBool
int8_t UBool
The ICU boolean type.
Definition: umachine.h:225
icu::Appendable
Base class for objects to which Unicode characters and strings can be appended.
Definition: appendable.h:51
icu::Locale
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:192