|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-28C7424E-2B32-53F2-8A31-8FB6815B4148" xml:lang="en"><title>How |
|
13 to format currency values</title><shortdesc>Describes how to format currency values for current locale.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-D09EB90D-6A64-46C8-A47D-1D122307AD4D"><title>From 6.1 onward</title> <p>From 6.1, the <xref href="GUID-53299759-C2DD-3ABC-A055-9AFE7C5081C6.dita"><apiname>TLocale</apiname></xref> class |
|
15 provides the <codeph>FormatCurrency()</codeph> functions that can format currency |
|
16 values into a descriptor. The functions can handle both small and large values. |
|
17 They render the currency amount as text, using the current locale's formatting |
|
18 requirements. These include items such as:</p> <ul> |
|
19 <li id="GUID-DC19903D-A39D-52D1-B1F7-06373F96F7CD"><p> the appropriate currency |
|
20 symbol</p> </li> |
|
21 <li id="GUID-518DBCEB-70B0-5E53-AB13-245403BF98C3"><p> whether the currency |
|
22 symbol is placed before or after the currency amount</p> </li> |
|
23 <li id="GUID-6BF3E2BC-1327-52FE-955D-E7D5BAF3CD8B"><p>whether there is space |
|
24 between the currency amount and the currency symbol</p> </li> |
|
25 <li id="GUID-340BC8A9-A189-56A2-9041-D3711041E436"><p>the number of decimal |
|
26 places</p> </li> |
|
27 <li id="GUID-9A7E86A9-6C2A-561A-AED0-BD513D128C54"><p>the way a negative currency |
|
28 value is rendered.</p> </li> |
|
29 </ul> <p>There are four overloaded variants of <codeph>FormatCurrency()</codeph>, |
|
30 two of which are suitable for rendering currency values that fit into a <xref href="GUID-7A2A43EC-6125-3BFE-834B-23C37F7B40D5.dita"><apiname>TInt</apiname></xref> type, |
|
31 and the other two of which are suitable for rendering very large currency |
|
32 values that fit into a <xref href="GUID-AAE85115-A8AA-3F6C-BA8C-69F5A23B0D90.dita"><apiname>TInt64</apiname></xref> type.</p> <p>Both pairs of |
|
33 functions behave in the same way, and the following code fragments will also |
|
34 apply to the <codeph>TInt64</codeph> variants.</p> <p>The first code fragment |
|
35 uses the <codeph>void FormatCurrency(TDes&,TInt);</codeph> variant.</p> <codeblock id="GUID-537D91F4-9F9C-5466-8001-AEB490544E71" xml:space="preserve">... |
|
36 TLocale locale; |
|
37 |
|
38 TInt amount; |
|
39 TBuf<64> buffer; |
|
40 |
|
41 locale.set(); |
|
42 locale.FormatCurrency(buffer,amount); |
|
43 ... |
|
44 </codeblock> <p>On return, the descriptor buffer contains the currency value |
|
45 formatted as text using the currency symbol and formatting appropriate to |
|
46 the current locale. Note, however, that the caller is responsible for ensuring |
|
47 that the descriptor buffer is large enough. Too small a buffer results in |
|
48 a <codeph>USER 11</codeph> panic.</p> <p>The second code fragment uses the <codeph>void |
|
49 FormatCurrency(TDes&,TDesOverflow&,TInt);</codeph> variant.</p> <codeblock id="GUID-1E2BD59A-DD14-5E6A-87FB-E4DA19AA5813" xml:space="preserve"> |
|
50 class TestOverflow : public TDesOverflow |
|
51 { |
|
52 void Overflow(TDes& aBufferThatOverflowed); |
|
53 }; |
|
54 |
|
55 void TestOverflow::Overflow(TDes& aBufferThatOverflowed) |
|
56 { |
|
57 _LIT(KTextOverflow,"Overflowed"); |
|
58 aBufferThatOverflowed = KTextOverflow; |
|
59 } |
|
60 |
|
61 ... |
|
62 TLocale locale; |
|
63 TestOverflow ovfl; |
|
64 |
|
65 TInt amount; |
|
66 HBufC* bufPtr; |
|
67 |
|
68 bufPtr = HBufC::NewL(10); |
|
69 |
|
70 locale.set(); |
|
71 locale.FormatCurrency(*bufPtr,ovfl,amount); |
|
72 ...</codeblock> <p>In this fragment, if the formatted text cannot fit into |
|
73 the buffer, <codeph>*bufPtr</codeph>, then <codeph>TestOverflow::Overflow()</codeph> is |
|
74 called which simply sets the text "Overflowed" into the buffer. In practice, |
|
75 application code would probably perform more sophisticated recovery which |
|
76 might include re-allocating the buffer and re-trying the <codeph>FormatCurrency()</codeph> operation.</p> </section> |
|
77 <section id="GUID-F82759A3-E704-474C-8A4D-3E2FB9F451BD"><title>Before 6.1</title> <p>Before 6.1, the <codeph>FormatCurrency()</codeph> function |
|
78 is not available and the procedure for formatting a currency value needs more |
|
79 code and explicitly uses more of the functionality of the <codeph>TLocale</codeph> class.</p> <p>In |
|
80 the following example code fragments, the formatting is done by a function |
|
81 called <codeph>foo()</codeph>. This function takes a descriptor that, on return, |
|
82 holds the formatted currency value. The function assumes that the descriptor |
|
83 is big enough to hold the formatted text. The example holds the currency value |
|
84 as a <xref href="GUID-2D851BBB-15A1-309A-813D-E397D55A6431.dita"><apiname>TReal</apiname></xref> value.</p> <p><codeph>foo()</codeph> uses the <codeph>AppendNum()</codeph> and <codeph>Append()</codeph> descriptor |
|
85 functions to format and append the currency value and symbol to <codeph>aBuffer</codeph> using |
|
86 an object of class <xref href="GUID-28F1EA9D-9F02-3E8C-A07F-4D65C955860C.dita"><apiname>TRealFormat</apiname></xref> to determine the character |
|
87 representation of the currency value.</p> <p>The code formats the following |
|
88 locale-dependent aspects of currency information: </p> <ul> |
|
89 <li id="GUID-3C344A41-3AA2-57A2-89F2-779D26FB37CE"><p>the number of decimal |
|
90 places</p> </li> |
|
91 <li id="GUID-1862BBE9-D48E-52AB-B8A8-4D0DF4F0C94D"><p>the decimal and thousands |
|
92 separators (<codeph>iPoint</codeph> and <codeph>iTriad</codeph>) </p> </li> |
|
93 <li id="GUID-E44611AA-8BC5-5907-9A71-D1375F68C5B5"><p>whether <keyword>triads</keyword> are |
|
94 allowed or not (<codeph>iTriLen</codeph>)</p> </li> |
|
95 <li id="GUID-A0713C22-602A-5FC2-9505-414DA4F4CFE9"><p>An <codeph>iTriLen</codeph> value |
|
96 of 1 signifies that triads are allowed throughout the currency amount. A value |
|
97 of zero means that no triads are allowed.</p> </li> |
|
98 </ul> <codeblock id="GUID-B557FADA-0BBC-55EC-945D-38B503F173D5" xml:space="preserve">void foo(TDes& aBuffer, TReal aCurrencyAmount) |
|
99 { |
|
100 // get system locale settings |
|
101 TLocale locale; |
|
102 TRealFormat realFormat; |
|
103 realFormat.iType=EFixed; |
|
104 |
|
105 // convert number to the general form "nnn.ddd" where |
|
106 // "n" is the integer and "d" is the decimal portion. |
|
107 // iWidth is the maximum number of characters allowed to represent the number |
|
108 realFormat.iWidth=30; |
|
109 realFormat.iDecimalPlaces=locale.CurrencyDecimalPlaces(); |
|
110 realFormat.iPoint=locale.DecimalSeparator(); |
|
111 realFormat.iTriad=locale.ThousandsSeparator(); |
|
112 realFormat.iTriLen=(locale.CurrencyTriadsAllowed() ? 1 : 0); |
|
113 ...</codeblock> <p>Note the following points:</p> <ul> |
|
114 <li id="GUID-E12C4EB4-F3E7-5262-BA23-EE1B83011624"><p>Use <codeph>CurrencySymbolPosition()</codeph> and <codeph>CurrencySpaceBetween()</codeph> to |
|
115 decide whether the currency symbol should be placed before or after the currency |
|
116 amount and whether or not to insert a space between the symbol and the amount.</p> </li> |
|
117 <li id="GUID-1F1A8FAD-E5AB-5570-B72E-9FECF0716B0A"><p>Use <codeph>CurrencyNegativeInBrackets()</codeph> to |
|
118 decide whether or not negative currency amounts should be enclosed in brackets. |
|
119 If this is the case, and the value is negative, an open bracket is appended |
|
120 and any minus sign is removed by appending the currency value to the buffer |
|
121 as a negative value.</p> </li> |
|
122 <li id="GUID-ABEABD32-AF6C-5265-BB39-D7BB075D2190"><p>Use <codeph>CurrencySpaceBetween()</codeph> to |
|
123 decide whether or not to insert a space between the currency symbol and the |
|
124 currency value.</p> </li> |
|
125 </ul> <codeblock id="GUID-87F2B73E-7E6C-5423-A08A-7C66443D11F1" xml:space="preserve">... |
|
126 _LIT(KTxtOpenBracket,"("); |
|
127 _LIT(KTxtCloseBracket,")"); |
|
128 _LIT(KTxtSpace," "); |
|
129 TCurrencySymbol symbol; |
|
130 |
|
131 // Get system wide currency symbol setting |
|
132 symbol.Set(); |
|
133 |
|
134 // Append an open bracket, if the amount is negative and the locale demands it. |
|
135 if ((aCurrencyAmount<0) && (locale.CurrencyNegativeInBrackets())) |
|
136 { |
|
137 aBuffer.Append(KTxtOpenBracket); |
|
138 } |
|
139 |
|
140 // Position the currency symbol before the currency value, and insert space between the |
|
141 // symbol and the amount if the locale demands them. |
|
142 if (locale.CurrencySymbolPosition() == ELocaleBefore) |
|
143 { |
|
144 aBuffer.Append(symbol); |
|
145 if (locale.CurrencySpaceBetween()) |
|
146 { |
|
147 aBuffer.Append(KTxtSpace); |
|
148 } |
|
149 } |
|
150 |
|
151 // Append negative currency value and remove the sign if the locale demands |
|
152 // negative values in brackets |
|
153 if ((locale.CurrencyNegativeInBrackets()) && (aCurrencyAmount<0)) |
|
154 { |
|
155 aBuffer.AppendNum(-aCurrencyAmount,realFormat); |
|
156 } |
|
157 else |
|
158 { |
|
159 aBuffer.AppendNum(aCurrencyAmount,realFormat); |
|
160 } |
|
161 |
|
162 // Position the currency symbol after the currency value, and insert space between the |
|
163 // amount and the symbol if the locale demands them. |
|
164 if (locale.CurrencySymbolPosition() == ELocaleAfter) |
|
165 { |
|
166 if (locale.CurrencySpaceBetween()) |
|
167 { |
|
168 aBuffer.Append(KTxtSpace); |
|
169 } |
|
170 aBuffer.Append(symbol); |
|
171 } |
|
172 |
|
173 // Finally, append the closing bracket, if the value is negative and |
|
174 // the locale demands brackets around negative values. |
|
175 if ((aCurrencyAmount<0) && (locale.CurrencyNegativeInBrackets())) |
|
176 { |
|
177 aBuffer.Append(KTxtCloseBracket); |
|
178 } |
|
179 }</codeblock> <p>Note that the currency symbol cannot be set using the <codeph>TLocale</codeph> class. |
|
180 Use <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-1CBBEEF4-0E5A-33AB-833F-6AF14BA57793"><apiname>User::SetCurrencySymbol()</apiname></xref> to do this.</p> </section> |
|
181 </conbody></concept> |