--- a/Symbian3/PDK/Source/GUID-28C7424E-2B32-53F2-8A31-8FB6815B4148.dita Tue Jul 20 12:00:49 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-28C7424E-2B32-53F2-8A31-8FB6815B4148.dita Fri Aug 13 16:47:46 2010 +0100
@@ -1,181 +1,181 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
-<!-- This component and the accompanying materials are made available under the terms of the License
-"Eclipse Public License v1.0" which accompanies this distribution,
-and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
-<!-- Initial Contributors:
- Nokia Corporation - initial contribution.
-Contributors:
--->
-<!DOCTYPE concept
- PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="GUID-28C7424E-2B32-53F2-8A31-8FB6815B4148" xml:lang="en"><title>How
-to format currency values</title><shortdesc>Describes how to format currency values for current locale.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
-<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
-provides the <codeph>FormatCurrency()</codeph> functions that can format currency
-values into a descriptor. The functions can handle both small and large values.
-They render the currency amount as text, using the current locale's formatting
-requirements. These include items such as:</p> <ul>
-<li id="GUID-DC19903D-A39D-52D1-B1F7-06373F96F7CD"><p> the appropriate currency
-symbol</p> </li>
-<li id="GUID-518DBCEB-70B0-5E53-AB13-245403BF98C3"><p> whether the currency
-symbol is placed before or after the currency amount</p> </li>
-<li id="GUID-6BF3E2BC-1327-52FE-955D-E7D5BAF3CD8B"><p>whether there is space
-between the currency amount and the currency symbol</p> </li>
-<li id="GUID-340BC8A9-A189-56A2-9041-D3711041E436"><p>the number of decimal
-places</p> </li>
-<li id="GUID-9A7E86A9-6C2A-561A-AED0-BD513D128C54"><p>the way a negative currency
-value is rendered.</p> </li>
-</ul> <p>There are four overloaded variants of <codeph>FormatCurrency()</codeph>,
-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,
-and the other two of which are suitable for rendering very large currency
-values that fit into a <xref href="GUID-AAE85115-A8AA-3F6C-BA8C-69F5A23B0D90.dita"><apiname>TInt64</apiname></xref> type.</p> <p>Both pairs of
-functions behave in the same way, and the following code fragments will also
-apply to the <codeph>TInt64</codeph> variants.</p> <p>The first code fragment
-uses the <codeph>void FormatCurrency(TDes&,TInt);</codeph> variant.</p> <codeblock id="GUID-537D91F4-9F9C-5466-8001-AEB490544E71" xml:space="preserve">...
-TLocale locale;
-
-TInt amount;
-TBuf<64> buffer;
-
-locale.set();
-locale.FormatCurrency(buffer,amount);
-...
-</codeblock> <p>On return, the descriptor buffer contains the currency value
-formatted as text using the currency symbol and formatting appropriate to
-the current locale. Note, however, that the caller is responsible for ensuring
-that the descriptor buffer is large enough. Too small a buffer results in
-a <codeph>USER 11</codeph> panic.</p> <p>The second code fragment uses the <codeph>void
-FormatCurrency(TDes&,TDesOverflow&,TInt);</codeph> variant.</p> <codeblock id="GUID-1E2BD59A-DD14-5E6A-87FB-E4DA19AA5813" xml:space="preserve">
-class TestOverflow : public TDesOverflow
- {
- void Overflow(TDes& aBufferThatOverflowed);
- };
-
-void TestOverflow::Overflow(TDes& aBufferThatOverflowed)
- {
- _LIT(KTextOverflow,"Overflowed");
- aBufferThatOverflowed = KTextOverflow;
- }
-
-...
-TLocale locale;
-TestOverflow ovfl;
-
-TInt amount;
-HBufC* bufPtr;
-
-bufPtr = HBufC::NewL(10);
-
-locale.set();
-locale.FormatCurrency(*bufPtr,ovfl,amount);
-...</codeblock> <p>In this fragment, if the formatted text cannot fit into
-the buffer, <codeph>*bufPtr</codeph>, then <codeph>TestOverflow::Overflow()</codeph> is
-called which simply sets the text "Overflowed" into the buffer. In practice,
-application code would probably perform more sophisticated recovery which
-might include re-allocating the buffer and re-trying the <codeph>FormatCurrency()</codeph> operation.</p> </section>
-<section id="GUID-F82759A3-E704-474C-8A4D-3E2FB9F451BD"><title>Before 6.1</title> <p>Before 6.1, the <codeph>FormatCurrency()</codeph> function
-is not available and the procedure for formatting a currency value needs more
-code and explicitly uses more of the functionality of the <codeph>TLocale</codeph> class.</p> <p>In
-the following example code fragments, the formatting is done by a function
-called <codeph>foo()</codeph>. This function takes a descriptor that, on return,
-holds the formatted currency value. The function assumes that the descriptor
-is big enough to hold the formatted text. The example holds the currency value
-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
-functions to format and append the currency value and symbol to <codeph>aBuffer</codeph> using
-an object of class <xref href="GUID-28F1EA9D-9F02-3E8C-A07F-4D65C955860C.dita"><apiname>TRealFormat</apiname></xref> to determine the character
-representation of the currency value.</p> <p>The code formats the following
-locale-dependent aspects of currency information: </p> <ul>
-<li id="GUID-3C344A41-3AA2-57A2-89F2-779D26FB37CE"><p>the number of decimal
-places</p> </li>
-<li id="GUID-1862BBE9-D48E-52AB-B8A8-4D0DF4F0C94D"><p>the decimal and thousands
-separators (<codeph>iPoint</codeph> and <codeph>iTriad</codeph>) </p> </li>
-<li id="GUID-E44611AA-8BC5-5907-9A71-D1375F68C5B5"><p>whether <keyword>triads</keyword> are
-allowed or not (<codeph>iTriLen</codeph>)</p> </li>
-<li id="GUID-A0713C22-602A-5FC2-9505-414DA4F4CFE9"><p>An <codeph>iTriLen</codeph> value
-of 1 signifies that triads are allowed throughout the currency amount. A value
-of zero means that no triads are allowed.</p> </li>
-</ul> <codeblock id="GUID-B557FADA-0BBC-55EC-945D-38B503F173D5" xml:space="preserve">void foo(TDes& aBuffer, TReal aCurrencyAmount)
- {
- // get system locale settings
- TLocale locale;
- TRealFormat realFormat;
- realFormat.iType=EFixed;
-
- // convert number to the general form "nnn.ddd" where
- // "n" is the integer and "d" is the decimal portion.
- // iWidth is the maximum number of characters allowed to represent the number
- realFormat.iWidth=30;
- realFormat.iDecimalPlaces=locale.CurrencyDecimalPlaces();
- realFormat.iPoint=locale.DecimalSeparator();
- realFormat.iTriad=locale.ThousandsSeparator();
- realFormat.iTriLen=(locale.CurrencyTriadsAllowed() ? 1 : 0);
- ...</codeblock> <p>Note the following points:</p> <ul>
-<li id="GUID-E12C4EB4-F3E7-5262-BA23-EE1B83011624"><p>Use <codeph>CurrencySymbolPosition()</codeph> and <codeph>CurrencySpaceBetween()</codeph> to
-decide whether the currency symbol should be placed before or after the currency
-amount and whether or not to insert a space between the symbol and the amount.</p> </li>
-<li id="GUID-1F1A8FAD-E5AB-5570-B72E-9FECF0716B0A"><p>Use <codeph>CurrencyNegativeInBrackets()</codeph> to
-decide whether or not negative currency amounts should be enclosed in brackets.
-If this is the case, and the value is negative, an open bracket is appended
-and any minus sign is removed by appending the currency value to the buffer
-as a negative value.</p> </li>
-<li id="GUID-ABEABD32-AF6C-5265-BB39-D7BB075D2190"><p>Use <codeph>CurrencySpaceBetween()</codeph> to
-decide whether or not to insert a space between the currency symbol and the
-currency value.</p> </li>
-</ul> <codeblock id="GUID-87F2B73E-7E6C-5423-A08A-7C66443D11F1" xml:space="preserve">...
-_LIT(KTxtOpenBracket,"(");
-_LIT(KTxtCloseBracket,")");
-_LIT(KTxtSpace," ");
-TCurrencySymbol symbol;
-
- // Get system wide currency symbol setting
-symbol.Set();
-
- // Append an open bracket, if the amount is negative and the locale demands it.
-if ((aCurrencyAmount<0) && (locale.CurrencyNegativeInBrackets()))
- {
- aBuffer.Append(KTxtOpenBracket);
- }
-
- // Position the currency symbol before the currency value, and insert space between the
- // symbol and the amount if the locale demands them.
-if (locale.CurrencySymbolPosition() == ELocaleBefore)
- {
- aBuffer.Append(symbol);
- if (locale.CurrencySpaceBetween())
- {
- aBuffer.Append(KTxtSpace);
- }
- }
-
- // Append negative currency value and remove the sign if the locale demands
- // negative values in brackets
-if ((locale.CurrencyNegativeInBrackets()) && (aCurrencyAmount<0))
- {
- aBuffer.AppendNum(-aCurrencyAmount,realFormat);
- }
-else
- {
- aBuffer.AppendNum(aCurrencyAmount,realFormat);
- }
-
- // Position the currency symbol after the currency value, and insert space between the
- // amount and the symbol if the locale demands them.
-if (locale.CurrencySymbolPosition() == ELocaleAfter)
- {
- if (locale.CurrencySpaceBetween())
- {
- aBuffer.Append(KTxtSpace);
- }
- aBuffer.Append(symbol);
- }
-
- // Finally, append the closing bracket, if the value is negative and
- // the locale demands brackets around negative values.
-if ((aCurrencyAmount<0) && (locale.CurrencyNegativeInBrackets()))
- {
- aBuffer.Append(KTxtCloseBracket);
- }
-}</codeblock> <p>Note that the currency symbol cannot be set using the <codeph>TLocale</codeph> class.
-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>
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License
+"Eclipse Public License v1.0" which accompanies this distribution,
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+ Nokia Corporation - initial contribution.
+Contributors:
+-->
+<!DOCTYPE concept
+ PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-28C7424E-2B32-53F2-8A31-8FB6815B4148" xml:lang="en"><title>How
+to format currency values</title><shortdesc>Describes how to format currency values for current locale.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<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
+provides the <codeph>FormatCurrency()</codeph> functions that can format currency
+values into a descriptor. The functions can handle both small and large values.
+They render the currency amount as text, using the current locale's formatting
+requirements. These include items such as:</p> <ul>
+<li id="GUID-DC19903D-A39D-52D1-B1F7-06373F96F7CD"><p> the appropriate currency
+symbol</p> </li>
+<li id="GUID-518DBCEB-70B0-5E53-AB13-245403BF98C3"><p> whether the currency
+symbol is placed before or after the currency amount</p> </li>
+<li id="GUID-6BF3E2BC-1327-52FE-955D-E7D5BAF3CD8B"><p>whether there is space
+between the currency amount and the currency symbol</p> </li>
+<li id="GUID-340BC8A9-A189-56A2-9041-D3711041E436"><p>the number of decimal
+places</p> </li>
+<li id="GUID-9A7E86A9-6C2A-561A-AED0-BD513D128C54"><p>the way a negative currency
+value is rendered.</p> </li>
+</ul> <p>There are four overloaded variants of <codeph>FormatCurrency()</codeph>,
+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,
+and the other two of which are suitable for rendering very large currency
+values that fit into a <xref href="GUID-AAE85115-A8AA-3F6C-BA8C-69F5A23B0D90.dita"><apiname>TInt64</apiname></xref> type.</p> <p>Both pairs of
+functions behave in the same way, and the following code fragments will also
+apply to the <codeph>TInt64</codeph> variants.</p> <p>The first code fragment
+uses the <codeph>void FormatCurrency(TDes&,TInt);</codeph> variant.</p> <codeblock id="GUID-537D91F4-9F9C-5466-8001-AEB490544E71" xml:space="preserve">...
+TLocale locale;
+
+TInt amount;
+TBuf<64> buffer;
+
+locale.set();
+locale.FormatCurrency(buffer,amount);
+...
+</codeblock> <p>On return, the descriptor buffer contains the currency value
+formatted as text using the currency symbol and formatting appropriate to
+the current locale. Note, however, that the caller is responsible for ensuring
+that the descriptor buffer is large enough. Too small a buffer results in
+a <codeph>USER 11</codeph> panic.</p> <p>The second code fragment uses the <codeph>void
+FormatCurrency(TDes&,TDesOverflow&,TInt);</codeph> variant.</p> <codeblock id="GUID-1E2BD59A-DD14-5E6A-87FB-E4DA19AA5813" xml:space="preserve">
+class TestOverflow : public TDesOverflow
+ {
+ void Overflow(TDes& aBufferThatOverflowed);
+ };
+
+void TestOverflow::Overflow(TDes& aBufferThatOverflowed)
+ {
+ _LIT(KTextOverflow,"Overflowed");
+ aBufferThatOverflowed = KTextOverflow;
+ }
+
+...
+TLocale locale;
+TestOverflow ovfl;
+
+TInt amount;
+HBufC* bufPtr;
+
+bufPtr = HBufC::NewL(10);
+
+locale.set();
+locale.FormatCurrency(*bufPtr,ovfl,amount);
+...</codeblock> <p>In this fragment, if the formatted text cannot fit into
+the buffer, <codeph>*bufPtr</codeph>, then <codeph>TestOverflow::Overflow()</codeph> is
+called which simply sets the text "Overflowed" into the buffer. In practice,
+application code would probably perform more sophisticated recovery which
+might include re-allocating the buffer and re-trying the <codeph>FormatCurrency()</codeph> operation.</p> </section>
+<section id="GUID-F82759A3-E704-474C-8A4D-3E2FB9F451BD"><title>Before 6.1</title> <p>Before 6.1, the <codeph>FormatCurrency()</codeph> function
+is not available and the procedure for formatting a currency value needs more
+code and explicitly uses more of the functionality of the <codeph>TLocale</codeph> class.</p> <p>In
+the following example code fragments, the formatting is done by a function
+called <codeph>foo()</codeph>. This function takes a descriptor that, on return,
+holds the formatted currency value. The function assumes that the descriptor
+is big enough to hold the formatted text. The example holds the currency value
+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
+functions to format and append the currency value and symbol to <codeph>aBuffer</codeph> using
+an object of class <xref href="GUID-28F1EA9D-9F02-3E8C-A07F-4D65C955860C.dita"><apiname>TRealFormat</apiname></xref> to determine the character
+representation of the currency value.</p> <p>The code formats the following
+locale-dependent aspects of currency information: </p> <ul>
+<li id="GUID-3C344A41-3AA2-57A2-89F2-779D26FB37CE"><p>the number of decimal
+places</p> </li>
+<li id="GUID-1862BBE9-D48E-52AB-B8A8-4D0DF4F0C94D"><p>the decimal and thousands
+separators (<codeph>iPoint</codeph> and <codeph>iTriad</codeph>) </p> </li>
+<li id="GUID-E44611AA-8BC5-5907-9A71-D1375F68C5B5"><p>whether <keyword>triads</keyword> are
+allowed or not (<codeph>iTriLen</codeph>)</p> </li>
+<li id="GUID-A0713C22-602A-5FC2-9505-414DA4F4CFE9"><p>An <codeph>iTriLen</codeph> value
+of 1 signifies that triads are allowed throughout the currency amount. A value
+of zero means that no triads are allowed.</p> </li>
+</ul> <codeblock id="GUID-B557FADA-0BBC-55EC-945D-38B503F173D5" xml:space="preserve">void foo(TDes& aBuffer, TReal aCurrencyAmount)
+ {
+ // get system locale settings
+ TLocale locale;
+ TRealFormat realFormat;
+ realFormat.iType=EFixed;
+
+ // convert number to the general form "nnn.ddd" where
+ // "n" is the integer and "d" is the decimal portion.
+ // iWidth is the maximum number of characters allowed to represent the number
+ realFormat.iWidth=30;
+ realFormat.iDecimalPlaces=locale.CurrencyDecimalPlaces();
+ realFormat.iPoint=locale.DecimalSeparator();
+ realFormat.iTriad=locale.ThousandsSeparator();
+ realFormat.iTriLen=(locale.CurrencyTriadsAllowed() ? 1 : 0);
+ ...</codeblock> <p>Note the following points:</p> <ul>
+<li id="GUID-E12C4EB4-F3E7-5262-BA23-EE1B83011624"><p>Use <codeph>CurrencySymbolPosition()</codeph> and <codeph>CurrencySpaceBetween()</codeph> to
+decide whether the currency symbol should be placed before or after the currency
+amount and whether or not to insert a space between the symbol and the amount.</p> </li>
+<li id="GUID-1F1A8FAD-E5AB-5570-B72E-9FECF0716B0A"><p>Use <codeph>CurrencyNegativeInBrackets()</codeph> to
+decide whether or not negative currency amounts should be enclosed in brackets.
+If this is the case, and the value is negative, an open bracket is appended
+and any minus sign is removed by appending the currency value to the buffer
+as a negative value.</p> </li>
+<li id="GUID-ABEABD32-AF6C-5265-BB39-D7BB075D2190"><p>Use <codeph>CurrencySpaceBetween()</codeph> to
+decide whether or not to insert a space between the currency symbol and the
+currency value.</p> </li>
+</ul> <codeblock id="GUID-87F2B73E-7E6C-5423-A08A-7C66443D11F1" xml:space="preserve">...
+_LIT(KTxtOpenBracket,"(");
+_LIT(KTxtCloseBracket,")");
+_LIT(KTxtSpace," ");
+TCurrencySymbol symbol;
+
+ // Get system wide currency symbol setting
+symbol.Set();
+
+ // Append an open bracket, if the amount is negative and the locale demands it.
+if ((aCurrencyAmount<0) && (locale.CurrencyNegativeInBrackets()))
+ {
+ aBuffer.Append(KTxtOpenBracket);
+ }
+
+ // Position the currency symbol before the currency value, and insert space between the
+ // symbol and the amount if the locale demands them.
+if (locale.CurrencySymbolPosition() == ELocaleBefore)
+ {
+ aBuffer.Append(symbol);
+ if (locale.CurrencySpaceBetween())
+ {
+ aBuffer.Append(KTxtSpace);
+ }
+ }
+
+ // Append negative currency value and remove the sign if the locale demands
+ // negative values in brackets
+if ((locale.CurrencyNegativeInBrackets()) && (aCurrencyAmount<0))
+ {
+ aBuffer.AppendNum(-aCurrencyAmount,realFormat);
+ }
+else
+ {
+ aBuffer.AppendNum(aCurrencyAmount,realFormat);
+ }
+
+ // Position the currency symbol after the currency value, and insert space between the
+ // amount and the symbol if the locale demands them.
+if (locale.CurrencySymbolPosition() == ELocaleAfter)
+ {
+ if (locale.CurrencySpaceBetween())
+ {
+ aBuffer.Append(KTxtSpace);
+ }
+ aBuffer.Append(symbol);
+ }
+
+ // Finally, append the closing bracket, if the value is negative and
+ // the locale demands brackets around negative values.
+if ((aCurrencyAmount<0) && (locale.CurrencyNegativeInBrackets()))
+ {
+ aBuffer.Append(KTxtCloseBracket);
+ }
+}</codeblock> <p>Note that the currency symbol cannot be set using the <codeph>TLocale</codeph> class.
+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>
</conbody></concept>
\ No newline at end of file