ICU 65.1 65.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 #ifndef __NUMBERRANGEFORMATTER_H__
5 #define __NUMBERRANGEFORMATTER_H__
6
7 #include "unicode/utypes.h"
8
9 #if U_SHOW_CPLUSPLUS_API
10
11 #if !UCONFIG_NO_FORMATTING
12
13 #include <atomic>
14 #include "unicode/appendable.h"
15 #include "unicode/fieldpos.h"
16 #include "unicode/formattedvalue.h"
17 #include "unicode/fpositer.h"
18 #include "unicode/numberformatter.h"
19
52 typedef enum UNumberRangeCollapse {
61 UNUM_RANGE_COLLAPSE_AUTO,
62
68 UNUM_RANGE_COLLAPSE_NONE,
69
76 UNUM_RANGE_COLLAPSE_UNIT,
77
84 UNUM_RANGE_COLLAPSE_ALL
85 } UNumberRangeCollapse;
86
94 typedef enum UNumberRangeIdentityFallback {
100 UNUM_IDENTITY_FALLBACK_SINGLE_VALUE,
101
108 UNUM_IDENTITY_FALLBACK_APPROXIMATELY_OR_SINGLE_VALUE,
109
116 UNUM_IDENTITY_FALLBACK_APPROXIMATELY,
117
124 UNUM_IDENTITY_FALLBACK_RANGE
125 } UNumberRangeIdentityFallback;
126
134 typedef enum UNumberRangeIdentityResult {
141 UNUM_IDENTITY_RESULT_EQUAL_BEFORE_ROUNDING,
142
149 UNUM_IDENTITY_RESULT_EQUAL_AFTER_ROUNDING,
150
157 UNUM_IDENTITY_RESULT_NOT_EQUAL,
158
159 #ifndef U_HIDE_INTERNAL_API
160
164 UNUM_IDENTITY_RESULT_COUNT
165 #endif
166
167 } UNumberRangeIdentityResult;
168
169 U_NAMESPACE_BEGIN
170
171 namespace number { // icu::number
172
173 // Forward declarations:
174 class UnlocalizedNumberRangeFormatter;
175 class LocalizedNumberRangeFormatter;
176 class FormattedNumberRange;
177
178 namespace impl {
179
180 // Forward declarations:
181 struct RangeMacroProps;
182 class DecimalQuantity;
183 class UFormattedNumberRangeData;
184 class NumberRangeFormatterImpl;
185
186 } // namespace impl
187
193 #if U_PLATFORM == U_PF_WINDOWS && !defined(U_IN_DOXYGEN)
194 } // namespace icu::number
195 U_NAMESPACE_END
196
197 template struct U_I18N_API std::atomic< U_NAMESPACE_QUALIFIER number::impl::NumberRangeFormatterImpl*>;
198
199 U_NAMESPACE_BEGIN
200 namespace number { // icu::number
201 #endif
202
204 // Other helper classes would go here, but there are none.
205
206 namespace impl { // icu::number::impl
207
208 // Do not enclose entire MacroProps with #ifndef U_HIDE_INTERNAL_API, needed for a protected field
210 struct U_I18N_API RangeMacroProps : public UMemory {
212 UnlocalizedNumberFormatter formatter1; // = NumberFormatter::with();
213
215 UnlocalizedNumberFormatter formatter2; // = NumberFormatter::with();
216
218 bool singleFormatter = true;
219
221 UNumberRangeCollapse collapse = UNUM_RANGE_COLLAPSE_AUTO;
222
224 UNumberRangeIdentityFallback identityFallback = UNUM_IDENTITY_FALLBACK_APPROXIMATELY;
225
227 Locale locale;
228
229 // NOTE: Uses default copy and move constructors.
230
235 bool copyErrorTo(UErrorCode &status) const {
236 return formatter1.copyErrorTo(status) || formatter2.copyErrorTo(status);
237 }
238 };
239
240 } // namespace impl
241
247 template<typename Derived>
248 class U_I18N_API NumberRangeFormatterSettings {
249 public:
262 Derived numberFormatterBoth(const UnlocalizedNumberFormatter &formatter) const &;
263
273 Derived numberFormatterBoth(const UnlocalizedNumberFormatter &formatter) &&;
274
284 Derived numberFormatterBoth(UnlocalizedNumberFormatter &&formatter) const &;
285
295 Derived numberFormatterBoth(UnlocalizedNumberFormatter &&formatter) &&;
296
308 Derived numberFormatterFirst(const UnlocalizedNumberFormatter &formatterFirst) const &;
309
319 Derived numberFormatterFirst(const UnlocalizedNumberFormatter &formatterFirst) &&;
320
330 Derived numberFormatterFirst(UnlocalizedNumberFormatter &&formatterFirst) const &;
331
341 Derived numberFormatterFirst(UnlocalizedNumberFormatter &&formatterFirst) &&;
342
354 Derived numberFormatterSecond(const UnlocalizedNumberFormatter &formatterSecond) const &;
355
365 Derived numberFormatterSecond(const UnlocalizedNumberFormatter &formatterSecond) &&;
366
376 Derived numberFormatterSecond(UnlocalizedNumberFormatter &&formatterSecond) const &;
377
387 Derived numberFormatterSecond(UnlocalizedNumberFormatter &&formatterSecond) &&;
388
406 Derived collapse(UNumberRangeCollapse collapse) const &;
407
417 Derived collapse(UNumberRangeCollapse collapse) &&;
418
439 Derived identityFallback(UNumberRangeIdentityFallback identityFallback) const &;
440
450 Derived identityFallback(UNumberRangeIdentityFallback identityFallback) &&;
451
452 #ifndef U_HIDE_DRAFT_API
453
464 LocalPointer<Derived> clone() const &;
465
473 LocalPointer<Derived> clone() &&;
474 #endif /* U_HIDE_DRAFT_API */
475
482 UBool copyErrorTo(UErrorCode &outErrorCode) const {
483 if (U_FAILURE(outErrorCode)) {
484 // Do not overwrite the older error code
485 return TRUE;
486 }
487 fMacros.copyErrorTo(outErrorCode);
488 return U_FAILURE(outErrorCode);
489 }
490
491 // NOTE: Uses default copy and move constructors.
492
493 private:
494 impl::RangeMacroProps fMacros;
495
496 // Don't construct me directly! Use (Un)LocalizedNumberFormatter.
497 NumberRangeFormatterSettings() = default;
498
499 friend class LocalizedNumberRangeFormatter;
500 friend class UnlocalizedNumberRangeFormatter;
501 };
502
511 class U_I18N_API UnlocalizedNumberRangeFormatter
512 : public NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>, public UMemory {
513
514 public:
524 LocalizedNumberRangeFormatter locale(const icu::Locale &locale) const &;
525
535 LocalizedNumberRangeFormatter locale(const icu::Locale &locale) &&;
536
542 UnlocalizedNumberRangeFormatter() = default;
543
548 UnlocalizedNumberRangeFormatter(const UnlocalizedNumberRangeFormatter &other);
549
555 UnlocalizedNumberRangeFormatter(UnlocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
556
561 UnlocalizedNumberRangeFormatter& operator=(const UnlocalizedNumberRangeFormatter& other);
562
568 UnlocalizedNumberRangeFormatter& operator=(UnlocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
569
570 private:
571 explicit UnlocalizedNumberRangeFormatter(
572 const NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>& other);
573
574 explicit UnlocalizedNumberRangeFormatter(
575 NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>&& src) U_NOEXCEPT;
576
577 // To give the fluent setters access to this class's constructor:
578 friend class NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>;
579
580 // To give NumberRangeFormatter::with() access to this class's constructor:
581 friend class NumberRangeFormatter;
582 };
583
592 class U_I18N_API LocalizedNumberRangeFormatter
593 : public NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>, public UMemory {
594 public:
608 FormattedNumberRange formatFormattableRange(
609 const Formattable& first, const Formattable& second, UErrorCode& status) const;
610
616 LocalizedNumberRangeFormatter() = default;
617
622 LocalizedNumberRangeFormatter(const LocalizedNumberRangeFormatter &other);
623
629 LocalizedNumberRangeFormatter(LocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
630
635 LocalizedNumberRangeFormatter& operator=(const LocalizedNumberRangeFormatter& other);
636
642 LocalizedNumberRangeFormatter& operator=(LocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
643
644 #ifndef U_HIDE_INTERNAL_API
645
656 void formatImpl(impl::UFormattedNumberRangeData& results, bool equalBeforeRounding,
657 UErrorCode& status) const;
658
659 #endif /* U_HIDE_INTERNAL_API */
660
665 ~LocalizedNumberRangeFormatter();
666
667 private:
668 std::atomic<impl::NumberRangeFormatterImpl*> fAtomicFormatter = {};
669
670 const impl::NumberRangeFormatterImpl* getFormatter(UErrorCode& stauts) const;
671
672 explicit LocalizedNumberRangeFormatter(
673 const NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>& other);
674
675 explicit LocalizedNumberRangeFormatter(
676 NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>&& src) U_NOEXCEPT;
677
678 LocalizedNumberRangeFormatter(const impl::RangeMacroProps &macros, const Locale &locale);
679
680 LocalizedNumberRangeFormatter(impl::RangeMacroProps &&macros, const Locale &locale);
681
682 void clear();
683
684 // To give the fluent setters access to this class's constructor:
685 friend class NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>;
686 friend class NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>;
687
688 // To give UnlocalizedNumberRangeFormatter::locale() access to this class's constructor:
689 friend class UnlocalizedNumberRangeFormatter;
690 };
691
700 class U_I18N_API FormattedNumberRange : public UMemory, public FormattedValue {
701 public:
702 // Copybrief: this method is older than the parent method
710 UnicodeString toString(UErrorCode& status) const U_OVERRIDE;
711
712 // Copydoc: this method is new in ICU 64
714 UnicodeString toTempString(UErrorCode& status) const U_OVERRIDE;
715
716 // Copybrief: this method is older than the parent method
724 Appendable &appendTo(Appendable &appendable, UErrorCode& status) const U_OVERRIDE;
725
726 // Copydoc: this method is new in ICU 64
728 UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const U_OVERRIDE;
729
730 #ifndef U_HIDE_DRAFT_API
731
760 UBool nextFieldPosition(FieldPosition& fieldPosition, UErrorCode& status) const;
761
775 void getAllFieldPositions(FieldPositionIterator &iterator, UErrorCode &status) const;
776
791 UnicodeString getFirstDecimal(UErrorCode& status) const;
792
807 UnicodeString getSecondDecimal(UErrorCode& status) const;
808 #endif // U_HIDE_DRAFT_API
809
819 UNumberRangeIdentityResult getIdentityResult(UErrorCode& status) const;
820
824 FormattedNumberRange(const FormattedNumberRange&) = delete;
825
829 FormattedNumberRange& operator=(const FormattedNumberRange&) = delete;
830
836 FormattedNumberRange(FormattedNumberRange&& src) U_NOEXCEPT;
837
843 FormattedNumberRange& operator=(FormattedNumberRange&& src) U_NOEXCEPT;
844
849 ~FormattedNumberRange();
850
851 private:
852 // Can't use LocalPointer because UFormattedNumberRangeData is forward-declared
853 const impl::UFormattedNumberRangeData *fData;
854
855 // Error code for the terminal methods
856 UErrorCode fErrorCode;
857
861 explicit FormattedNumberRange(impl::UFormattedNumberRangeData *results)
862 : fData(results), fErrorCode(U_ZERO_ERROR) {}
863
864 explicit FormattedNumberRange(UErrorCode errorCode)
865 : fData(nullptr), fErrorCode(errorCode) {}
866
867 void getAllFieldPositionsImpl(FieldPositionIteratorHandler& fpih, UErrorCode& status) const;
868
869 // To give LocalizedNumberRangeFormatter format methods access to this class's constructor:
870 friend class LocalizedNumberRangeFormatter;
871 };
872
878 class U_I18N_API NumberRangeFormatter final {
879 public:
887 static UnlocalizedNumberRangeFormatter with();
888
898 static LocalizedNumberRangeFormatter withLocale(const Locale &locale);
899
903 NumberRangeFormatter() = delete;
904 };
905
906 } // namespace number
907 U_NAMESPACE_END
908
909 #endif /* #if !UCONFIG_NO_FORMATTING */
910
911 #endif /* U_SHOW_CPLUSPLUS_API */
912
913 #endif // __NUMBERRANGEFORMATTER_H__
914
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:76
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:709
icu::number::FormattedNumberRange
The result of a number range formatting operation.
Definition: numberrangeformatter.h:700
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:141
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:878
icu::number::LocalizedNumberRangeFormatter
A NumberRangeFormatter that has a locale associated with it; this means .formatRange() methods are av...
Definition: numberrangeformatter.h:592
UNUM_IDENTITY_FALLBACK_APPROXIMATELY
Show the number using a locale-sensitive approximation pattern.
Definition: numberrangeformatter.h:116
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:227
UNumberRangeIdentityResult
UNumberRangeIdentityResult
Used in the result class FormattedNumberRange to indicate to the user whether the numbers formatted i...
Definition: numberrangeformatter.h:134
U_ZERO_ERROR
No error, no warning.
Definition: utypes.h:449
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:149
icu::number::NumberRangeFormatterSettings
An abstract base class for specifying settings related to number formatting.
Definition: numberrangeformatter.h:248
icu::FormattedValue
An abstract formatted value: a string with associated field attributes.
Definition: formattedvalue.h:254
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:157
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:210
UNUM_IDENTITY_FALLBACK_APPROXIMATELY_OR_SINGLE_VALUE
Show the number using a locale-sensitive approximation pattern.
Definition: numberrangeformatter.h:108
UNumberRangeCollapse
UNumberRangeCollapse
Defines how to merge fields that are identical across the range sign.
Definition: numberrangeformatter.h:52
icu::FieldPositionIterator
FieldPositionIterator returns the field ids and their start/limit positions generated by a call to Fo...
Definition: fpositer.h:58
UNUM_IDENTITY_FALLBACK_RANGE
Show the number as the range of two equal values.
Definition: numberrangeformatter.h:124
icu::number::NumberRangeFormatterSettings::copyErrorTo
UBool copyErrorTo(UErrorCode &outErrorCode) const
Sets the UErrorCode if an error occurred in the fluent chain.
Definition: numberrangeformatter.h:482
icu::number::NumberFormatterSettings::copyErrorTo
UBool copyErrorTo(UErrorCode &outErrorCode) const
Sets the UErrorCode if an error occurred in the fluent chain.
Definition: numberformatter.h:2115
UNUM_RANGE_COLLAPSE_AUTO
Use locale data and heuristics to determine how much of the string to collapse.
Definition: numberrangeformatter.h:61
icu::number::UnlocalizedNumberRangeFormatter
A NumberRangeFormatter that does not yet have a locale.
Definition: numberrangeformatter.h:511
UNUM_RANGE_COLLAPSE_NONE
Do not collapse any part of the number.
Definition: numberrangeformatter.h:68
TRUE
#define TRUE
The TRUE value of a UBool.
Definition: umachine.h:265
UNUM_IDENTITY_FALLBACK_SINGLE_VALUE
Show the number as a single value rather than a range.
Definition: numberrangeformatter.h:100
icu::ConstrainedFieldPosition
Represents a span of a string containing a given field.
Definition: formattedvalue.h:46
U_NOEXCEPT
#define U_NOEXCEPT
"noexcept" if supported, otherwise empty.
Definition: platform.h:529
UNUM_IDENTITY_RESULT_COUNT
The number of entries in this enum.
Definition: numberrangeformatter.h:164
icu::number::UnlocalizedNumberFormatter
A NumberFormatter that does not yet have a locale.
Definition: numberformatter.h:2148
icu::number::impl::RangeMacroProps::formatter2
UnlocalizedNumberFormatter formatter2
Definition: numberrangeformatter.h:215
UNumberRangeIdentityFallback
UNumberRangeIdentityFallback
Defines the behavior when the two numbers in the range are identical after rounding.
Definition: numberrangeformatter.h:94
UErrorCode
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
icu::FieldPosition
FieldPosition is a simple class used by Format and its subclasses to identify fields in formatted out...
Definition: fieldpos.h:110
icu::number::impl::RangeMacroProps::formatter1
UnlocalizedNumberFormatter formatter1
Definition: numberrangeformatter.h:212
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
icu::UnicodeString
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition: unistr.h:294
icu::Formattable
Formattable objects can be passed to the Format class or its subclasses for formatting.
Definition: fmtable.h:64
icu::UMemory
UMemory is the common ICU base class.
Definition: uobject.h:115
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:84
icu::number::impl::RangeMacroProps::copyErrorTo
bool copyErrorTo(UErrorCode &status) const
Check all members for errors.
Definition: numberrangeformatter.h:235
UBool
int8_t UBool
The ICU boolean type.
Definition: umachine.h:261
icu::Appendable
Base class for objects to which Unicode characters and strings can be appended.
Definition: appendable.h:54
icu::Locale
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:195