Overview
Group
Quick Info

Windows NT
Yes
Win95
Yes
Win32s
Yes
Import Library
kernel32.lib
Header File
winnls.h
Unicode
No
Platform Notes
None

GetStringTypeA

The GetStringTypeA function returns character-type information for the characters in the specified source string. For each character in the string, the function sets one or more bits in the corresponding 16-bit element of the output array. Each bit identifies a given character type, such as whether the character is a letter, a digit, or neither.

BOOL GetStringTypeA(

LCID Locale,
// locale identifer
DWORD dwInfoType,
// information-type options
LPCSTR lpSrcStr,
// pointer to the source string
int cchSrc,
// size, in bytes, of the source string
LPWORD lpCharType
// pointer to the buffer for output
);

Parameters

Locale

Specifies the locale identifier. This value uniquely defines the ANSI code page to use to translate the string pointed to by lpSrcStr from ANSI to Unicode. The function then analyzes each Unicode character for character type information.

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT
Default system locale
LOCALE_USER_DEFAULT
Default user locale

Note that the Locale parameter does not exist in the GetStringTypeW function. Because of that parameter difference, an application cannot automatically invoke the proper A or W version of GetStringType* through the use of the #define UNICODE switch. An application can circumvent this limitation by using GetStringTypeEx, which is the recommended Win32 function.

dwInfoType

Specifies the type of character information the user wants to retrieve. The various types are divided into different levels (see the following Remarks section for a list of the information included in each type). This parameter can specify one of the following character type flags:

CT_CTYPE1
Retrieve character type information.
CT_CTYPE2
Retrieve bidirectional layout information.
CT_CTYPE3
Retrieve text processing information.

lpSrcStr

Points to the string for which character types are requested. If cchSrc is pics/WIN3200090000.gif1, the string is assumed to be null terminated. This must be an ANSI string. Note that this can be a double-byte character set (DBCS) string if the locale is appropriate for DBCS.

cchSrc

Specifies the size, in bytes, of the string pointed to by the lpSrcStr parameter. If this count includes a null terminator, the function returns character type information for the null terminator. If this value is pics/WIN3200090000.gif1, the string is assumed to be null terminated and the length is calculated automatically.

lpCharType

Points to an array of 16-bit values. The length of this array must be large enough to receive one 16-bit value for each character in the source string. When the function returns, this array contains one word corresponding to each character in the source string.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER

Remarks

The lpSrcStr and lpCharType pointers must not be the same. If they are the same, the function fails and GetLastError returns ERROR_INVALID_PARAMETER.

The Locale parameter is only used to perform string conversion to Unicode. It has nothing to do with the CTYPEs the function returns. The CTYPEs are solely determined by Unicode code points, and do not vary on a locale basis. For example, Greek letters are C1_ALPHA for any Locale value.

The character-type bits are divided into several levels. The information for one level can be retrieved by a single call to this function. Each level is limited to 16 bits of information so that the other mapping routines, which are limited to 16 bits of representation per character, can also return character-type information.

The character types supported by this function include the following.

Ctype 1

These types support ANSI C and POSIX (LC_CTYPE) character-typing functions. A combination of these values is returned in the array pointed to by the lpCharType parameter when the dwInfoType parameter is set to CT_CTYPE1.

Name
Value
Meaning
C1_UPPER
  1. x0001
Uppercase
C1_LOWER
  1. x0002
Lowercase
C1_DIGIT
0x0004
Decimal digits
C1_SPACE
0x0008
Space characters
C1_PUNCT
0x0010
Punctuation
C1_CNTRL
0x0020
Control characters
C1_BLANK
0x0040
Blank characters
C1_XDIGIT
0x0080
Hexadecimal digits
C1_ALPHA
0x0100
Any linguistic character: alphabetic, syllabary, or ideographic

The following character types are either constant or computable from basic types and do not need to be supported by this function.

Type
Description
Alphanumeric
Alphabetic characters and digits (C1_ALPHA and C1_DIGIT)
Printable
Graphic characters and blanks (all C1_* types except C1_CNTRL)

Ctype 2

These types support proper layout of Unicode text. The direction attributes are assigned so that the bidirectional layout algorithm standardized by Unicode produces accurate results. These types are mutually exclusive. For more information about the use of these attributes, see The Unicode Standard: Worldwide Character Encoding, Volumes 1 and 2, Addison Wesley Publishing Company: 1991, 1992, ISBN 0201567881.

Name
Value
Meaning
Strong:


C2_LEFTTORIGHT
  1. x1
Left to right
C2_RIGHTTOLEFT
  1. x2
Right to left
Weak:


C2_EUROPENUMBER
  1. x3
European number, European digit
C2_EUROPESEPARATOR
  1. x4
European numeric separator
C2_EUROPETERMINATOR
  1. x5
European numeric terminator
C2_ARABICNUMBER
  1. x6
Arabic number
C2_COMMONSEPARATOR
  1. x7
Common numeric separator
Neutral:


C2_BLOCKSEPARATOR
  1. x8
Block separator
C2_SEGMENTSEPARATOR
  1. x9
Segment separator
C2_WHITESPACE
  1. xA
White space
C2_OTHERNEUTRAL
  1. xB
Other neutrals
Not applicable:


C2_NOTAPPLICABLE
0x0
No implicit directionality (for example, control codes)

Ctype 3

These types are intended to be placeholders for extensions to the POSIX types required for general text processing or for the standard C library functions. These types are supported in the current version of Windows NT. A combination of these values is returned when dwInfoType is set to CT_CTYPE3.

Name
Value
Meaning
C3_NONSPACING
  1. x1
Nonspacing mark
C3_DIACRITIC
  1. x2
Diacritic nonspacing mark
C3_VOWELMARK
0x4
Vowel nonspacing mark
C3_SYMBOL
0x8
Symbol
C3_KATAKANA
0x10
Katakana character
C3_HIRAGANA
0x20
Hiragana character
C3_HALFWIDTH
0x40
Half-width character
C3_FULLWIDTH
0x80
Full-width character
C3_IDEOGRAPH
0x100
Ideographic character
C3_KASHIDA
0x200
Arabic Kashida character
C3_ALPHA
0x8000
All linguistic characters (alphabetic, syllabary, and ideographic)
Not applicable:


C3_NOTAPPLICABLE
0x0
Not applicable

See Also

GetLocaleInfo
, GetStringTypeEx, GetStringTypeW

Software for developers
Delphi Components
.Net Components
Software for Android Developers
More information resources
MegaDetailed.Net
Unix Manual Pages
Delphi Examples
Databases for Amazon shops developers
Amazon Categories Database
Browse Nodes Database