Generic-Text Mappings in tchar.h
To simplify the transporting of code for international use, the Microsoft run-time library provides Microsoft-specific generic-text mappings for many data types, routines, and other objects. You can use these mappings, which are defined in tchar.h, to write generic code that can be compiled for single-byte, multibyte, or Unicode character sets, depending on a manifest constant that you define by using a
#define statement. Generic-text mappings are Microsoft extensions that are not ANSI compatible.
By using the tchar.h, you can build single-byte, Multibyte Character Set (MBCS), and Unicode applications from the same sources. tchar.h defines macros (which have the prefix
_tcs) that, with the correct preprocessor definitions, map to
wcs functions, as appropriate. To build MBCS, define the symbol
_MBCS. To build Unicode, define the symbol
_UNICODE. To build a single-byte application, define neither (the default). By default,
_UNICODE is defined for MFC applications.
_TCHAR data type is defined conditionally in tchar.h. If the symbol
_UNICODE is defined for your build,
_TCHAR is defined as wchar_t; otherwise, for single-byte and MBCS builds, it is defined as char. (wchar_t, the basic Unicode wide-character data type, is the 16-bit counterpart to an 8-bit signed char.) For international applications, use the
_tcs family of functions, which operate in
_TCHAR units, not bytes. For example,
Because some Single Byte Character Set (SBCS) string-handling functions take (signed)
char* parameters, a type mismatch compiler warning results when
_MBCS is defined. There are three ways to avoid this warning:
Use the type-safe inline function thunks in tchar.h. This is the default behavior.
Use the direct macros in tchar.h by defining
_MB_MAP_DIRECTon the command line. If you do this, you must manually match types. This is the fastest method, but is not type-safe.
Use the type-safe statically linked library function thunks in tchar.h. To do so, define the constant
_NO_INLININGon the command line. This is the slowest method, but the most type-safe.
Preprocessor Directives for Generic-Text Mappings
|# define||Compiled version||Example|
|None (the default has neither
For example, the generic-text function
_tcsrev, which is defined in tchar.h, maps to
_mbsrev if you defined
_MBCS in your program, or to
_wcsrev if you defined
_tcsrev maps to
strrev. Other data type mappings are provided in tchar.h for programming convenience, but
_TCHAR is the most useful.
Generic-Text Data Type Mappings
Data Type Name
_MBCS Not Defined
||signed char||signed char||wchar_t|
||unsigned char||unsigned char||wchar_t|
||No effect (removed by preprocessor)||No effect (removed by preprocessor)||
For a list of generic-text mappings of routines, variables, and other objects, see Generic-Text Mappings in the Run-Time Library Reference.
Do not use the
str family of functions with Unicode strings, which are likely to contain embedded null bytes. Similarly, do not use the
wcs family of functions with MBCS (or SBCS) strings.
The following code fragments illustrate the use of
_tcsrev for mapping to the MBCS, Unicode, and SBCS models.
_TCHAR *RetVal, *szString; RetVal = _tcsrev(szString);
_MBCS has been defined, the preprocessor maps this fragment to this code:
char *RetVal, *szString; RetVal = _mbsrev(szString);
_UNICODE has been defined, the preprocessor maps this fragment to this code:
wchar_t *RetVal, *szString; RetVal = _wcsrev(szString);
_UNICODE have been defined, the preprocessor maps the fragment to single-byte ASCII code, as follows:
char *RetVal, *szString; RetVal = strrev(szString);
Therefore, you can write, maintain, and compile a single-source code file to run with routines that are specific to any of the three kinds of character sets.