/src/icu/icu4c/source/i18n/unicode/simplenumberformatter.h

Source
// © 2022 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html

#ifndef __SIMPLENUMBERFORMATTERH__
#define __SIMPLENUMBERFORMATTERH__

#include "unicode/utypes.h"

#if U_SHOW_CPLUSPLUS_API

#if !UCONFIG_NO_FORMATTING

#include "unicode/dcfmtsym.h"
#include "unicode/usimplenumberformatter.h"
#include "unicode/formattednumber.h"

/**
 * \file
 * \brief C++ API: Simple number formatting focused on low memory and code size.
 *
 * These functions render locale-aware number strings but without the bells and whistles found in
 * other number formatting APIs such as those in numberformatter.h, like units and currencies.
 *
 * <pre>
 * SimpleNumberFormatter snf = SimpleNumberFormatter::forLocale("de-CH", status);
 * FormattedNumber result = snf.formatInt64(-1000007, status);
 * assertEquals("", u"-1’000’007", result.toString(status));
 * </pre>
 */

U_NAMESPACE_BEGIN

/* forward declaration */
class SimpleDateFormat;

namespace number {  // icu::number


namespace impl {
class UFormattedNumberData;
struct SimpleMicroProps;
class AdoptingSignumModifierStore;
}  // icu::number::impl


/**
 * An input type for SimpleNumberFormatter.
 *
 * This class is mutable and not intended for public subclassing. This class is movable but not copyable.
 *
 * @stable ICU 73
 */
class U_I18N_API SimpleNumber : public UMemory {
  public:
    /**
     * Creates a SimpleNumber for an integer.
     *
     * @stable ICU 73
     */
    static SimpleNumber forInt64(int64_t value, UErrorCode& status);

    /**
     * Changes the value of the SimpleNumber by a power of 10.
     *
     * This function immediately mutates the inner value.
     *
     * @stable ICU 73
     */
    void multiplyByPowerOfTen(int32_t power, UErrorCode& status);

    /**
     * Rounds the value currently stored in the SimpleNumber to the given power of 10,
     * which can be before or after the decimal separator.
     *
     * This function does not change minimum integer digits.
     *
     * @stable ICU 73
     */
    void roundTo(int32_t power, UNumberFormatRoundingMode roundingMode, UErrorCode& status);

    /**
     * Sets the number of integer digits to the given amount, truncating if necessary.
     *
     * @stable ICU 75
     */
    void setMaximumIntegerDigits(uint32_t maximumIntegerDigits, UErrorCode& status);

    /**
     * Pads the beginning of the number with zeros up to the given minimum number of integer digits.
     *
     * @stable ICU 73
     */
    void setMinimumIntegerDigits(uint32_t minimumIntegerDigits, UErrorCode& status);

    /**
     * Pads the end of the number with zeros up to the given minimum number of fraction digits.
     *
     * @stable ICU 73
     */
    void setMinimumFractionDigits(uint32_t minimumFractionDigits, UErrorCode& status);

    /**
     * Sets the sign of the number: an explicit plus sign, explicit minus sign, or no sign.
     *
     * This setting is applied upon formatting the number.
     *
     * NOTE: This does not support accounting sign notation.
     *
     * @stable ICU 73
     */
    void setSign(USimpleNumberSign sign, UErrorCode& status);

    /**
     * Creates a new, empty SimpleNumber that does not contain a value.
     * 
     * NOTE: This number will fail to format; use forInt64() to create a SimpleNumber with a value.
     *
     * @stable ICU 73
     */
    SimpleNumber() = default;

    /**
     * Destruct this SimpleNumber, cleaning up any memory it might own.
     *
     * @stable ICU 73
     */
    ~SimpleNumber() {
        cleanup();
    }

    /**
     * SimpleNumber move constructor.
     *
     * @stable ICU 73
     */
    SimpleNumber(SimpleNumber&& other) noexcept {
        fData = other.fData;
        fSign = other.fSign;
        other.fData = nullptr;
    }

    /**
     * SimpleNumber move assignment.
     *
     * @stable ICU 73
     */
    SimpleNumber& operator=(SimpleNumber&& other) noexcept {
        cleanup();
        fData = other.fData;
        fSign = other.fSign;
        other.fData = nullptr;
        return *this;
    }

