2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
4 // Licensed under the Apache License, Version 2.0 (the License);
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
8 // http://www.apache.org/licenses/LICENSE-2.0
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
18 * @file FLclNumberFormatter.h
19 * @brief This is the header file for the %NumberFormatter class.
21 * This header file contains the declarations of the %NumberFormatter class.
24 #ifndef _FLCL_NUMBER_FORMATTER_H_
25 #define _FLCL_NUMBER_FORMATTER_H_
27 #include <FLclLocale.h>
28 #include <FLclCurrency.h>
30 namespace Tizen { namespace Locales
34 * @class NumberFormatter
35 * @brief This class provides methods for formatting numbers.
39 * The %NumberFormatter class is used to format all number formats, including decimal and real numbers, currency, and percentage
40 * for any locale. It also provides methods to determine the locales that have number formats and their names. You can write
41 * codes completely independent of the locale conventions for decimal points, thousand separators, the specific
42 * decimal digits used, or the number format. A normal decimal number can also be displayed as a currency or as a percentage.
44 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/locales/num_formatter.htm">Number Formatters</a>.
46 * The following example demonstrates how to use the %NumberFormatter class.
53 using namespace Tizen::Base;
54 using namespace Tizen::Locales;
57 LocaleApp::NumberFormatterExample(void)
60 Locale koreaLoc(LANGUAGE_KOR, COUNTRY_KR);
62 // Get number formatter
63 NumberFormatter* pNumberFormatter = NumberFormatter::CreateNumberFormatterN(koreaLoc);
65 String formattedString;
67 // Format number with number formatter
68 double num = 345987.246;
69 pNumberFormatter->Format(num, formattedString);
71 // Get currency formatter
72 NumberFormatter* pCurrencyFormatter = NumberFormatter::CreateCurrencyFormatterN(koreaLoc);
74 // Format number with currency formatter
76 pCurrencyFormatter->Format(num, formattedString);
78 // Get percent formatter
79 NumberFormatter* pPercentFormatter = NumberFormatter::CreatePercentFormatterN(koreaLoc);
81 // Format number with percent formatter
83 pPercentFormatter->Format(num, formattedString);
85 delete pNumberFormatter;
86 delete pCurrencyFormatter;
87 delete pPercentFormatter;
93 class _OSP_EXPORT_ NumberFormatter
94 : public Tizen::Base::Object
98 * This is the destructor for this class. @n
99 * This destructor overrides Tizen::Base::Object::~Object().
103 virtual ~NumberFormatter(void);
107 * Creates a number formatter for the system locale.
111 * @return A pointer to the general number formatter for the default locale, @n
112 * else @c null if an error occurs
113 * @exception E_SUCCESS The method is successful.
114 * @exception E_OUT_OF_MEMORY The memory is insufficient.
115 * @exception E_UNSUPPORTED_OPERATION The system locale is not supported.
116 * @remarks The specific error code can be accessed using the GetLastResult() method.
118 static NumberFormatter* CreateNumberFormatterN(void);
122 * Creates a number formatter for the specified locale.
125 * @brief <i> [Compatibility] </i>
129 * @compatibility This method has compatibility issues with OSP compatible applications. @n
130 * For more information, see @ref CompNumberFormatterCreateNumberFormatterNPage "here".
133 * @return A pointer to the general number formatter for the specified @c locale, @n
134 * else @c null if an error occurs
135 * @param[in] locale An instance of Locale
136 * @exception E_SUCCESS The method is successful.
137 * @exception E_OUT_OF_MEMORY The memory is insufficient.
138 * @exception E_INVALID_ARG The specified @c locale is invalid.
139 * @remarks The specific error code can be accessed using the GetLastResult() method.
141 static NumberFormatter* CreateNumberFormatterN(const Locale& locale);
145 * @page CompNumberFormatterCreateNumberFormatterNPage Compatibility for CreateNumberFormatterN()
146 * @section CompNumberFormatterCreateNumberFormatterNIssueSection Issues
147 * Implementation of this method in OSP compatible applications has the following issue: @n
148 * -# The method returns @c E_UNSUPPORTED_OPERATION if the @c locale is invalid.
150 * @section CompNumberFormatterCreateNumberFormatterNSolutionSection Resolutions
151 * This issue has been resolved in Tizen.
152 * @par When working in Tizen:
153 * -# The method returns @c E_INVALID_ARG if the @c locale is invalid.
158 * Creates a currency formatter for the default locale.
162 * @return A pointer to the currency formatter for the default locale, @n
163 * else @c null if an error occurs
164 * @exception E_SUCCESS The method is successful.
165 * @exception E_OUT_OF_MEMORY The memory is insufficient.
166 * @exception E_UNSUPPORTED_OPERATION The system locale is not supported.
167 * @remarks The specific error code can be accessed using the GetLastResult() method.
169 static NumberFormatter* CreateCurrencyFormatterN(void);
173 * Creates a currency formatter for the specified @c locale.
176 * @brief <i> [Compatibility] </i>
180 * @compatibility This method has compatibility issues with OSP compatible applications. @n
181 * For more information, see @ref CompNumberFormatterCreateCurrencyFormatterNPage "here".
184 * @return A pointer to the currency formatter for the specified @c locale, @n
185 * else @c null if an error occurs
186 * @param[in] locale An instance of Locale
187 * @exception E_SUCCESS The method is successful.
188 * @exception E_OUT_OF_MEMORY The memory is insufficient.
189 * @exception E_INVALID_ARG The specified @c locale is invalid.
190 * @remarks The specific error code can be accessed using the GetLastResult() method.
192 static NumberFormatter* CreateCurrencyFormatterN(const Locale& locale);
196 * @page CompNumberFormatterCreateCurrencyFormatterNPage Compatibility for CreateCurrencyFormatterN()
197 * @section CompNumberFormatterCreateCurrencyFormatterNIssueSection Issues
198 * Implementation of this method in OSP compatible applications has the following issue: @n
199 * -# The method returns @c E_UNSUPPORTED_OPERATION if the @c locale is invalid.
201 * @section CompNumberFormatterCreateCurrencyFormatterNSolutionSection Resolutions
202 * This issue has been resolved in Tizen.
203 * @par When working in Tizen:
204 * -# The method returns @c E_INVALID_ARG if the @c locale is invalid.
209 * Creates a percentage formatter for the system locale.
213 * @return A pointer to the percentage formatter for the default locale, @n
214 * else @c null if an error occurs
215 * @exception E_SUCCESS The method is successful.
216 * @exception E_OUT_OF_MEMORY The memory is insufficient.
217 * @exception E_UNSUPPORTED_OPERATION The system locale is not supported.
218 * @remarks The specific error code can be accessed using the GetLastResult() method.
220 static NumberFormatter* CreatePercentFormatterN(void);
224 * Creates a percentage formatter for the specified @c locale.
227 * @brief <i> [Compatibility] </i>
231 * @compatibility This method has compatibility issues with OSP compatible applications. @n
232 * For more information, see @ref CompNumberFormatterCreatePercentFormatterNPage "here".
235 * @return A pointer to the percentage formatter for the specified @c locale, @n
236 * else @c null if an error occurs
237 * @param[in] locale An instance of Locale
238 * @exception E_SUCCESS The method is successful.
239 * @exception E_OUT_OF_MEMORY The memory is insufficient.
240 * @exception E_INVALID_ARG The specified @c locale is invalid.
241 * @remarks The specific error code can be accessed using the GetLastResult() method.
243 static NumberFormatter* CreatePercentFormatterN(const Locale& locale);
247 * @page CompNumberFormatterCreatePercentFormatterNPage Compatibility for CreatePercentFormatterN()
248 * @section CompNumberFormatterCreatePercentFormatterNIssueSection Issues
249 * Implementation of this method in OSP compatible applications has the following issue: @n
250 * -# The method returns @c E_UNSUPPORTED_OPERATION if the @c locale is invalid.
252 * @section CompNumberFormatterCreatePercentFormatterNSolutionSection Resolutions
253 * This issue has been resolved in Tizen.
254 * @par When working in Tizen:
255 * -# The method returns @c E_INVALID_ARG if the @c locale is invalid.
262 * Formats a number of type Tizen::Base::Long to type Tizen::Base::String and appends the resulting string to a buffer.
266 * @return An error code
267 * @param[in] number The number of type Tizen::Base::Long to format
268 * @param[out] str The string to append
269 * @exception E_SUCCESS The method is successful.
271 virtual result Format(long number, Tizen::Base::String& str) const;
275 * Formats a number of type Tizen::Base::Double to type Tizen::Base::String and appends the resulting string to a buffer.
279 * @return An error code
280 * @param[in] number The number of type Tizen::Base::Double to format
281 * @param[out] str The string to append
282 * @exception E_SUCCESS The method is successful.
284 virtual result Format(double number, Tizen::Base::String& str) const;
288 * Gets the currency used by the current number format when formatting currency values.
292 * @return A pointer to an instance of Currency
293 * @remarks The initial value is derived in a locale dependent way. @n
294 * The returned value may be @c null if no valid currency is determined
295 * or no currency has been set using the SetCurrency() method.
297 virtual const Currency* GetCurrency(void) const;
301 * Sets the currency to be used by the current number format when formatting currency values.
305 * @param[in] currency The currency to set
306 * @remarks This does not update the minimum or maximum number of fractional digits used by the number format.
309 virtual void SetCurrency(const Currency& currency);
313 * Gets the maximum number of digits allowed in the integer portion of a number.
317 * @return An integer value representing the maximum number of digits allowed in the integer portion of a number
318 * @see SetMaxIntegerDigits()
320 virtual int GetMaxIntegerDigits(void) const;
324 * Sets the maximum number of digits allowed in the integer portion of a number.
328 * @param[in] newValue The maximum number of integer digits allowed in the integer portion of a number, @n
329 * If less than zero, @c 0 is used.
330 * @remarks The maximum integer digits must be greater than or equal to the minimum integer digits.@n
331 * If the new value for the maximum integer digits is less than the current value of the minimum integer digits,
332 * the minimum integer digits are also set to the new value.
333 * @see GetMaxIntegerDigits()
335 virtual void SetMaxIntegerDigits(int newValue);
339 * Gets the minimum number of digits allowed in the integer portion of a number.
343 * @return An integer value representing the minimum number of digits
344 * @see SetMinIntegerDigits()
346 virtual int GetMinIntegerDigits(void) const;
350 * Sets the minimum number of digits allowed in the integer portion of a number.
354 * @param[in] newValue The minimum number of integer digits allowed in the integer portion of a number @n
355 * If less than zero, @c 0 is used.
356 * @remarks The minimum integer digits must be less than or equal to the maximum integer digits. @n
357 * If the new value for the minimum integer digits exceeds the current value of the maximum integer digits,
358 * the maximum integer digits are also set to the new value.
359 * @see GetMinIntegerDigits()
361 virtual void SetMinIntegerDigits(int newValue);
365 * Gets the maximum number of digits allowed in the fractional portion of a number.
369 * @return An integer value representing the maximum number of digits
370 * @see SetMaxFractionDigits()
372 virtual int GetMaxFractionDigits(void) const;
376 * Sets the maximum number of digits allowed in the fractional portion of a number.
380 * @param[in] newValue The maximum number of fractional digits allowed in the fractional portion of a number @n
381 * If less than zero, @c 0 is used.
382 * @remarks The maximum fractional digits must be greater than or equal to the minimum fractional digits. @n
383 * If the new value for the maximum fractional digits is less than the current value of the minimum fractional digits,
384 * the minimum fractional digits are also set to the new value.
385 * @see GetMaxFractionDigits()
387 virtual void SetMaxFractionDigits(int newValue);
391 * Gets the minimum number of digits allowed in the fractional portion of a number.
395 * @return An integer value representing the minimum number of digits allowed in the fractional portion of a number
396 * @see SetMinFractionDigits()
398 virtual int GetMinFractionDigits(void) const;
402 * Sets the minimum number of digits allowed in the fractional portion of a number.
406 * @param[in] newValue The minimum number of fractional digits allowed in the fractional portion of a number @n
407 * If less than zero, @c 0 is used.
408 * @remarks The minimum fractional digits must be less than or equal to the maximum fractional digits. @n
409 * If the new value for the minimum fractional digits exceeds the current value of the maximum fraction digits,
410 * the maximum fraction digits are also set to the new value.
411 * @see GetMinFractionDigits()
413 virtual void SetMinFractionDigits(int newValue);
417 * Checks whether the grouping is used in the current instance of %NumberFormatter.
421 * @return @c true if grouping is used in the current instance of %NumberFormatter, @n
424 * - For example, in the English locale, with grouping on, the number 1234567
425 * might be formatted as "1,234,567".
426 * - The grouping separator as well as the size of each group is locale dependent
427 * and is determined by subclasses of %NumberFormatter.
428 * @see SetGroupingUsed()
430 virtual bool IsGroupingUsed(void) const;
434 * Sets the use of grouping in the current instance of %NumberFormatter.
438 * @param[in] newValue Set to @c true to use grouping in the current formatter, @n
440 * @see IsGroupingUsed()
442 virtual void SetGroupingUsed(bool newValue);
446 * Applies the pattern to the current instance of %NumberFormatter.
450 * @return An error code
451 * @param[in] pattern The pattern to apply
452 * @param[in] localized The flag to set the localization on or off @n
453 * Set to @c true if the pattern is applied with the localized symbols, @n
455 * @exception E_SUCCESS The method is successful.
456 * @exception E_INVALID_ARG The specified @c pattern is invalid or its length is @c 0.
458 result ApplyPattern(const Tizen::Base::String& pattern, bool localized);
462 * Gets the positive prefix of the current instance of %NumberFormatter.
466 * @return The positive prefix of the current %NumberFormatter instance
467 * @remarks For example: +123, $123, sFr123.
468 * @see SetPositivePrefix()
470 Tizen::Base::String GetPositivePrefix(void) const;
474 * Sets the positive prefix of the current instance of %NumberFormatter.
478 * @param[in] newValue The positive prefix to set
479 * @see GetPositivePrefix()
481 void SetPositivePrefix(const Tizen::Base::String& newValue);
485 * Gets the negative prefix of the current instance of %NumberFormatter.
489 * @return The negative prefix of the current %NumberFormatter instance
490 * @remarks For example: -123, $123 (with negative prefix), sFr-123
491 * @see SetNegativePrefix()
493 Tizen::Base::String GetNegativePrefix(void) const;
497 * Sets the negative prefix of the current instance of %NumberFormatter.
501 * @param[in] newValue The negative prefix to set
502 * @see GetNegativePrefix()
504 void SetNegativePrefix(const Tizen::Base::String& newValue);
508 * Gets the positive suffix of the current instance of %NumberFormatter.
512 * @return The positive suffix of the current %NumberFormatter instance
513 * @remarks For example: 123%
514 * @see SetPositiveSuffix()
516 Tizen::Base::String GetPositiveSuffix(void) const;
520 * Sets the positive suffix of the current instance of %NumberFormatter.
524 * @param[in] newValue The positive suffix to set
525 * @see GetPositiveSuffix()
527 void SetPositiveSuffix(const Tizen::Base::String& newValue);
531 * Gets the negative suffix of the current instance of %NumberFormatter.
535 * @return The negative suffix of the current %NumberFormatter instance
536 * @remarks For example: -123%, $123 (with negative suffix)
537 * @see SetNegativeSuffix()
539 Tizen::Base::String GetNegativeSuffix(void) const;
543 * Sets the negative suffix of the current instance of %NumberFormatter.
547 * @param[in] newValue The negative suffix to set
548 * @see GetNegativeSuffix()
550 void SetNegativeSuffix(const Tizen::Base::String& newValue);
554 * Gets the multiplier for use in percent, per mill, and so on.
558 * @return An integer value representing the multiplier
559 * @remarks For example: with 100, 1.23 -> "123", and "123" -> 1.23
560 * @see SetMultiplier()
562 int GetMultiplier(void) const;
566 * Sets the multiplier for use in percent, per mill, and so on.
570 * @param[in] newValue The multiplier to set
571 * @exception E_SUCCESS The method is successful.
572 * @exception E_INVALID_ARG The specified input parameter is invalid.
573 * @remarks For example, in percentage, set the suffixes to have "%" and the multiplier to be 100.
574 * @see GetMultiplier()
576 result SetMultiplier(int newValue);
580 * Gets the grouping size.
584 * @return An integer value representing the grouping size
585 * @remarks The grouping size is the number of digits between the grouping separators in the integer portion of a number. @n
586 * For example, in the number "123,456.78", the grouping size is 3.
587 * @see SetGroupingSize()
588 * @see IsGroupingUsed()
590 int GetGroupingSize(void) const;
594 * Sets the grouping size.
598 * @param[in] newValue The grouping size to set
599 * @exception E_SUCCESS The method is successful.
600 * @exception E_INVALID_ARG The specified input parameter is invalid.
601 * @see GetGroupingSize()
602 * @see SetGroupingUsed()
604 result SetGroupingSize(int newValue);
608 * Checks whether the decimal separator is always shown.
612 * @return @c true if the decimal separator is always shown, @n
614 * @remarks For example: ON: 12345 -> 12345.; OFF: 12345 -> 12345
615 * @see SetDecimalSeparatorAlwaysShown()
617 bool IsDecimalSeparatorAlwaysShown(void) const;
621 * Sets the visibility behavior of the decimal separator. @n
622 * The decimal separator can be set to always appear using this method.
626 * @param[in] newValue Set to @c true to always show the decimal separator, @n
628 * @see IsDecimalSeparatorAlwaysShown()
630 void SetDecimalSeparatorAlwaysShown(bool newValue);
634 * Checks whether the positive sign is always shown.
638 * @return @c true if the positive sign is always shown, @n
640 * @remarks For example: ON: 12345 -> +12345.; OFF: 12345 -> 12345.
641 * @see SetPositiveSignAlwaysShown()
643 bool IsPositiveSignAlwaysShown(void) const;
647 * Sets the visibility behavior of the plus sign. @n
648 * The plus sign can be set to always appear using this method.
652 * @param[in] newValue Set to @c true to always show the plus sign, @n
654 * @see IsPositiveSignAlwaysShown()
656 void SetPositiveSignAlwaysShown(bool newValue);
661 * This default constructor is intentionally declared as private so that only the platform can create an instance.
663 NumberFormatter(void);
666 * The implementation of this copy constructor is intentionally blank and declared as private to
667 * prohibit copying of objects.
669 NumberFormatter(const NumberFormatter& numberFormatter);
672 * The implementation of this copy assignment operator is intentionally blank and declared as private
673 * to prohibit copying of objects.
675 NumberFormatter& operator =(const NumberFormatter& numberFormatter);
677 friend class _NumberFormatterImpl;
678 class _NumberFormatterImpl* __pNumberFormatterImpl;
680 }; // NumberFormatter
684 #endif //_FLCL_NUMBER_FORMATTER_H_