ATL 7.0 introduces several new conversion classes and macros, providing significant improvements over the existing macros.

The names of the new string conversion classes and macros take the form:

CSourceType2[C]DestinationType[EX]

where:

• SourceType and DestinationType are described in the table below.

• [C] is present when the destination type must be constant.

• [EX] is present when the initial size of the buffer must be specified as a template argument.

  SourceType/DestinationType	Description
  A	ANSI character string.
  W	Unicode character string.
  T	Generic character string (equivalent to W when _UNICODE is defined, equivalent to A otherwise).
  OLE	OLE character string (equivalent to W).

For example, to convert from a Unicode string to a generic string without changing the converted string, use CW2CT.

If it is known that the converted string is unlikely to be more than 64 characters, the EX version, such as CW2CTEX<64>, can be used to save space on the stack.

Note:
The recommended way of converting to and from BSTR strings is to use the CComBSTR class. To convert to a BSTR, pass the existing string to the constructor of CComBSTR. To convert from a BSTR, use COLE2[C]DestinationType[EX], such as COLE2T.

The new conversion classes which require a buffer (CA2AEX, CA2WEX, CW2AEX, and CW2WEX) use a fixed-size static buffer to store the result of the conversion. If the result is too large to fit into the static buffer, the class allocates memory using malloc, freeing the memory when the object goes out of scope. This ensures that, unlike the older text conversion macros, these classes are safe to use in loops and won't overflow the stack.

The conversion macros introduced in ATL 7.0 are optimized to be aware of input NULL strings. These macros will return NULL if the input parameter is NULL without allocating any memory.

By default, the ATL conversion classes and macros will use the current thread's ANSI code page for the conversion. If you want to override that behavior for a specific conversion using macros based on the classes CA2WEX or CW2AEX, specify the code page as the second parameter to the constructor for the class.

Security Note:
Check the length of the strings before passing them to these macros to avoid potential buffer overrun problems. Stack overflows are exceptions that could also be caught with try/except.

There are several important differences between the older string conversion macros and the new string conversion classes:

Code

//Example 1
// Convert LPCWSTR to LPCSTR.
void ExampleFunction1(LPCWSTR pszW)
{
   // Create an instance of CW2A, called pszA,
   // and initialize it with pszW.
   CW2A pszA(pszW);
   // pszA works like an LPCSTR, and can be used thus:
   ExampleFunctionA(pszA);  
   // Note: pszA will become invalid when it goes out of scope.
}

// Example 2
// Use a temporary instance of CW2A.
void ExampleFunction2(LPCWSTR pszW)
{
   // Create a temporary instance of CW2A,
   // and initialize it with pszW.
   ExampleFunctionA(CW2A(pszW));
   // Note: the temporary instance becomes invalid 
   // after the execution of the statement above.
}

// Example 3
// Incorrect use of conversion macros.
void ExampleFunction3(LPCWSTR pszW)
{
   // Create a temporary instance of CW2A,
   // save a pointer to it and then delete
   // the temportary instance.
   LPCSTR pszA = CW2A(pszW);
   // The pszA in the following line is an invalid pointer,
   // as the instance of CW2A has gone out of scope.
   ExampleFunctionA(pszA);
}

A Warning Regarding Temporary Class Instances

LPCTSTR szr = CA2T(szReplaceFile);

LPCTSTR szr = A2T(szReplaceFile);   

LPCTSTR szr = CA2T(szReplaceFile);   

LPCTSTR szr;
{
   CA2T temp(szReplaceFile);
   szr = temp.operator LPTSTR();
}   

CA2T szr(szReplaceFile);   

Advanced Usage

// Example 4
// Changing the size of the buffer.
void ExampleFunction4(LPCWSTR pszW)
{
   // Use a 16-character buffer.
   ExampleFunctionA(CW2AEX<16>(pszW));
}

// Example 5
// Specifying the code page.
void ExampleFunction5(LPCWSTR pszW)
{
   // Convert to the Macintosh code page
   ExampleFunctionA(CW2A(pszW, CP_MACCP));
}

The original text conversion macros are still available and are listed in the table below:

The syntax for using these macros is as follows:

MACRONAME( string_address )

For example:

A2W(lpa);

In the macro names, the source string type is on the left (for example, A) and the destination string type is on the right (for example, W). A stands for LPSTR, OLE stands for LPOLESTR, T stands for LPTSTR, and W stands for LPWSTR.

If there is a C in the macro name, the macro converts to a const string. For example, W2CA converts an LPWSTR to an LPCSTR.

Thus, A2W converts an LPSTR to an LPWSTR, OLE2T converts an LPOLESTR to an LPTSTR, and so on.

The behavior of the ATL string conversion macros depends on the compiler directive in effect, if any. If the source and destination types are the same, no conversion takes place. Compiler directives change T and OLE as follows:

The destination string is created using _alloca, except when the destination type is BSTR. Using _alloca allocates memory off the stack, so that when your function returns, it is automatically cleaned up. By default this macro will only convert up to 500KB at one time.

When using an ATL string conversion macro, specify the USES_CONVERSION macro at the beginning of your function in order to avoid compiler errors. For example:

void StringFunc(LPSTR lpsz)
{
   USES_CONVERSION;

   LPWSTR x = A2W(lpsz);
   // Do something with x
   wprintf_s(L"x is %s", x);
}

Requirements

Concepts