  private:
    SimpleNumber(impl::UFormattedNumberData* data, UErrorCode& status);
    SimpleNumber(const SimpleNumber&) = delete;
    SimpleNumber& operator=(const SimpleNumber&) = delete;

    void cleanup();

    impl::UFormattedNumberData* fData = nullptr;
    USimpleNumberSign fSign = UNUM_SIMPLE_NUMBER_NO_SIGN;

    friend class SimpleNumberFormatter;

    // Uses the private constructor to avoid a heap allocation
    friend class icu::SimpleDateFormat;
};


/**
 * A special NumberFormatter focused on smaller binary size and memory use.
 * 
 * SimpleNumberFormatter is capable of basic number formatting, including grouping separators,
 * sign display, and rounding. It is not capable of currencies, compact notation, or units.
 *
 * This class is immutable and not intended for public subclassing. This class is movable but not copyable.
 *
 * @stable ICU 73
 */
class U_I18N_API SimpleNumberFormatter : public UMemory {
  public:
    /**
     * Creates a new SimpleNumberFormatter with all locale defaults.
     *
     * @stable ICU 73
     */
    static SimpleNumberFormatter forLocale(
        const icu::Locale &locale,
        UErrorCode &status);

    /**
     * Creates a new SimpleNumberFormatter, overriding the grouping strategy.
     *
     * @stable ICU 73
     */
    static SimpleNumberFormatter forLocaleAndGroupingStrategy(
        const icu::Locale &locale,
        UNumberGroupingStrategy groupingStrategy,
        UErrorCode &status);

    /**
     * Creates a new SimpleNumberFormatter, overriding the grouping strategy and symbols.
     *
     * IMPORTANT: For efficiency, this function borrows the symbols. The symbols MUST remain valid
     * for the lifetime of the SimpleNumberFormatter.
     *
     * @stable ICU 73
     */
    static SimpleNumberFormatter forLocaleAndSymbolsAndGroupingStrategy(
        const icu::Locale &locale,
        const DecimalFormatSymbols &symbols,
        UNumberGroupingStrategy groupingStrategy,
        UErrorCode &status);

    /**
     * Formats a value using this SimpleNumberFormatter.
     *
     * The SimpleNumber argument is "consumed". A new SimpleNumber object should be created for
     * every formatting operation.
     *
     * @stable ICU 73
     */
    FormattedNumber format(SimpleNumber value, UErrorCode &status) const;

    /**
     * Formats an integer using this SimpleNumberFormatter.
     *
     * For more control over the formatting, use SimpleNumber.
     *
     * @stable ICU 73
     */
    FormattedNumber formatInt64(int64_t value, UErrorCode &status) const {
        return format(SimpleNumber::forInt64(value, status), status);
    }

#ifndef U_HIDE_INTERNAL_API
    /**
     * Run the formatter with the internal types.
     * @internal
     */
    void formatImpl(impl::UFormattedNumberData* data, USimpleNumberSign sign, UErrorCode& status) const;
#endif // U_HIDE_INTERNAL_API

    /**
     * Destruct this SimpleNumberFormatter, cleaning up any memory it might own.
     *
     * @stable ICU 73
     */
    ~SimpleNumberFormatter() {
        cleanup();
    }

    /**
     * Creates a shell, initialized but non-functional SimpleNumberFormatter.
     *
     * @stable ICU 73
     */
    SimpleNumberFormatter() = default;

    /**
     * SimpleNumberFormatter: Move constructor.
     *
     * @stable ICU 73
     */
    SimpleNumberFormatter(SimpleNumberFormatter&& other) noexcept {
        fGroupingStrategy = other.fGroupingStrategy;
        fOwnedSymbols = other.fOwnedSymbols;
        fMicros = other.fMicros;
        fPatternModifier = other.fPatternModifier;
        other.fOwnedSymbols = nullptr;
        other.fMicros = nullptr;
        other.fPatternModifier = nullptr;
    }

