Mapeamentos de texto genérico em tchar.h

Para simplificar o transporte de código para uso internacional, a biblioteca de runtime da Microsoft fornece mapeamentos de texto genérico específico da Microsoft para vários tipos de dados, rotinas e outros objetos. Você pode usar esses mapeamentos, que são definidos em tchar.h, para escrever código genérico que pode ser compilado para conjuntos de caracteres Unicode, multibyte ou byte único, dependendo de uma constante de manifesto que você definir usando uma instrução #define. Mapeamentos de texto genérico são extensões da Microsoft não compatíveis com ANSI.

Usando tchar.h, você pode criar aplicativos de byte único, MBCS (conjunto de caracteres multibyte) e Unicode das mesmas fontes. tchar.h define macros (que têm o prefixo _tcs) que, com as definições corretas do pré-processador, mapeiam para as funções str, _mbs ou wcs, conforme apropriado. Para criar o MBCS, defina o símbolo _MBCS. Para criar o Unicode, defina o símbolo _UNICODE. Para criar um aplicativo de byte único, defina nenhum (o padrão). Por padrão, _UNICODE é definido para aplicativos do MFC.

O tipo de dados _TCHAR é definido condicionalmente em tchar.h. Se o símbolo _UNICODE for definido para seu build, _TCHAR será definido como wchar_t. Caso contrário, para builds de byte único e MBCS, ele será definido como char. (wchar_t, o tipo de dados Unicode de caractere largo básico, é o equivalente de 16 bits de um signed char de 8 bits). Para aplicativos internacionais, use a família de funções _tcs, que opera em unidades _TCHAR, não bytes. Por exemplo, _tcsncpy copia n_TCHARs, não bytes n.

Devido a algumas funções de manipulação de cadeia de caracteres SBCS (conjunto de caracteres de um byte) aceitarem parâmetros char* (assinados), definir _MBCS resultará em um aviso do compilador sobre incompatibilidade de tipo. Há três formas de evitar esse aviso:

1. Use as conversões embutidas fortemente tipadas em tchar.h. Esse é o comportamento padrão.

2. Use as macros diretas em tchar.h definindo _MB_MAP_DIRECT na linha de comando. Se você fizer isso, você deverá realizar a correspondência de tipos manualmente. Esse é o método mais rápido, mas não é fortemente tipado.

3. Use as conversões de biblioteca vinculada estaticamente fortemente tipadas em tchar.h. Para fazer isso, defina a constante _NO_INLINING na linha de comando. Esse é o método mais lento, no entanto, é o mais fortemente tipado.

Diretivas de pré-processador para mapeamentos de texto genérico

# define	Versão compilada	Exemplo
_UNICODE	Unicode (caracteres largos)	_tcsrev é mapeado para _wcsrev
_MBCS	Caracteres multibyte	_tcsrev é mapeado para _mbsrev
Nenhum (padrão: não há definição de _UNICODE nem de _MBCS)	SBCS (ASCII)	_tcsrev é mapeado para strrev

Por exemplo, a função de texto genérico _tcsrev, definida em tchar.h, é mapeada para _mbsrev, caso _MBCS tenha sido definido em seu programa, ou para _wcsrev, caso _UNICODE tenha sido definido. Do contrário, _tcsrev é mapeado para strrev. Outros mapeamentos de tipo de dados são fornecidos em tchar.h para conveniência de programação, mas _TCHAR é o mais útil.

Mapeamentos de tipo de dados de texto genérico

Texto genérico Nome de tipo de dados	_UNICODE & _MBCS não definido	_MBCS Definido	_UNICODE Definido
_TCHAR	char	char	wchar_t
_TINT	int	unsigned int	wint_t
_TSCHAR	signed char	signed char	wchar_t
_TUCHAR	unsigned char	unsigned char	wchar_t
_TXCHAR	char	unsigned char	wchar_t
_T ou _TEXT	Nenhum efeito (removido pelo pré-processador)	Nenhum efeito (removido pelo pré-processador)	L (converte o próximo caractere ou a próxima cadeia de caracteres no equivalente em Unicode)

Para obter uma lista de mapeamentos de texto genérico de rotinas, variáveis e outros objetos, confira Mapeamentos de texto genérico na referência da biblioteca de runtime.

Observação

Não use a família de funções str com cadeias de caracteres Unicode, que provavelmente conterão bytes nulos inseridos. Da mesma forma, não use a família de funções wcs com cadeias de caracteres MBCS (ou SBCS).

Os fragmentos de código a seguir ilustram o uso de _TCHAR e _tcsrev para mapear os modelos MBCS, Unicode e SBCS.

_TCHAR *RetVal, *szString;
RetVal = _tcsrev(szString);

Se _MBCS tiver sido definido, o pré-processador mapeará esse fragmento para esse código:

char *RetVal, *szString;
RetVal = _mbsrev(szString);

Se _UNICODE tiver sido definido, o pré-processador mapeará esse fragmento para esse código:

wchar_t *RetVal, *szString;
RetVal = _wcsrev(szString);

Se _MBCS nem _UNICODE tiver sido definido, o pré-processador mapeará o fragmento para o código ASCII de byte único, da seguinte maneira:

char *RetVal, *szString;
RetVal = strrev(szString);

Portanto, você pode escrever, manter e compilar um arquivo de código-fonte único para execução com rotinas que sejam específicas para qualquer um dos três tipos de conjuntos de caracteres.

Confira também

Texto e cadeias de caracteres
Usando tipos de dados TCHAR.H com código _MBCS