ATL e MFC string conversão macros

Artigo
08/25/2010

As macros de conversão de seqüência de caracteres discutidas aqui são válidas para o ATL e MFC.Para obter mais informações sobre a conversão de seqüência de caracteres MFC, consulte TN059: Usando macros MFC Unicode/MBCS conversão e Macros do MFC e globais.

ATL 7.0 string classes de conversão e macros
ATL 3.0 macros de conversão de cadeias de caracteres

ATL 7.0 string classes de conversão e macros

ATL 7.0 apresenta várias novas classes de conversão e macros, oferecendo melhorias significativas sobre macros existentes.

Os nomes das novas classes de conversão de seqüência de caracteres e as macros assumem a forma:

CSourceType2[C]DestinationType[EX]

Onde:

SourceType and DestinationType são descritos na tabela a seguir.
[C está presente quando o tipo de destino deve ser constante.

[POR EXEMPLO está presente quando o dimensionar inicial do buffer deve ser especificado sistema autônomo um argumento de modelo.

SourceType/DestinationType	Descrição
A	Seqüência de caractere ANSI.
W	Seqüência de caractere Unicode.
T	Seqüência de caractere genéricas (equivalente ao W quando _UNICODE estiver definido, equivalente a uma outra forma).
OLE	Seqüência de caractere OLE (equivalente a L).

Por exemplo, para converter de uma seqüência de caracteres Unicode em uma seqüência de caracteres genérica sem alterar a seqüência de caracteres convertida, use CW2CT.

Se ele for conhecido que a seqüência de caracteres convertida é improvável que ter mais de 64 caracteres, a POR EXEMPLO versão, sistema autônomo, por exemplo, CW2CTEX <64>, pode ser usado para economizar espaço na pilha.

Observação:
A maneira recomendada de converter para e de seqüências de caracteres BSTR é usar o CComBSTR classe.Para converter um BSTR, passar a seqüência de caracteres existente para o construtor de CComBSTR. To convert from a BSTR, use COLE2[C]DestinationType[EX], such as COLE2T.

As novas classes de conversão que requer um buffer (CA2AEX, CA2WEX, CW2AEX, e CW2WEX) usam um buffer de dimensionar fixo estático para armazenar o resultado da conversão. Se o resultado é muito grande ajuste no buffer estático, a classe aloca memória usando malloc, liberar a memória quando o objeto fica fora do escopo. Isso garante que, ao contrário das macros de conversão de texto mais antigas, essas classes são seguros usar em loops e não estouram a pilha.

As macros de conversão introduzidas no ATL 7.0 são otimizadas para estar ciente de entrada NULO seqüências.Essas macros retornará NULO se o parâmetro de entrada é NULO sem alocar qualquer memória.

Por padrão, as classes de conversão do ATL e as macros serão usam página de código ANSI corrente do segmento para a conversão.Se você desejar substituir esse comportamento para alguma conversão específica usando macros com base na classes CA2WEX ou CW2AEX, especificar a página de código sistema autônomo o segundo parâmetro para o construtor da classe.

Observação de segurança:
Verifica o comprimento das seqüências de caracteres antes de passá-los para essas macros para evitar possíveis problemas de saturação de buffer.Estouros de pilha são exceções também podem ser detectadas com try / exceto.

Há várias diferenças importantes entre as macros de conversão de seqüência de caracteres mais antigas e as novas classes de conversão de seqüência de caracteres:

Antigo ATL 3.0 macros de conversão	Novo ATL 7.0 classes de conversão
Aloca memória na pilha.	Usa a pilha memória para cadeias de caracteres pequenas.Usa o heap se a pilha não é grande o suficiente.
A seqüência de caracteres é liberada quando a função é finalizada.	A seqüência de caracteres é liberada quando a variável sai do escopo.
Não pode ser usado em manipuladores de exceção.	Pode ser usado em manipuladores de exceção.
Não é adequado para uso em loops.Uso da memória aumenta até que a função será finalizada.	Oferece suporte para usar em loops.Escopo de loop assegura que a memória liberada em cada iteração.
Não é mercadoria para grandes seqüências de caracteres.Espaço de pilha é limitado.	Há problemas com seqüências de caracteres grandes.Seqüências de caracteres serão alocadas no heap.
Geralmente exigem USES_CONVERSION seja definido.	Nunca exigir USES_CONVERSION seja definido.
Significado do OLE depende da definição de OLE2ANSI.	OLE sempre é equivalente a w.

Exemplo

Código

//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);
}

Um aviso sobre instâncias de classe temporários

Estresse que este não é mercadoria código:

LPCTSTR szr = CA2T(szReplaceFile);

Usando macros ATL 3.0, era aceitável o uso de:

LPCTSTR szr = A2T(szReplaceFile);

sistema autônomo a memória alocada pelas funções de conversão não poderia ser liberada até que a função corrente foi encerrada.O mesmo código não funciona com as novas classes.

Este código:

LPCTSTR szr = CA2T(szReplaceFile);

é equivalente a esta:

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

sistema autônomo a memória alocada pelo objeto temporário e retornado pelo operador de lançamento é destruída quando o objeto temporário é destruído, usando o valor em szr terá resultados indesejados.

Em vez disso, use este código:

CA2T szr(szReplaceFile);

O operador de conversão torna o objeto CA2T parecer um LPCTSTR.

Uso avançado

O padrão estático dimensionar do buffer é 128 caracteres.Se o dimensionar do buffer deve ser alterado de alguma conversão específica, usar a versão de EX de uma macro e especificar o dimensionar do buffer sistema autônomo um argumento de modelo.

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

Eis um exemplo de especificar a página de código sistema autônomo o segundo parâmetro para o construtor da classe.

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

ATL 3.0 macros de conversão de cadeias de caracteres

As macros de conversão de texto original ainda estão disponível e são listadas na tabela a seguir:

ATL 3.0 macros de conversão de cadeias de caracteres

A2BSTR	OLE2A	T2A	W2A
A2COLE	OLE2BSTR	T2BSTR	W2BSTR
A2CT	OLE2CA	T2CA (Preterido.Use T2CA_EX ou CT2CA em vez disso.)	W2CA
A2CW	OLE2CT	T2COLE	W2COLE
A2OLE	OLE2CW	T2CW	W2CT
A2T	OLE2T	T2OLE	W2OLE
A2W	OLE2W	T2W	W2T

A sintaxe para usar essas macros é o seguinte:

MACRONAME( string_address )

Por exemplo:

A2W(lpa);

Nos nomes de macro, o tipo de seqüência de caracteres de fonte está à esquerda (por exemplo, UM) e o tipo de seqüência de caracteres de destino é à direita (por exemplo, W).UM significaLPSTR, OLE significaLPOLESTR, T significaLPTSTR, e W significaLPWSTR.

Se houver um C nome da macro, a macro converte um Constseqüência de caracteres .Por exemplo, W2CA converte um LPWSTR para um LPCSTR.

Assim, A2W converte um LPSTR to an LPWSTR, OLE2T converte um LPOLESTR para um LPTSTR, e assim por diante.

O comportamento das macros ATL seqüência conversão depende a diretiva de compilador em vigor, se houver.Se os tipos de fonte e destino forem iguais, nenhuma conversão é feita.Diretivas de compilador alterar T and OLE da seguinte maneira:

Diretiva de compilador em vigor	T torna-se	Torna-se de OLE
Nenhum	A	W
_UNICODE	W	W
OLE2ANSI	A	A
_UNICODE and OLE2ANSI	W	A

A seqüência de caracteres de destino é criada usando _ alloca, exceto quando o tipo de destino é BSTR. Usando _ alloca aloca memória na pilha, para que quando a função retorna, ele automaticamente é limpa.Por padrão desta macro apenas converterá até 500 KB ao mesmo time.

Ao usar uma macro de conversão de seqüência de caracteres ATL, especifique o USES_CONVERSION macro no início de sua função para evitar erros do compilador.Por exemplo:

void StringFunc(LPSTR lpsz)
{
   USES_CONVERSION;

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

Requisitos

Arquivo de cabeçalho: AtlBase.h, AtlConv.h (declarado no AtlConv.h)

Consulte também

Referência

DEVMODE e macros de conversão de string TEXTMETRIC

Outros recursos

Macros ATL

Compartilhar via

ATL e MFC string conversão macros

ATL 7.0 string classes de conversão e macros

Exemplo

Código

Um aviso sobre instâncias de classe temporários

Uso avançado

ATL 3.0 macros de conversão de cadeias de caracteres

Requisitos

Consulte também

Referência

Outros recursos

Recursos adicionais