ICU 68.2  68.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 #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"
20 
48 U_NAMESPACE_BEGIN
49 
50 // Forward declarations:
51 class PluralRules;
52 
53 namespace number { // icu::number
54 
55 // Forward declarations:
56 class UnlocalizedNumberRangeFormatter;
57 class LocalizedNumberRangeFormatter;
58 class FormattedNumberRange;
59 
60 namespace impl {
61 
62 // Forward declarations:
63 struct RangeMacroProps;
64 class DecimalQuantity;
65 class UFormattedNumberRangeData;
66 class NumberRangeFormatterImpl;
67 struct UFormattedNumberRangeImpl;
68 
69 } // namespace impl
70 
76 #if U_PLATFORM == U_PF_WINDOWS && !defined(U_IN_DOXYGEN)
77 } // namespace icu::number
78 U_NAMESPACE_END
79 
80 template struct U_I18N_API std::atomic< U_NAMESPACE_QUALIFIER number::impl::NumberRangeFormatterImpl*>;
81 
82 U_NAMESPACE_BEGIN
83 namespace number { // icu::number
84 #endif
85 
87 // Other helper classes would go here, but there are none.
88 
89 namespace impl { // icu::number::impl
90 
91 // Do not enclose entire MacroProps with #ifndef U_HIDE_INTERNAL_API, needed for a protected field
95  UnlocalizedNumberFormatter formatter1; // = NumberFormatter::with();
96 
98  UnlocalizedNumberFormatter formatter2; // = NumberFormatter::with();
99 
101  bool singleFormatter = true;
102 
105 
108 
111 
112  // NOTE: Uses default copy and move constructors.
113 
118  bool copyErrorTo(UErrorCode &status) const {
119  return formatter1.copyErrorTo(status) || formatter2.copyErrorTo(status);
120  }
121 };
122 
123 } // namespace impl
124 
130 template<typename Derived>
132  public:
145  Derived numberFormatterBoth(const UnlocalizedNumberFormatter &formatter) const &;
146 
156  Derived numberFormatterBoth(const UnlocalizedNumberFormatter &formatter) &&;
157 
167  Derived numberFormatterBoth(UnlocalizedNumberFormatter &&formatter) const &;
168 
179 
191  Derived numberFormatterFirst(const UnlocalizedNumberFormatter &formatterFirst) const &;
192 
202  Derived numberFormatterFirst(const UnlocalizedNumberFormatter &formatterFirst) &&;
203 
213  Derived numberFormatterFirst(UnlocalizedNumberFormatter &&formatterFirst) const &;
214 
224  Derived numberFormatterFirst(UnlocalizedNumberFormatter &&formatterFirst) &&;
225 
237  Derived numberFormatterSecond(const UnlocalizedNumberFormatter &formatterSecond) const &;
238 
248  Derived numberFormatterSecond(const UnlocalizedNumberFormatter &formatterSecond) &&;
249 
259  Derived numberFormatterSecond(UnlocalizedNumberFormatter &&formatterSecond) const &;
260 
270  Derived numberFormatterSecond(UnlocalizedNumberFormatter &&formatterSecond) &&;
271 
289  Derived collapse(UNumberRangeCollapse collapse) const &;
290 
300  Derived collapse(UNumberRangeCollapse collapse) &&;
301 
322  Derived identityFallback(UNumberRangeIdentityFallback identityFallback) const &;
323 
333  Derived identityFallback(UNumberRangeIdentityFallback identityFallback) &&;
334 
347 
355  LocalPointer<Derived> clone() &&;
356 
363  UBool copyErrorTo(UErrorCode &outErrorCode) const {
364  if (U_FAILURE(outErrorCode)) {
365  // Do not overwrite the older error code
366  return true;
367  }
368  fMacros.copyErrorTo(outErrorCode);
369  return U_FAILURE(outErrorCode);
370  }
371 
372  // NOTE: Uses default copy and move constructors.
373 
374  private:
375  impl::RangeMacroProps fMacros;
376 
377  // Don't construct me directly! Use (Un)LocalizedNumberFormatter.
378  NumberRangeFormatterSettings() = default;
379 
380  friend class LocalizedNumberRangeFormatter;
381  friend class UnlocalizedNumberRangeFormatter;
382 };
383 
394 
395  public:
406 
417 
424 
430 
437 
443 
450 
451  private:
454 
457 
458  // To give the fluent setters access to this class's constructor:
460 
461  // To give NumberRangeFormatter::with() access to this class's constructor:
462  friend class NumberRangeFormatter;
463 };
464 
475  public:
490  const Formattable& first, const Formattable& second, UErrorCode& status) const;
491 
498 
504 
511 
517 
524 
525 #ifndef U_HIDE_INTERNAL_API
526 
537  void formatImpl(impl::UFormattedNumberRangeData& results, bool equalBeforeRounding,
538  UErrorCode& status) const;
539 
540 #endif /* U_HIDE_INTERNAL_API */
541 
547 
548  private:
549  std::atomic<impl::NumberRangeFormatterImpl*> fAtomicFormatter = {};
550 
551  const impl::NumberRangeFormatterImpl* getFormatter(UErrorCode& stauts) const;
552 
555 
558 
559  LocalizedNumberRangeFormatter(const impl::RangeMacroProps &macros, const Locale &locale);
560 
562 
563  void clear();
564 
565  // To give the fluent setters access to this class's constructor:
568 
569  // To give UnlocalizedNumberRangeFormatter::locale() access to this class's constructor:
570  friend class UnlocalizedNumberRangeFormatter;
571 };
572 
582  public:
583  // Copybrief: this method is older than the parent method
592 
593  // Copydoc: this method is new in ICU 64
596 
597  // Copybrief: this method is older than the parent method
605  Appendable &appendTo(Appendable &appendable, UErrorCode& status) const U_OVERRIDE;
606 
607  // Copydoc: this method is new in ICU 64
610 
611 #ifndef U_HIDE_DEPRECATED_API
612 
631 
651 #endif // U_HIDE_DEPRECATED_API
652 
653 
654 #ifndef U_HIDE_DRAFT_API
655 
674  template<typename StringClass>
675  inline std::pair<StringClass, StringClass> getDecimalNumbers(UErrorCode& status) const;
676 #endif // U_HIDE_DRAFT_API
677 
688 
693 
698 
705 
712 
718 
719  private:
720  // Can't use LocalPointer because UFormattedNumberRangeData is forward-declared
721  const impl::UFormattedNumberRangeData *fData;
722 
723  // Error code for the terminal methods
724  UErrorCode fErrorCode;
725 
729  explicit FormattedNumberRange(impl::UFormattedNumberRangeData *results)
730  : fData(results), fErrorCode(U_ZERO_ERROR) {}
731 
732  explicit FormattedNumberRange(UErrorCode errorCode)
733  : fData(nullptr), fErrorCode(errorCode) {}
734 
735  void getAllFieldPositionsImpl(FieldPositionIteratorHandler& fpih, UErrorCode& status) const;
736 
737  void getDecimalNumbers(ByteSink& sink1, ByteSink& sink2, UErrorCode& status) const;
738 
739  const impl::UFormattedNumberRangeData* getData(UErrorCode& status) const;
740 
741  // To allow PluralRules to access the underlying data
742  friend class ::icu::PluralRules;
743 
744  // To give LocalizedNumberRangeFormatter format methods access to this class's constructor:
745  friend class LocalizedNumberRangeFormatter;
746 
747  // To give C API access to internals
748  friend struct impl::UFormattedNumberRangeImpl;
749 };
750 
751 #ifndef U_HIDE_DRAFT_API
752 // Note: This is draft ICU 68
753 template<typename StringClass>
754 std::pair<StringClass, StringClass> FormattedNumberRange::getDecimalNumbers(UErrorCode& status) const {
755  StringClass str1;
756  StringClass str2;
757  StringByteSink<StringClass> sink1(&str1);
758  StringByteSink<StringClass> sink2(&str2);
759  getDecimalNumbers(sink1, sink2, status);
760  return std::make_pair(str1, str2);
761 }
762 #endif // U_HIDE_DRAFT_API
763 
770  public:
779 
790 
795 };
796 
797 } // namespace number
798 U_NAMESPACE_END
799 
800 #endif /* #if !UCONFIG_NO_FORMATTING */
801 
802 #endif /* U_SHOW_CPLUSPLUS_API */
803 
804 #endif // __NUMBERRANGEFORMATTER_H__
805 
icu::number::FormattedNumberRange::getSecondDecimal
UnicodeString getSecondDecimal(UErrorCode &status) const
Export the second formatted number as a decimal number.
icu::number::UnlocalizedNumberRangeFormatter::locale
LocalizedNumberRangeFormatter locale(const icu::Locale &locale) &&
Overload of locale() for use on an rvalue reference.
fpositer.h
C++ API: FieldPosition Iterator.
icu::number::FormattedNumberRange::FormattedNumberRange
FormattedNumberRange(const FormattedNumberRange &)=delete
Copying not supported; use move constructor instead.
icu::number::LocalizedNumberRangeFormatter::formatFormattableRange
FormattedNumberRange formatFormattableRange(const Formattable &first, const Formattable &second, UErrorCode &status) const
Format the given Formattables to a string using the settings specified in the NumberRangeFormatter fl...
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
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
icu::number::NumberRangeFormatter::NumberRangeFormatter
NumberRangeFormatter()=delete
Use factory methods instead of the constructor to create a NumberFormatter.
icu::number::FormattedNumberRange::nextPosition
UBool nextPosition(ConstrainedFieldPosition &cfpos, UErrorCode &status) const U_OVERRIDE
Iterates over field positions in the FormattedValue.
UBool
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:269
U_NOEXCEPT
#define U_NOEXCEPT
"noexcept" if supported, otherwise empty.
Definition: platform.h:529
icu::Formattable
Formattable objects can be passed to the Format class or its subclasses for formatting.
Definition: fmtable.h:64
icu::number::UnlocalizedNumberRangeFormatter
A NumberRangeFormatter that does not yet have a locale.
Definition: numberrangeformatter.h:393
icu::FormattedValue
An abstract formatted value: a string with associated field attributes.
Definition: formattedvalue.h:241
icu::number::NumberRangeFormatterSettings::collapse
Derived collapse(UNumberRangeCollapse collapse) &&
Overload of collapse() for use on an rvalue reference.
icu::number::NumberRangeFormatterSettings::numberFormatterFirst
Derived numberFormatterFirst(UnlocalizedNumberFormatter &&formatterFirst) const &
Overload of numberFormatterFirst() for use on an rvalue reference.
icu::number::FormattedNumberRange::~FormattedNumberRange
~FormattedNumberRange()
Destruct an instance of FormattedNumberRange, cleaning up any memory it might own.
icu::number::NumberRangeFormatter::with
static UnlocalizedNumberRangeFormatter with()
Call this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is not c...
icu::number::NumberRangeFormatterSettings::numberFormatterFirst
Derived numberFormatterFirst(UnlocalizedNumberFormatter &&formatterFirst) &&
Overload of numberFormatterFirst() for use on an rvalue reference.
icu::number::impl::RangeMacroProps::locale
Locale locale
Definition: numberrangeformatter.h:110
icu::number::NumberRangeFormatterSettings::identityFallback
Derived identityFallback(UNumberRangeIdentityFallback identityFallback) &&
Overload of identityFallback() for use on an rvalue reference.
icu::number::LocalizedNumberRangeFormatter::operator=
LocalizedNumberRangeFormatter & operator=(LocalizedNumberRangeFormatter &&src) U_NOEXCEPT
Move assignment operator: The source LocalizedNumberRangeFormatter will be left in a valid but undefi...
U_OVERRIDE
#define U_OVERRIDE
Defined to the C++11 "override" keyword if available.
Definition: umachine.h:130
icu::number::FormattedNumberRange::toString
UnicodeString toString(UErrorCode &status) const U_OVERRIDE
Returns the formatted string as a self-contained UnicodeString.
icu::number::NumberRangeFormatterSettings::collapse
Derived collapse(UNumberRangeCollapse collapse) const &
Sets the aggressiveness of "collapsing" fields across the range separator.
icu::LocalPointer
"Smart pointer" class, deletes objects via the standard C++ delete operator.
Definition: localpointer.h:191
icu::number::UnlocalizedNumberRangeFormatter::operator=
UnlocalizedNumberRangeFormatter & operator=(UnlocalizedNumberRangeFormatter &&src) U_NOEXCEPT
Move assignment operator: The source UnlocalizedNumberRangeFormatter will be left in a valid but unde...
icu::number::NumberRangeFormatterSettings::identityFallback
Derived identityFallback(UNumberRangeIdentityFallback identityFallback) const &
Sets the behavior when the two sides of the range are the same.
icu::number::NumberFormatterSettings::copyErrorTo
UBool copyErrorTo(UErrorCode &outErrorCode) const
Sets the UErrorCode if an error occurred in the fluent chain.
Definition: numberformatter.h:2259
icu::number::LocalizedNumberRangeFormatter::LocalizedNumberRangeFormatter
LocalizedNumberRangeFormatter(const LocalizedNumberRangeFormatter &other)
Returns a copy of this LocalizedNumberRangeFormatter.
icu::number::FormattedNumberRange::FormattedNumberRange
FormattedNumberRange(FormattedNumberRange &&src) U_NOEXCEPT
Move constructor: Leaves the source FormattedNumberRange in an undefined state.
icu::number::UnlocalizedNumberRangeFormatter::operator=
UnlocalizedNumberRangeFormatter & operator=(const UnlocalizedNumberRangeFormatter &other)
Copy assignment operator.
icu::number::impl::RangeMacroProps
Definition: numberrangeformatter.h:93
icu::number::NumberRangeFormatterSettings::numberFormatterSecond
Derived numberFormatterSecond(UnlocalizedNumberFormatter &&formatterSecond) &&
Overload of numberFormatterSecond() for use on an rvalue reference.
icu::number::UnlocalizedNumberRangeFormatter::locale
LocalizedNumberRangeFormatter locale(const icu::Locale &locale) const &
Associate the given locale with the number range formatter.
fieldpos.h
C++ API: FieldPosition identifies the fields in a formatted output.
icu::number::NumberRangeFormatterSettings::numberFormatterBoth
Derived numberFormatterBoth(UnlocalizedNumberFormatter &&formatter) const &
Overload of numberFormatterBoth() for use on an rvalue reference.
icu::UnicodeString
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition: unistr.h:295
icu::number::FormattedNumberRange::operator=
FormattedNumberRange & operator=(FormattedNumberRange &&src) U_NOEXCEPT
Move assignment: Leaves the source FormattedNumberRange in an undefined state.
U_FAILURE
#define U_FAILURE(x)
Does the error code indicate a failure?
Definition: utypes.h:719
icu::number::NumberRangeFormatterSettings::numberFormatterSecond
Derived numberFormatterSecond(UnlocalizedNumberFormatter &&formatterSecond) const &
Overload of numberFormatterSecond() for use on an rvalue reference.
UErrorCode
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
icu::number::NumberRangeFormatterSettings::numberFormatterBoth
Derived numberFormatterBoth(const UnlocalizedNumberFormatter &formatter) const &
Sets the NumberFormatter instance to use for the numbers in the range.
icu::number::UnlocalizedNumberRangeFormatter::UnlocalizedNumberRangeFormatter
UnlocalizedNumberRangeFormatter()=default
Default constructor: puts the formatter into a valid but undefined state.
icu::number::FormattedNumberRange
The result of a number range formatting operation.
Definition: numberrangeformatter.h:581
icu::number::UnlocalizedNumberFormatter
A NumberFormatter that does not yet have a locale.
Definition: numberformatter.h:2293
icu::ByteSink
A ByteSink can be filled with bytes.
Definition: bytestream.h:53
icu::UMemory
UMemory is the common ICU base class.
Definition: uobject.h:115
icu::number::NumberRangeFormatterSettings
An abstract base class for specifying settings related to number formatting.
Definition: numberrangeformatter.h:131
icu::number::FormattedNumberRange::toTempString
UnicodeString toTempString(UErrorCode &status) const U_OVERRIDE
Returns the formatted string as a read-only alias to memory owned by the FormattedValue.
icu::number::LocalizedNumberRangeFormatter::LocalizedNumberRangeFormatter
LocalizedNumberRangeFormatter()=default
Default constructor: puts the formatter into a valid but undefined state.
icu::number::FormattedNumberRange::getFirstDecimal
UnicodeString getFirstDecimal(UErrorCode &status) const
Export the first formatted number as a decimal number.
icu::number::FormattedNumberRange::getIdentityResult
UNumberRangeIdentityResult getIdentityResult(UErrorCode &status) const
Returns whether the pair of numbers was successfully formatted as a range or whether an identity fall...
icu::number::NumberRangeFormatterSettings::numberFormatterSecond
Derived numberFormatterSecond(const UnlocalizedNumberFormatter &formatterSecond) &&
Overload of numberFormatterSecond() for use on an rvalue reference.
U_ZERO_ERROR
@ U_ZERO_ERROR
No error, no warning.
Definition: utypes.h:449
appendable.h
C++ API: Appendable class: Sink for Unicode code points and 16-bit code units (char16_ts).
icu::number::LocalizedNumberRangeFormatter::operator=
LocalizedNumberRangeFormatter & operator=(const LocalizedNumberRangeFormatter &other)
Copy assignment operator.
icu::number::NumberRangeFormatterSettings::numberFormatterFirst
Derived numberFormatterFirst(const UnlocalizedNumberFormatter &formatterFirst) const &
Sets the NumberFormatter instance to use for the first number in the range.
icu::number::UnlocalizedNumberRangeFormatter::UnlocalizedNumberRangeFormatter
UnlocalizedNumberRangeFormatter(const UnlocalizedNumberRangeFormatter &other)
Returns a copy of this UnlocalizedNumberRangeFormatter.
icu::number::impl::RangeMacroProps::formatter2
UnlocalizedNumberFormatter formatter2
Definition: numberrangeformatter.h:98
formattedvalue.h
C++ API: Abstract operations for localized strings.
icu::number::NumberRangeFormatterSettings::numberFormatterFirst
Derived numberFormatterFirst(const UnlocalizedNumberFormatter &formatterFirst) &&
Overload of numberFormatterFirst() for use on an rvalue reference.
UNumberRangeCollapse
UNumberRangeCollapse
Defines how to merge fields that are identical across the range sign.
Definition: unumberrangeformatter.h:83
icu::Appendable
Base class for objects to which Unicode characters and strings can be appended.
Definition: appendable.h:54
icu::number::FormattedNumberRange::appendTo
Appendable & appendTo(Appendable &appendable, UErrorCode &status) const U_OVERRIDE
Appends the formatted string to an Appendable.
UNUM_RANGE_COLLAPSE_AUTO
@ UNUM_RANGE_COLLAPSE_AUTO
Use locale data and heuristics to determine how much of the string to collapse.
Definition: unumberrangeformatter.h:92
numberformatter.h
C++ API: Library for localized number formatting introduced in ICU 60.
icu::number::FormattedNumberRange::operator=
FormattedNumberRange & operator=(const FormattedNumberRange &)=delete
Copying not supported; use move assignment instead.
icu::number::LocalizedNumberRangeFormatter::LocalizedNumberRangeFormatter
LocalizedNumberRangeFormatter(LocalizedNumberRangeFormatter &&src) U_NOEXCEPT
Move constructor: The source LocalizedNumberRangeFormatter will be left in a valid but undefined stat...
icu::number::NumberRangeFormatter
See the main description in numberrangeformatter.h for documentation and examples.
Definition: numberrangeformatter.h:769
icu::number::UnlocalizedNumberRangeFormatter::UnlocalizedNumberRangeFormatter
UnlocalizedNumberRangeFormatter(UnlocalizedNumberRangeFormatter &&src) U_NOEXCEPT
Move constructor: The source UnlocalizedNumberRangeFormatter will be left in a valid but undefined st...
icu::number::LocalizedNumberRangeFormatter::~LocalizedNumberRangeFormatter
~LocalizedNumberRangeFormatter()
Destruct this LocalizedNumberRangeFormatter, cleaning up any memory it might own.
icu::number::LocalizedNumberRangeFormatter
A NumberRangeFormatter that has a locale associated with it; this means .formatRange() methods are av...
Definition: numberrangeformatter.h:474
icu::StringByteSink
Implementation of ByteSink that writes to a "string".
Definition: bytestream.h:269
UNumberRangeIdentityFallback
UNumberRangeIdentityFallback
Defines the behavior when the two numbers in the range are identical after rounding.
Definition: unumberrangeformatter.h:125
icu::number::impl::RangeMacroProps::formatter1
UnlocalizedNumberFormatter formatter1
Definition: numberrangeformatter.h:95
unumberrangeformatter.h
C-compatible API for localized number range formatting.
UNumberRangeIdentityResult
UNumberRangeIdentityResult
Used in the result class FormattedNumberRange to indicate to the user whether the numbers formatted i...
Definition: unumberrangeformatter.h:165
icu::number::NumberRangeFormatterSettings::clone
LocalPointer< Derived > clone() const &
Returns the current (Un)LocalizedNumberRangeFormatter as a LocalPointer wrapping a heap-allocated cop...
UNUM_IDENTITY_FALLBACK_APPROXIMATELY
@ UNUM_IDENTITY_FALLBACK_APPROXIMATELY
Show the number using a locale-sensitive approximation pattern.
Definition: unumberrangeformatter.h:147
icu::number::NumberRangeFormatterSettings::numberFormatterBoth
Derived numberFormatterBoth(const UnlocalizedNumberFormatter &formatter) &&
Overload of numberFormatterBoth() for use on an rvalue reference.
icu::number::NumberRangeFormatterSettings::numberFormatterSecond
Derived numberFormatterSecond(const UnlocalizedNumberFormatter &formatterSecond) const &
Sets the NumberFormatter instance to use for the second number in the range.
icu::number::NumberRangeFormatterSettings::numberFormatterBoth
Derived numberFormatterBoth(UnlocalizedNumberFormatter &&formatter) &&
Overload of numberFormatterBoth() for use on an rvalue reference.
icu::number::LocalizedNumberRangeFormatter::formatImpl
void formatImpl(impl::UFormattedNumberRangeData &results, bool equalBeforeRounding, UErrorCode &status) const
icu::Locale
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:195
icu::number::impl::RangeMacroProps::copyErrorTo
bool copyErrorTo(UErrorCode &status) const
Check all members for errors.
Definition: numberrangeformatter.h:118
icu::ConstrainedFieldPosition
Represents a span of a string containing a given field.
Definition: formattedvalue.h:41
icu::number::NumberRangeFormatter::withLocale
static LocalizedNumberRangeFormatter withLocale(const Locale &locale)
Call this method at the beginning of a NumberRangeFormatter fluent chain in which the locale is known...