    /**
     * SimpleNumberFormatter: Move assignment.
     *
     * @stable ICU 73
     */
    SimpleNumberFormatter& operator=(SimpleNumberFormatter&& other) noexcept {
        cleanup();
        fGroupingStrategy = other.fGroupingStrategy;
        fOwnedSymbols = other.fOwnedSymbols;
        fMicros = other.fMicros;
        fPatternModifier = other.fPatternModifier;
        other.fOwnedSymbols = nullptr;
        other.fMicros = nullptr;
        other.fPatternModifier = nullptr;
        return *this;
    }

  private:
    void initialize(
        const icu::Locale &locale,
        const DecimalFormatSymbols &symbols,
        UNumberGroupingStrategy groupingStrategy,
        UErrorCode &status);

    void cleanup();

    SimpleNumberFormatter(const SimpleNumberFormatter&) = delete;

    SimpleNumberFormatter& operator=(const SimpleNumberFormatter&) = delete;

    UNumberGroupingStrategy fGroupingStrategy = UNUM_GROUPING_AUTO;

    // Owned Pointers:
    DecimalFormatSymbols* fOwnedSymbols = nullptr; // can be empty
    impl::SimpleMicroProps* fMicros = nullptr;
    impl::AdoptingSignumModifierStore* fPatternModifier = nullptr;
};


}  // namespace number
U_NAMESPACE_END

#endif /* #if !UCONFIG_NO_FORMATTING */

#endif /* U_SHOW_CPLUSPLUS_API */

#endif // __SIMPLENUMBERFORMATTERH__


Coverage Report

Created: 2026-06-23 06:26

