28 |
28 |
29 /*! |
29 /*! |
30 @stable |
30 @stable |
31 @hbcore |
31 @hbcore |
32 \class HbNumberGrouping |
32 \class HbNumberGrouping |
33 \brief HbNumberGrouping formats numbers according to conventions of a certain country. |
33 \brief The HbNumberGrouping class formats numbers according to the conventions of a certain locale. |
34 Eg. for Finland: "123456789.00" => "123 456 789,00". |
|
35 |
34 |
36 NOTE! |
35 The grouping of numbers may vary in different locales. For example, for |
37 - Characters in 'number' parameter needs to be latin numbers even though the type of parameter is QString. |
36 Finland, the number \c "123456789.00" would be formatted as \c "123 456 |
38 - Also '+' and '-' characters are supported. |
37 789,00". The grouping may also vary depending on the context of where |
39 - Decimal separator needs to be a dot '.' always. |
38 numbers are used. HbNumberGrouping provides functions for grouping currency |
40 - Any other characters than above descripted are not allowed. |
39 values and generic numbers. |
41 - If grouping fails for some reason then return value is empty QString. |
|
42 - At the moment currency mark is not added to return value (formatCurrency). |
|
43 - Grouping for phone numbers is not activated yet. |
|
44 |
40 |
45 Example: |
41 For example, to format \c "1234567890" according to the current system |
46 |
42 locale: |
47 \snippet{unittest_hbnumbergrouping/unittest_hbnumbergrouping.cpp,1} |
43 |
48 |
44 \code |
|
45 QString number("1234567890"); |
|
46 QString result = HbNumberGrouping::formatGeneric(number); |
|
47 \endcode |
|
48 |
|
49 Use HbStringUtil to display the number using the locale digit type, and use |
|
50 HbExtendedLocale and QLocale for other currency formatting. |
|
51 |
49 */ |
52 */ |
50 |
53 |
51 /*! |
54 /*! |
52 Static function for creating a (generic) number group. |
55 |
|
56 Returns a number grouped based on the given country format, or the current |
|
57 locale. |
53 |
58 |
54 \attention Cross-Platform API |
59 \param number The source number string to be grouped. The characters must be |
|
60 Latin digits, and always use '.' as the decimal separator. '+' and '-' |
|
61 characters are also supported. No other characters are supported. |
|
62 |
|
63 \param country (optional) The QLocale::Country enumeration (in QLocale) that |
|
64 determines the format to be used for converting the number. If \a country is |
|
65 not given, the number is grouped based on the current locale. |
55 |
66 |
56 \param number Source number for grouping. |
67 \return The modified number as a QString if successful, otherwise an empty |
57 \param country Format for number converting. |
68 QString. |
58 If the country is not given (country = QLocale::AnyCountry) then it will be requested from QLocale::country. |
69 |
59 |
|
60 \return modified string. |
|
61 */ |
70 */ |
62 QString HbNumberGrouping::formatGeneric( const QString &number, |
71 QString HbNumberGrouping::formatGeneric( const QString &number, |
63 QLocale::Country country ) |
72 QLocale::Country country ) |
64 { |
73 { |
65 if ( number.size() == 0 ) { |
74 if ( number.size() == 0 ) { |
66 return QString(); |
75 return QString(); |
67 } |
76 } |
68 |
77 |
69 if ( country == QLocale::AnyCountry) { |
78 if ( country == QLocale::AnyCountry) { |
70 QLocale locale; |
79 QLocale locale; |
71 country = locale.country(); |
80 country = locale.country(); |
72 } |
81 } |
73 |
82 |
74 return HbNgNormalNumber::normalNumberGrouping(number, country); |
83 return HbNgNormalNumber::normalNumberGrouping(number, country); |
75 } |
84 } |
76 |
85 |
77 /*! |
86 /*! |
78 Static function for creating a currency group. |
87 |
|
88 Returns a currency value grouped based on the given country format, or the |
|
89 current locale. |
|
90 |
|
91 \param number The source number string to be grouped. The characters must be |
|
92 Latin digits, and always use '.' as the decimal separator. '+' and '-' |
|
93 characters are also supported. No other characters are supported. |
79 |
94 |
80 \attention Cross-Platform API |
95 \param country (optional) The QLocale::Country enumeration (in QLocale) that |
|
96 determines the format to be used for converting the number. If \a country is |
|
97 not given, the number is grouped based on the current locale. |
81 |
98 |
82 \param number Source number for grouping. |
99 \return The modified number as a QString if successful, otherwise an empty |
83 \param country Format for number converting. |
100 QString. |
84 If the country is not given (country = QLocale::AnyCountry) then it will be requested from QLocale::country. |
101 |
85 |
102 \note The currency symbol is not added to the return value. Use |
86 \return modified string. |
103 HbExtendedLocale to handle the currency symbol. |
|
104 |
87 */ |
105 */ |
88 QString HbNumberGrouping::formatCurrency( const QString &number, |
106 QString HbNumberGrouping::formatCurrency( const QString &number, |
89 QLocale::Country country ) |
107 QLocale::Country country ) |
90 { |
108 { |
91 if ( number.size() == 0 ) { |
109 if ( number.size() == 0 ) { |
92 return QString(); |
110 return QString(); |
93 } |
111 } |
94 |
112 |
95 if ( country == QLocale::AnyCountry) { |
113 if ( country == QLocale::AnyCountry) { |
96 QLocale locale; |
114 QLocale locale; |
97 country = locale.country(); |
115 country = locale.country(); |
98 } |
116 } |
99 |
117 |
100 return HbNgNormalNumber::normalNumberGrouping(number, country); |
118 return HbNgNormalNumber::normalNumberGrouping(number, country); |
101 } |
119 } |
102 |
120 |
103 /*! |
121 /*! |
104 Static function for creating a phone number group. |
122 \internal |
|
123 |
|
124 Returns a phone number grouped based on the given country format, or the |
|
125 current locale. |
|
126 |
|
127 \note The grouping of phone numbers is not supported yet. |
105 |
128 |
106 \attention Cross-Platform API |
129 \param number The source number for grouping. The characters must be |
|
130 Latin digits, and always use '.' as the decimal separator. '+' and '-' |
|
131 characters are also supported. No other characters are supported. |
|
132 |
|
133 \param country (optional) The QLocale::country numeration (in QLocale) that |
|
134 determines the format to be used for converting the number. If \a country is |
|
135 not given, the number is grouped based on the current locale. |
107 |
136 |
108 \param number Source number for grouping. |
137 \return The modified number as a QString if successful, otherwise an |
109 \param country Format for number converting. |
138 empty QString. |
110 If the country is not given (country = QLocale::AnyCountry) then it will be requested from QLocale::country. |
139 |
111 |
|
112 \return modified string. |
|
113 */ |
140 */ |
114 QString HbNumberGrouping::formatPhoneNumber( const QString &number, |
141 QString HbNumberGrouping::formatPhoneNumber( const QString &number, |
115 QLocale::Country country ) |
142 QLocale::Country country ) |
116 { |
143 { |
117 if ( number.size() == 0 ) { |
144 if ( number.size() == 0 ) { |
118 return QString(); |
145 return QString(); |
119 } |
146 } |
120 |
147 |
121 if ( country == QLocale::AnyCountry) { |
148 if ( country == QLocale::AnyCountry) { |
122 QLocale locale; |
149 QLocale locale; |
123 country = locale.country(); |
150 country = locale.country(); |
124 } |
151 } |
125 |
152 |
126 return QString(); |
153 return QString(); |
127 } |
154 } |