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 de byte único, multibyte ou Unicode, 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 o tchar.h, você pode criar aplicativos de um único byte, MBCS (conjunto de caracteres multibyte) e Unicode a partir 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 construir um aplicativo de único byte, não defina nada (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 dado Unicode de caractere largo básico, é a contraparte 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 em bytes. Por exemplo, _tcsncpy copia n_TCHARs, não n bytes.

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 funções embutidas seguras para o tipo thunks em tchar.h. Esse é o comportamento padrão.

2. Utilize 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 é seguro em termos de tipo.

3. Utilize as funções de amortecimento seguras para tipos da biblioteca vinculada estaticamente no tchar.h. Para fazer isso, defina a constante _NO_INLINING na linha de comando. Esse é o método mais lento, mas o mais seguro em relação aos tipos.

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

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

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.

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 nem _MBCS nem _UNICODE tiverem sido definidos, 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