ICU 63.1 63.1

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/fpositer.h"
12 #include "unicode/numberformatter.h"
13
14 #ifndef U_HIDE_DRAFT_API
15
47 typedef enum UNumberRangeCollapse {
56 UNUM_RANGE_COLLAPSE_AUTO,
57
63 UNUM_RANGE_COLLAPSE_NONE,
64
71 UNUM_RANGE_COLLAPSE_UNIT,
72
79 UNUM_RANGE_COLLAPSE_ALL
80 } UNumberRangeCollapse;
81
89 typedef enum UNumberRangeIdentityFallback {
95 UNUM_IDENTITY_FALLBACK_SINGLE_VALUE,
96
103 UNUM_IDENTITY_FALLBACK_APPROXIMATELY_OR_SINGLE_VALUE,
104
111 UNUM_IDENTITY_FALLBACK_APPROXIMATELY,
112
119 UNUM_IDENTITY_FALLBACK_RANGE
120 } UNumberRangeIdentityFallback;
121
129 typedef enum UNumberRangeIdentityResult {
136 UNUM_IDENTITY_RESULT_EQUAL_BEFORE_ROUNDING,
137
144 UNUM_IDENTITY_RESULT_EQUAL_AFTER_ROUNDING,
145
152 UNUM_IDENTITY_RESULT_NOT_EQUAL,
153
154 #ifndef U_HIDE_INTERNAL_API
155
159 UNUM_IDENTITY_RESULT_COUNT
160 #endif
161
162 } UNumberRangeIdentityResult;
163
164 U_NAMESPACE_BEGIN
165
166 namespace number { // icu::number
167
168 // Forward declarations:
169 class UnlocalizedNumberRangeFormatter;
170 class LocalizedNumberRangeFormatter;
171 class FormattedNumberRange;
172
173 namespace impl {
174
175 // Forward declarations:
176 struct RangeMacroProps;
177 class DecimalQuantity;
178 struct UFormattedNumberRangeData;
179 class NumberRangeFormatterImpl;
180
181 } // namespace impl
182
188 #if U_PF_WINDOWS <= U_PLATFORM && U_PLATFORM < U_PF_CYGWIN && !defined(U_IN_DOXYGEN)
189 template struct U_I18N_API std::atomic<impl::NumberRangeFormatterImpl*>;
190 #endif
191
193 // Other helper classes would go here, but there are none.
194
195 namespace impl { // icu::number::impl
196
197 // Do not enclose entire MacroProps with #ifndef U_HIDE_INTERNAL_API, needed for a protected field
199 struct U_I18N_API RangeMacroProps : public UMemory {
201 UnlocalizedNumberFormatter formatter1; // = NumberFormatter::with();
202
204 UnlocalizedNumberFormatter formatter2; // = NumberFormatter::with();
205
207 bool singleFormatter = true;
208
210 UNumberRangeCollapse collapse = UNUM_RANGE_COLLAPSE_AUTO;
211
213 UNumberRangeIdentityFallback identityFallback = UNUM_IDENTITY_FALLBACK_APPROXIMATELY;
214
216 Locale locale;
217
218 // NOTE: Uses default copy and move constructors.
219
224 bool copyErrorTo(UErrorCode &status) const {
225 return formatter1.copyErrorTo(status) || formatter2.copyErrorTo(status);
226 }
227 };
228
229 } // namespace impl
230
236 template<typename Derived>
237 class U_I18N_API NumberRangeFormatterSettings {
238 public:
251 Derived numberFormatterBoth(const UnlocalizedNumberFormatter &formatter) const &;
252
262 Derived numberFormatterBoth(const UnlocalizedNumberFormatter &formatter) &&;
263
273 Derived numberFormatterBoth(UnlocalizedNumberFormatter &&formatter) const &;
274
284 Derived numberFormatterBoth(UnlocalizedNumberFormatter &&formatter) &&;
285
297 Derived numberFormatterFirst(const UnlocalizedNumberFormatter &formatterFirst) const &;
298
308 Derived numberFormatterFirst(const UnlocalizedNumberFormatter &formatterFirst) &&;
309
319 Derived numberFormatterFirst(UnlocalizedNumberFormatter &&formatterFirst) const &;
320
330 Derived numberFormatterFirst(UnlocalizedNumberFormatter &&formatterFirst) &&;
331
343 Derived numberFormatterSecond(const UnlocalizedNumberFormatter &formatterSecond) const &;
344
354 Derived numberFormatterSecond(const UnlocalizedNumberFormatter &formatterSecond) &&;
355
365 Derived numberFormatterSecond(UnlocalizedNumberFormatter &&formatterSecond) const &;
366
376 Derived numberFormatterSecond(UnlocalizedNumberFormatter &&formatterSecond) &&;
377
395 Derived collapse(UNumberRangeCollapse collapse) const &;
396
406 Derived collapse(UNumberRangeCollapse collapse) &&;
407
428 Derived identityFallback(UNumberRangeIdentityFallback identityFallback) const &;
429
439 Derived identityFallback(UNumberRangeIdentityFallback identityFallback) &&;
440
447 UBool copyErrorTo(UErrorCode &outErrorCode) const {
448 if (U_FAILURE(outErrorCode)) {
449 // Do not overwrite the older error code
450 return TRUE;
451 }
452 fMacros.copyErrorTo(outErrorCode);
453 return U_FAILURE(outErrorCode);
454 };
455
456 // NOTE: Uses default copy and move constructors.
457
458 private:
459 impl::RangeMacroProps fMacros;
460
461 // Don't construct me directly! Use (Un)LocalizedNumberFormatter.
462 NumberRangeFormatterSettings() = default;
463
464 friend class LocalizedNumberRangeFormatter;
465 friend class UnlocalizedNumberRangeFormatter;
466 };
467
474 class U_I18N_API UnlocalizedNumberRangeFormatter
475 : public NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>, public UMemory {
476
477 public:
487 LocalizedNumberRangeFormatter locale(const icu::Locale &locale) const &;
488
498 LocalizedNumberRangeFormatter locale(const icu::Locale &locale) &&;
499
505 UnlocalizedNumberRangeFormatter() = default;
506
511 UnlocalizedNumberRangeFormatter(const UnlocalizedNumberRangeFormatter &other);
512
518 UnlocalizedNumberRangeFormatter(UnlocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
519
524 UnlocalizedNumberRangeFormatter& operator=(const UnlocalizedNumberRangeFormatter& other);
525
531 UnlocalizedNumberRangeFormatter& operator=(UnlocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
532
533 private:
534 explicit UnlocalizedNumberRangeFormatter(
535 const NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>& other);
536
537 explicit UnlocalizedNumberRangeFormatter(
538 NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>&& src) U_NOEXCEPT;
539
540 // To give the fluent setters access to this class's constructor:
541 friend class NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>;
542
543 // To give NumberRangeFormatter::with() access to this class's constructor:
544 friend class NumberRangeFormatter;
545 };
546
553 class U_I18N_API LocalizedNumberRangeFormatter
554 : public NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>, public UMemory {
555 public:
569 FormattedNumberRange formatFormattableRange(
570 const Formattable& first, const Formattable& second, UErrorCode& status) const;
571
577 LocalizedNumberRangeFormatter() = default;
578
583 LocalizedNumberRangeFormatter(const LocalizedNumberRangeFormatter &other);
584
590 LocalizedNumberRangeFormatter(LocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
591
596 LocalizedNumberRangeFormatter& operator=(const LocalizedNumberRangeFormatter& other);
597
603 LocalizedNumberRangeFormatter& operator=(LocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
604
605 #ifndef U_HIDE_INTERNAL_API
606
617 void formatImpl(impl::UFormattedNumberRangeData& results, bool equalBeforeRounding,
618 UErrorCode& status) const;
619
620 #endif
621
626 ~LocalizedNumberRangeFormatter();
627
628 private:
629 std::atomic<impl::NumberRangeFormatterImpl*> fAtomicFormatter = {};
630
631 const impl::NumberRangeFormatterImpl* getFormatter(UErrorCode& stauts) const;
632
633 explicit LocalizedNumberRangeFormatter(
634 const NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>& other);
635
636 explicit LocalizedNumberRangeFormatter(
637 NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>&& src) U_NOEXCEPT;
638
639 LocalizedNumberRangeFormatter(const impl::RangeMacroProps &macros, const Locale &locale);
640
641 LocalizedNumberRangeFormatter(impl::RangeMacroProps &&macros, const Locale &locale);
642
643 void clear();
644
645 // To give the fluent setters access to this class's constructor:
646 friend class NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>;
647 friend class NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>;
648
649 // To give UnlocalizedNumberRangeFormatter::locale() access to this class's constructor:
650 friend class UnlocalizedNumberRangeFormatter;
651 };
652
659 class U_I18N_API FormattedNumberRange : public UMemory {
660 public:
669 UnicodeString toString(UErrorCode& status) const;
670
682 Appendable &appendTo(Appendable &appendable, UErrorCode& status) const;
683
713 UBool nextFieldPosition(FieldPosition& fieldPosition, UErrorCode& status) const;
714
728 void getAllFieldPositions(FieldPositionIterator &iterator, UErrorCode &status) const;
729
744 UnicodeString getFirstDecimal(UErrorCode& status) const;
745
760 UnicodeString getSecondDecimal(UErrorCode& status) const;
761
771 UNumberRangeIdentityResult getIdentityResult(UErrorCode& status) const;
772
776 FormattedNumberRange(const FormattedNumberRange&) = delete;
777
781 FormattedNumberRange& operator=(const FormattedNumberRange&) = delete;
782
788 FormattedNumberRange(FormattedNumberRange&& src) U_NOEXCEPT;
789
795 FormattedNumberRange& operator=(FormattedNumberRange&& src) U_NOEXCEPT;
796
801 ~FormattedNumberRange();
802
803 private:
804 // Can't use LocalPointer because UFormattedNumberRangeData is forward-declared
805 const impl::UFormattedNumberRangeData *fResults;
806
807 // Error code for the terminal methods
808 UErrorCode fErrorCode;
809
814 explicit FormattedNumberRange(impl::UFormattedNumberRangeData *results)
815 : fResults(results), fErrorCode(U_ZERO_ERROR) {};
816
817 explicit FormattedNumberRange(UErrorCode errorCode)
818 : fResults(nullptr), fErrorCode(errorCode) {};
819
820 void getAllFieldPositionsImpl(FieldPositionIteratorHandler& fpih, UErrorCode& status) const;
821
822 // To give LocalizedNumberRangeFormatter format methods access to this class's constructor:
823 friend class LocalizedNumberRangeFormatter;
824 };
825
831 class U_I18N_API NumberRangeFormatter final {
832 public:
840 static UnlocalizedNumberRangeFormatter with();
841
851 static LocalizedNumberRangeFormatter withLocale(const Locale &locale);
852
856 NumberRangeFormatter() = delete;
857 };
858
859 } // namespace number
860 U_NAMESPACE_END
861
862 #endif // U_HIDE_DRAFT_API
863
864 #endif // __NUMBERRANGEFORMATTER_H__
865
866 #endif /* #if !UCONFIG_NO_FORMATTING */
UNUM_RANGE_COLLAPSE_UNIT
Collapse the unit part of the number, but not the notation, if present.
Definition: numberrangeformatter.h:71
U_FAILURE
#define U_FAILURE(x)
Does the error code indicate a failure?
Definition: utypes.h:699
icu::number::FormattedNumberRange
The result of a number range formatting operation.
Definition: numberrangeformatter.h:659
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:136
icu::number::NumberRangeFormatter
See the main description in numberrangeformatter.h for documentation and examples.
Definition: numberrangeformatter.h:831
icu::number::LocalizedNumberRangeFormatter
A NumberRangeFormatter that has a locale associated with it; this means .formatRange() methods are av...
Definition: numberrangeformatter.h:553
UNUM_IDENTITY_FALLBACK_APPROXIMATELY
Show the number using a locale-sensitive approximation pattern.
Definition: numberrangeformatter.h:111
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:216
UNumberRangeIdentityResult
UNumberRangeIdentityResult
Used in the result class FormattedNumberRange to indicate to the user whether the numbers formatted i...
Definition: numberrangeformatter.h:129
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:144
icu::number::NumberRangeFormatterSettings
An abstract base class for specifying settings related to number formatting.
Definition: numberrangeformatter.h:237
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:152
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:199
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:103
UNumberRangeCollapse
UNumberRangeCollapse
Defines how to merge fields that are identical across the range sign.
Definition: numberrangeformatter.h:47
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:119
icu::number::NumberRangeFormatterSettings::copyErrorTo
UBool copyErrorTo(UErrorCode &outErrorCode) const
Sets the UErrorCode if an error occurred in the fluent chain.
Definition: numberrangeformatter.h:447
icu::number::NumberFormatterSettings::copyErrorTo
UBool copyErrorTo(UErrorCode &outErrorCode) const
Sets the UErrorCode if an error occurred in the fluent chain.
Definition: numberformatter.h:2149
UNUM_RANGE_COLLAPSE_AUTO
Use locale data and heuristics to determine how much of the string to collapse.
Definition: numberrangeformatter.h:56
icu::number::UnlocalizedNumberRangeFormatter
A NumberRangeFormatter that does not yet have a locale.
Definition: numberrangeformatter.h:474
UNUM_RANGE_COLLAPSE_NONE
Do not collapse any part of the number.
Definition: numberrangeformatter.h:63
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:95
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:159
icu::number::UnlocalizedNumberFormatter
A NumberFormatter that does not yet have a locale.
Definition: numberformatter.h:2180
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:204
UNumberRangeIdentityFallback
UNumberRangeIdentityFallback
Defines the behavior when the two numbers in the range are identical after rounding.
Definition: numberrangeformatter.h:89
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:201
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:109
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:79
icu::number::impl::RangeMacroProps::copyErrorTo
bool copyErrorTo(UErrorCode &status) const
Check all members for errors.
Definition: numberrangeformatter.h:224
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