Line	Count	Source
1		// © 2022 and later: Unicode, Inc. and others.
2		// License & terms of use: http://www.unicode.org/copyright.html
3
4		#ifndef __SIMPLENUMBERFORMATTERH__
5		#define __SIMPLENUMBERFORMATTERH__
6
7		#include "unicode/utypes.h"
8
9		#if U_SHOW_CPLUSPLUS_API
10
11		#if !UCONFIG_NO_FORMATTING
12
13		#include "unicode/dcfmtsym.h"
14		#include "unicode/usimplenumberformatter.h"
15		#include "unicode/formattednumber.h"
16
17		/**
18		* \file
19		* \brief C++ API: Simple number formatting focused on low memory and code size.
20		*
21		* These functions render locale-aware number strings but without the bells and whistles found in
22		* other number formatting APIs such as those in numberformatter.h, like units and currencies.
23		*
24		* <pre>
25		* SimpleNumberFormatter snf = SimpleNumberFormatter::forLocale("de-CH", status);
26		* FormattedNumber result = snf.formatInt64(-1000007, status);
27		* assertEquals("", u"-1’000’007", result.toString(status));
28		* </pre>
29		*/
30
31		U_NAMESPACE_BEGIN
32
33		/* forward declaration */
34		class SimpleDateFormat;
35
36		namespace number { // icu::number
37
38
39		namespace impl {
40		class UFormattedNumberData;
41		struct SimpleMicroProps;
42		class AdoptingSignumModifierStore;
43		} // icu::number::impl
44
45
46		/**
47		* An input type for SimpleNumberFormatter.
48		*
49		* This class is mutable and not intended for public subclassing. This class is movable but not copyable.
50		*
51		* @stable ICU 73
52		*/
53		class U_I18N_API SimpleNumber : public UMemory {
54		public:
55		/**
56		* Creates a SimpleNumber for an integer.
57		*
58		* @stable ICU 73
59		*/
60		static SimpleNumber forInt64(int64_t value, UErrorCode& status);
61
62		/**
63		* Changes the value of the SimpleNumber by a power of 10.
64		*
65		* This function immediately mutates the inner value.
66		*
67		* @stable ICU 73
68		*/
69		void multiplyByPowerOfTen(int32_t power, UErrorCode& status);
70
71		/**
72		* Rounds the value currently stored in the SimpleNumber to the given power of 10,
73		* which can be before or after the decimal separator.
74		*
75		* This function does not change minimum integer digits.
76		*
77		* @stable ICU 73
78		*/
79		void roundTo(int32_t power, UNumberFormatRoundingMode roundingMode, UErrorCode& status);
80
81		/**
82		* Sets the number of integer digits to the given amount, truncating if necessary.
83		*
84		* @stable ICU 75
85		*/
86		void setMaximumIntegerDigits(uint32_t maximumIntegerDigits, UErrorCode& status);
87
88		/**
89		* Pads the beginning of the number with zeros up to the given minimum number of integer digits.
90		*
91		* @stable ICU 73
92		*/
93		void setMinimumIntegerDigits(uint32_t minimumIntegerDigits, UErrorCode& status);
94
95		/**
96		* Pads the end of the number with zeros up to the given minimum number of fraction digits.
97		*
98		* @stable ICU 73
99		*/
100		void setMinimumFractionDigits(uint32_t minimumFractionDigits, UErrorCode& status);
101
102		/**
103		* Sets the sign of the number: an explicit plus sign, explicit minus sign, or no sign.
104		*
105		* This setting is applied upon formatting the number.
106		*
107		* NOTE: This does not support accounting sign notation.
108		*
109		* @stable ICU 73
110		*/
111		void setSign(USimpleNumberSign sign, UErrorCode& status);
112
113		/**
114		* Creates a new, empty SimpleNumber that does not contain a value.
115		*
116		* NOTE: This number will fail to format; use forInt64() to create a SimpleNumber with a value.
117		*
118		* @stable ICU 73
119		*/
120	0	SimpleNumber() = default;
121
122		/**
123		* Destruct this SimpleNumber, cleaning up any memory it might own.
124		*
125		* @stable ICU 73
126		*/
127	189k	~SimpleNumber() {
128	189k	cleanup();
129	189k	}
130
131		/**
132		* SimpleNumber move constructor.
133		*
134		* @stable ICU 73
135		*/
136	94.8k	SimpleNumber(SimpleNumber&& other) noexcept {
137	94.8k	fData = other.fData;
138	94.8k	fSign = other.fSign;
139	94.8k	other.fData = nullptr;
140	94.8k	}
141
142		/**
143		* SimpleNumber move assignment.
144		*
145		* @stable ICU 73
146		*/
147	0	SimpleNumber& operator=(SimpleNumber&& other) noexcept {
148	0	cleanup();
149	0	fData = other.fData;
150	0	fSign = other.fSign;
151	0	other.fData = nullptr;
152	0	return *this;
153	0	}
154
155		private:
156		SimpleNumber(impl::UFormattedNumberData* data, UErrorCode& status);
157		SimpleNumber(const SimpleNumber&) = delete;
158		SimpleNumber& operator=(const SimpleNumber&) = delete;
159
160		void cleanup();
161
162		impl::UFormattedNumberData* fData = nullptr;
163		USimpleNumberSign fSign = UNUM_SIMPLE_NUMBER_NO_SIGN;
164
165		friend class SimpleNumberFormatter;
166
167		// Uses the private constructor to avoid a heap allocation
168		friend class icu::SimpleDateFormat;
169		};
170
171
172		/**
173		* A special NumberFormatter focused on smaller binary size and memory use.
174		*
175		* SimpleNumberFormatter is capable of basic number formatting, including grouping separators,
176		* sign display, and rounding. It is not capable of currencies, compact notation, or units.
177		*
178		* This class is immutable and not intended for public subclassing. This class is movable but not copyable.
179		*
180		* @stable ICU 73
181		*/
182		class U_I18N_API SimpleNumberFormatter : public UMemory {
183		public:
184		/**
185		* Creates a new SimpleNumberFormatter with all locale defaults.
186		*
187		* @stable ICU 73
188		*/
189		static SimpleNumberFormatter forLocale(
190		const icu::Locale &locale,
191		UErrorCode &status);
192
193		/**
194		* Creates a new SimpleNumberFormatter, overriding the grouping strategy.
195		*
196		* @stable ICU 73
197		*/
198		static SimpleNumberFormatter forLocaleAndGroupingStrategy(
199		const icu::Locale &locale,
200		UNumberGroupingStrategy groupingStrategy,
201		UErrorCode &status);
202
203		/**
204		* Creates a new SimpleNumberFormatter, overriding the grouping strategy and symbols.
205		*
206		* IMPORTANT: For efficiency, this function borrows the symbols. The symbols MUST remain valid
207		* for the lifetime of the SimpleNumberFormatter.
208		*
209		* @stable ICU 73
210		*/
211		static SimpleNumberFormatter forLocaleAndSymbolsAndGroupingStrategy(
212		const icu::Locale &locale,
213		const DecimalFormatSymbols &symbols,
214		UNumberGroupingStrategy groupingStrategy,
215		UErrorCode &status);
216
217		/**
218		* Formats a value using this SimpleNumberFormatter.
219		*
220		* The SimpleNumber argument is "consumed". A new SimpleNumber object should be created for
221		* every formatting operation.
222		*
223		* @stable ICU 73
224		*/
225		FormattedNumber format(SimpleNumber value, UErrorCode &status) const;
226
227		/**
228		* Formats an integer using this SimpleNumberFormatter.
229		*
230		* For more control over the formatting, use SimpleNumber.
231		*
232		* @stable ICU 73
233		*/
234	0	FormattedNumber formatInt64(int64_t value, UErrorCode &status) const {
235	0	return format(SimpleNumber::forInt64(value, status), status);
236	0	}
237
238		#ifndef U_HIDE_INTERNAL_API
239		/**
240		* Run the formatter with the internal types.
241		* @internal
242		*/
243		void formatImpl(impl::UFormattedNumberData* data, USimpleNumberSign sign, UErrorCode& status) const;
244		#endif // U_HIDE_INTERNAL_API
245
246		/**
247		* Destruct this SimpleNumberFormatter, cleaning up any memory it might own.
248		*
249		* @stable ICU 73
250		*/
251	119k	~SimpleNumberFormatter() {
252	119k	cleanup();
253	119k	}
254
255		/**
256		* Creates a shell, initialized but non-functional SimpleNumberFormatter.
257		*
258		* @stable ICU 73
259		*/
260	119k	SimpleNumberFormatter() = default;
261
262		/**
263		* SimpleNumberFormatter: Move constructor.
264		*
265		* @stable ICU 73
266		*/
267	0	SimpleNumberFormatter(SimpleNumberFormatter&& other) noexcept {
268	0	fGroupingStrategy = other.fGroupingStrategy;
269	0	fOwnedSymbols = other.fOwnedSymbols;
270	0	fMicros = other.fMicros;
271	0	fPatternModifier = other.fPatternModifier;
272	0	other.fOwnedSymbols = nullptr;
273	0	other.fMicros = nullptr;
274	0	other.fPatternModifier = nullptr;
275	0	}
276
277		/**
278		* SimpleNumberFormatter: Move assignment.
279		*
280		* @stable ICU 73
281		*/
282	0	SimpleNumberFormatter& operator=(SimpleNumberFormatter&& other) noexcept {
283	0	cleanup();
284	0	fGroupingStrategy = other.fGroupingStrategy;
285	0	fOwnedSymbols = other.fOwnedSymbols;
286	0	fMicros = other.fMicros;
287	0	fPatternModifier = other.fPatternModifier;
288	0	other.fOwnedSymbols = nullptr;
289	0	other.fMicros = nullptr;
290	0	other.fPatternModifier = nullptr;
291	0	return *this;
292	0	}
293
294		private:
295		void initialize(
296		const icu::Locale &locale,
297		const DecimalFormatSymbols &symbols,
298		UNumberGroupingStrategy groupingStrategy,
299		UErrorCode &status);
300
301		void cleanup();
302
303		SimpleNumberFormatter(const SimpleNumberFormatter&) = delete;
304
305		SimpleNumberFormatter& operator=(const SimpleNumberFormatter&) = delete;
306
307		UNumberGroupingStrategy fGroupingStrategy = UNUM_GROUPING_AUTO;
308
309		// Owned Pointers:
310		DecimalFormatSymbols* fOwnedSymbols = nullptr; // can be empty
311		impl::SimpleMicroProps* fMicros = nullptr;
312		impl::AdoptingSignumModifierStore* fPatternModifier = nullptr;
313		};
314
315
316		} // namespace number
317		U_NAMESPACE_END
318
319		#endif /* #if !UCONFIG_NO_FORMATTING */
320
321		#endif /* U_SHOW_CPLUSPLUS_API */
322
323		#endif // __SIMPLENUMBERFORMATTERH__
324