Encapsulates the CURRENCY data type of OLE automation.

class COleCurrency

COleCurrency does not have a base class.

CURRENCY is implemented as an 8-byte, two's-complement integer value scaled by 10,000. This gives a fixed-point number with 15 digits to the left of the decimal point and 4 digits to the right. The CURRENCY data type is extremely useful for calculations involving money, or for any fixed-point calculation where accuracy is important. It is one of the possible types for the VARIANT data type of OLE automation.

COleCurrency also implements some basic arithmetic operations for this fixed-point type. The supported operations have been selected to control the rounding errors which occur during fixed-point calculations.

COleCurrency

Header: afxdisp.h

Constructs a COleCurrency object.

COleCurrency();
COleCurrency(CURRENCY cySrc);
COleCurrency(const COleCurrency& curSrc);
COleCurrency(const VARIANT& varSrc);

COleCurrency(
    long nUnits,
    long nFractionalUnits);

cySrc
A CURRENCY value to be copied into the new COleCurrency object.

curSrc
An existing COleCurrency object to be copied into the new COleCurrency object.

varSrc
An existing VARIANT data structure (possibly a COleVariant object) to be converted to a currency value (VT_CY) and copied into the new COleCurrency object.

nUnits, nFractionalUnits Indicate the units and fractional part (in 1/10,000's) of the value to be copied into the new COleCurrency object.

All of these constructors create new COleCurrency objects initialized to the specified value. A brief description of each of these constructors follows. Unless otherwise noted, the status of the new COleCurrency item is set to valid.

• COleCurrency() Constructs a COleCurrency object initialized to 0 (zero).

• COleCurrency(cySrc) Constructs a COleCurrency object from a CURRENCY value.

• COleCurrency(curSrc) Constructs a COleCurrency object from an existing COleCurrency object. The new object has the same status as the source object.

• COleCurrency(varSrc) Constructs a COleCurrency object. Attempts to convert a VARIANT structure or COleVariant object to a currency (VT_CY) value. If this conversion is successful, the converted value is copied into the new COleCurrency object. If it is not, the value of the COleCurrency object is set to zero (0) and its status to invalid.

• COleCurrency(nUnits, nFractionalUnits) Constructs a COleCurrency object from the specified numerical components. If the absolute value of the fractional part is greater than 10,000, the appropriate adjustment is made to the units. Note that the units and fractional part are specified by signed long values.

For more information, see the CURRENCY and VARIANT entries in the Windows SDK.

The following examples show the effects of the zero-parameter and two-parameter constructors:

[!code-cppNVC_MFCOleContainer#10]

Call this member function to create a formatted representation of the currency value.

CString Format(DWORD  dwFlags = 0, LCID  lcid = LANG_USER_DEFAULT) const;

dwFlags
Indicates flags for locale settings. Only the following flag is relevant to currency:

• LOCALE_NOUSEROVERRIDE Use the system default locale settings, rather than custom user settings.

lcid
Indicates locale ID to use for the conversion.

A CString that contains the formatted currency value.

It formats the value using the local language specifications (locale IDs). A currency symbol is not included in the value returned. If the status of this COleCurrency object is null, the return value is an empty string. If the status is invalid, the return string is specified by the string resource IDS_INVALID_CURRENCY.

[!code-cppNVC_MFCOleContainer#11]

Call this member function to get the status (validity) of a given COleCurrency object.

CurrencyStatus GetStatus() const;

Returns the status of this COleCurrency value.

The return value is defined by the CurrencyStatus enumerated type that is defined within the COleCurrency class.

enum CurrencyStatus {
    valid = 0,
    invalid = 1,
    null = 2
    };

For a brief description of these status values, see the following list:

• COleCurrency::valid Indicates that this COleCurrency object is valid.

• COleCurrency::invalid Indicates that this COleCurrency object is invalid; that is, its value may be incorrect.

• COleCurrency::null Indicates that this COleCurrency object is null, that is, that no value has been supplied for this object. (This is "null" in the database sense of "having no value," as opposed to the C++ NULL.)

The status of a COleCurrency object is invalid in the following cases:

• If its value is set from a VARIANT or COleVariant value that could not be converted to a currency value.

• If this object has experienced an overflow or underflow during an arithmetic assignment operation, for example += or *=.

• If an invalid value was assigned to this object.

• If the status of this object was explicitly set to invalid using SetStatus.

For more information on operations that may set the status to invalid, see the following member functions:

• COleCurrency

• operator =

• operator + -

• operator += and -=

• operator * /

• operator *= and /=

[!code-cppNVC_MFCOleContainer#12]

The underlying CURRENCY structure for this COleCurrency object.

For more information, see the CURRENCY entry in the Windows SDK.

The type of this data member is the enumerated type CurrencyStatus, which is defined within the COleCurrency class.

enum CurrencyStatus{
    valid = 0,
    invalid = 1,
    null = 2,
};

For a brief description of these status values, see the following list:

• COleCurrency::valid Indicates that this COleCurrency object is valid.

• COleCurrency::invalid Indicates that this COleCurrency object is invalid; that is, its value may be incorrect.

• COleCurrency::null Indicates that this COleCurrency object is null, that is, that no value has been supplied for this object. (This is "null" in the database sense of "having no value," as opposed to the C++ NULL.)

The status of a COleCurrency object is invalid in the following cases:

• If its value is set from a VARIANT or COleVariant value that could not be converted to a currency value.

• If this object has experienced an overflow or underflow during an arithmetic assignment operation, for example += or *=.

• If an invalid value was assigned to this object.

• If the status of this object was explicitly set to invalid using SetStatus.

For more information on operations that may set the status to invalid, see the following member functions:

• COleCurrency

• operator =

• operator +, -

• operator +=, -=

• operator */

• operator *=, /=

These overloaded assignment operators copy the source currency value into this COleCurrency object.

const COleCurrency& operator=(CURRENCY cySrc);
const COleCurrency& operator=(const COleCurrency& curSrc);
const COleCurrency& operator=(const VARIANT& varSrc);

A brief description of each operator follows:

• operator =( cySrc ) The CURRENCY value is copied into the COleCurrency object and its status is set to valid.

• operator =( curSrc ) The value and status of the operand, an existing COleCurrency object are copied into this COleCurrency object.

• operator =( varSrc ) If the conversion of the VARIANT value (or COleVariant object) to a currency ( VT_CY) is successful, the converted value is copied into this COleCurrency object and its status is set to valid. If the conversion is not successful, the value of the COleCurrency object is set to 0 and its status to invalid.

For more information, see the CURRENCY and VARIANT entries in the Windows SDK.

[!code-cppNVC_MFCOleContainer#15]

These operators allow you to add and subtract two COleCurrency values to and from each other and to change the sign of a COleCurrency value.

COleCurrency operator+(const COleCurrency& cur) const;
COleCurrency operator-(const COleCurrency& cur) const;
COleCurrency operator-() const;

If either of the operands is null, the status of the resulting COleCurrency value is null.

If the arithmetic operation overflows, the resulting COleCurrency value is invalid.

If the operand is invalid and the other is not null, the status of the resulting COleCurrency value is invalid.

For more information on the valid, invalid, and null status values, see the m_status member variable.

[!code-cppNVC_MFCOleContainer#16]

Allow you to add and subtract a COleCurrency value to and from this COleCurrency object.

const COleCurrency& operator+=(const COleCurrency& cur);
const COleCurrency& operator-=(const COleCurrency& cur);

If either of the operands is null, the status of this COleCurrency object is set to null.

If the arithmetic operation overflows, the status of this COleCurrency object is set to invalid.

If either of the operands is invalid and the other is not null, the status of this COleCurrency object is set to invalid.

For more information on the valid, invalid, and null status values, see the m_status member variable.

[!code-cppNVC_MFCOleContainer#17]

Allow you to scale a COleCurrency value by an integral value.

COleCurrency operator*(long nOperand) const;
COleCurrency operator/(long nOperand) const;

If the COleCurrency operand is null, the status of the resulting COleCurrency value is null.

If the arithmetic operation overflows or underflows, the status of the resulting COleCurrency value is invalid.

If the COleCurrency operand is invalid, the status of the resulting COleCurrency value is invalid.

For more information on the valid, invalid, and null status values, see the m_status member variable.

[!code-cppNVC_MFCOleContainer#18]

Allow you to scale this COleCurrency value by an integral value.

const COleCurrency& operator*=(long nOperand);
const COleCurrency& operator/=(long nOperand);

If the COleCurrency operand is null, the status of this COleCurrency object is set to null.

If the arithmetic operation overflows, the status of this COleCurrency object is set to invalid.

If the COleCurrency operand is invalid, the status of this COleCurrency object is set to invalid.

For more information on the valid, invalid, and null status values, see the m_status member variable.

[!code-cppNVC_MFCOleContainer#19]

Supports diagnostic dumping and storing to an archive.

friend CDumpContext& operator<<(
    CDumpContext& dc,
    COleCurrency curSrc);

friend CArchive& operator<<(
    CArchive& ar,
    COleCurrency curSrc);

friend CArchive& operator>>(
    CArchive& ar,
    COleCurrency& curSrc);

The extraction ( >>) operator supports loading from an archive.

Returns a CURRENCY structure whose value is copied from this COleCurrency object.

operator CURRENCY() const;

Call this member function to parse a string to read a currency value.

BOOL ParseCurrency(
    LPCTSTR lpszCurrency,
    DWORD dwFlags = 0,
    LCID lcid = LANG_USER_DEFAULT);

throw(CMemoryException*);
throw(COleException*);

lpszCurrency
A pointer to the null-terminated string which is to be parsed.

dwFlags
Indicates flags for locale settings, possibly the following flag:

• LOCALE_NOUSEROVERRIDE Use the system default locale settings, rather than custom user settings.

lcid
Indicates locale ID to use for the conversion.

Nonzero if the string was successfully converted to a currency value, otherwise 0.

It uses local language specifications (locale IDs) for the meaning of nonnumeric characters in the source string.

For a discussion of locale ID values, see Supporting Multiple Languages.

If the string was successfully converted to a currency value, the value of this COleCurrency object is set to that value and its status to valid.

If the string could not be converted to a currency value or if there was a numerical overflow, the status of this COleCurrency object is invalid.

If the string conversion failed due to memory allocation errors, this function throws a CMemoryException. In any other error state, this function throws a COleException.

[!code-cppNVC_MFCOleContainer#13]

Compare two currency values and return nonzero if the condition is true; otherwise 0.

BOOL operator==(const COleCurrency& cur) const;
BOOL operator!=(const COleCurrency& cur) const;
BOOL operator<(const COleCurrency& cur) const;
BOOL operator>(const COleCurrency& cur) const;
BOOL operator<=(const COleCurrency& cur) const;
BOOL operator>=(const COleCurrency& cur) const;

[!code-cppNVC_MFCOleContainer#20]

Call this member function to set the units and fractional part of this COleCurrency object.

void SetCurrency(
    long nUnits,
    long nFractionalUnits);

nUnits, nFractionalUnits Indicate the units and fractional part (in 1/10,000's) of the value to be copied into this COleCurrency object.

If the absolute value of the fractional part is greater than 10,000, the appropriate adjustment is made to the units, as shown in the third of the following examples.

Note that the units and fractional part are specified by signed long values. The fourth of the following examples shows what happens when the parameters have different signs.

[!code-cppNVC_MFCOleContainer#14]

Call this member function to set the status (validity) of this COleCurrency object.

void SetStatus(CurrencyStatus  status  );

status
The new status for this COleCurrency object.

The status parameter value is defined by the CurrencyStatus enumerated type, which is defined within the COleCurrency class.

enum CurrencyStatus {
    valid = 0,
    invalid = 1,
    null = 2
    };

For a brief description of these status values, see the following list:

• COleCurrency::valid Indicates that this COleCurrency object is valid.

• COleCurrency::invalid Indicates that this COleCurrency object is invalid; that is, its value may be incorrect.

• COleCurrency::null Indicates that this COleCurrency object is null, that is, that no value has been supplied for this object. (This is "null" in the database sense of "having no value," as opposed to the C++ NULL.)

Hierarchy Chart
COleVariant Class