<?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&amp;,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&amp;,TDesOverflow&amp;,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&amp; 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>