|
(OS/2 Warp) Second Edition (October 1997) |
This document describes the OS/2 Warp Universal Language
Support (ULS) functions. These functions provide APIs and data types to support
internationalization of applications.
This document is broken up into four major sections:
Locale and Character Classification Functions
Internationalized applications are required to operate in a variety of environments
based on some territory, language, and/or cultural definition. These environments
are identified by a locale, an object which encapsulates culturally specific
information. The locale identifies the culture, language, and territory that it
supports.
UniCompleteUserLocale is used to finish a locale modification. This API is called
after one or more UniSetLocaleItem calls to cause the new user defined locale file
to be saved.
Format
#include <unidef.h>
Parameters
None required.
Remarks
UniCompleteUserLocale is used to complete the process of defining a new locale
or modifying an existing locale. An application will use the UniQueryLocale API's
and UniSetUserLocaleItem API to take an existing locale definition and customize
that definition to form a new locale. When the customization process is complete,
the UniCompleteUserLocale API is invoked to save the results as a new locale.
The result of calling this API is that the locale is saved to disk as a new user
locale or changes to an existing locale are saved to disk to represent the newly
created locale.
Related Functions
Example
This example shows how to complete a user locale after modifying
one or more locale items.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
/* Array containing user locales */
UniChar *uniUsrLocales;
int rc = ULS_SUCCESS;
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* allocate space for the user defined locales */
uniUsrLocales = (UniChar *) malloc(4096);
/* Query the list of user defined locales available to modify */
rc = UniQueryLocaleList(UNI_USER_LOCALES, uniUsrLocales, 2048);
if (rc != ULS_SUCCESS) {
printf("UniQueryLocaleList error: return code = %u\n", rc);
return 1;
}
.
.
.
/* Change locale definition by calling UniSetUserLocaleItem to make
locale item changes.
*/
.
.
.
/* Write the current set of user locales to disk */
rc = UniCompleteUserLocale();
if (rc != ULS_SUCCESS) {
printf("UniCompleteUserLocale error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniCreateAttrObject creates an attribute object that is used to determine character
classifications.
Format
#include <unidef.h>
Remarks
UniCreateAttrObject allocates resources associated with an attribute defined
in the LC_CTYPE category of the locale indicated by the locale_object argument.
The locale_object argument specifies a locale object handle returned by UniCreateLocaleObject.
It should not be a NULL pointer.
The AttrName argument specifies the attribute names for which an attribute object
handle should be created. Multiple attribute names are specified as a string of
space-separated names.
When UniCreateAttrObject completes without errors, the attr_object argument specifies
a valid pointer to an attribute object.
The attribute object pointer should be used in all subsequent calls to the UniQueryCharAttr.
If the function result is other than ULS_SUCCESS, the contents of the area pointed
to by attr_object are undefined.
The following attribute names are the base POSIX attributes. All attribute names
which can be specified in UniQueryCharAttr are allowed.
Those attributes which start with underscore (_) or hash (#) may not be combined
with other attributes.
Related Functions
Example
This example shows how to create and use a character attribute object.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
AttrObject attr_object = NULL;
int result = 0;
int rc = ULS_SUCCESS;
UniChar uni_char = L'a'; /* Unicode lowercase Latin letter a */
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Create an alphabetic attribute object */
rc = UniCreateAttrObject(locale_object,
(UniChar *)L"alpha", &attr_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateAttrObject error: return code = %u\n", rc);
return 1;
}
/* Make call to determine if character is alphabetic */
result = UniQueryCharAttr(attr_object, uni_char);
if (result)
printf("UniChar character %04X is alphabetic\n", uni_char);
else
printf("UniChar character %04X is not alphabetic\n", uni_char);
return ULS_SUCCESS;
}
UniCreateLocaleObject creates a locale object.
Format
#include <unidef.h>
The constant names of the values of LocaleSpecType are defined in
the header unidef.h:
Remarks
UniCreateLocaleObject creates a locale object for the locale specified by LocaleSpec.
The object created is an opaque object containing all the data and methods necessary
to perform the language-sensitive operations or functions that accept an argument
of type LocaleObject. If the function is successful, all categories of the
locale object are created and initialized.
When the LocaleSpec argument is a pointer to a character string (UCS character
string or multibyte character string), it identifies the name of the locale to be
initialized. The locale name is used to locate physical resources associated with
this locale. The locale name UNIV is reserved and refers to the definitions
that provide default behavior for functions.
When the LocaleSpec argument is a NULL pointer (without regard to the
value of the LocaleSpecType argument), UniCreateLocaleObject creates a locale
object for the UNIV locale.
When the LocaleSpec argument points to a locale token value as indicated
by the value of the LocaleSpecType argument, the token identifies the locale
to be initialized.
When the LocaleSpec argument is an empty multibyte or UCS character string,
UniCreateLocaleObject creates a locale object based upon the settings of the locale
environment variables.
|
Catgeory |
Precedence |
Usage |
|
LC_ALL |
Highest |
Setting LC_ALL takes precedence over any other locale environment variable. |
|
LC_COLLATE |
Equal precedence |
Specifies collation (sorting) rules. |
|
LC_CTYPE |
Equal precedence |
Specifies character classification and case conversion. |
|
LC_MESSAGES |
Equal precedence |
Specifies the values for affirmative and negative answers, and the language
for displayed messages. |
|
LC_MONETARY |
Equal precedence |
Specifies monetary formats and currency symbol. |
|
LC_NUMERIC |
Equal precedence |
Specifies decimal formats. |
|
LC_TIME |
Equal precedence |
Specifies date and time formats. |
|
LANG |
Lowest |
Setting LANG takes precedence over any undefined locale environment
variable. This may be used in conjunction with LC_COLLATE, LC_CTYPE, LC_MESSAGES,
LC_MONETARY, LC_NUMERIC, and LC_TIME. |
If the specified locale is valid and supported, UniCreateLocaleObject allocates
memory for the new object and returns the address of the created locale object in
the area pointed to by locale_object. It is the application's responsibility
to free this memory with a call to UniFreeLocaleObject when the object is no longer
needed. If the function fails for any reason, the contents of the area pointed to
by locale_object are undefined.
The locale token provides a shorthand notation for specifying a locale. The format
of the locale token is as returned by a call to UniLocaleStrToToken. The format
is defined as an unsigned integer of four octets.
Examples of typical usage:
The locale environment variables are set as follows:
LANG=de_DE
LC_MONETARY=en_US
The LocaleSpec argument is an empty multibyte or UCS character string. This example creates a locale object with all categories set to de_DE except for
LC_MONETARY which has the value of en_US.
The locale environment variables are set as follows:
LANG=fr_FR
The LocaleSpec argument is an empty multibyte or UCS character string. This example creates a locale object with all categories set to fr_FR.
The locale environment variables are set as follows:
LC_ALL=it_IT
LANG=fr_FR
The LocaleSpec argument is an empty multibyte or UCS character string. This example creates a locale object with all categories set to it_IT.
Related Functions
Example
This example shows how to create a locale object.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
int rc = ULS_SUCCESS;
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniCreateTransformObject creates a string transform object.
Format
#include <unidef.h>
Returns
Remarks
UniCreateTransformObject obtains a transformation object for a transformation
type as defined in the locale indicated by the locale_object argument. The function
returns a transformation object that can be used as an argument in UniTransformStr.
The following transformation types are defined in all locales:
In addition to the above transformation-type names, other transformation-type
names in the locale (including user-defined transformation-type names) may be passed
to UniCreateTransformObject through the xtype argument. To obtain a successful return,
the transformation-type name must be defined in locale_object.
When UniCreateTransformObject completes without errors, the xform_object argument
value specifies a valid pointer to a transformation object. The transformation object
should be used in all subsequent calls to UniTransformStr. If the function result
is other than ULS_SUCCESS, the contents of the area pointed to by xform_object
are undefined.
Related Functions
Example
This example shows how to create and use a transform object.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
XformObject xform_object = NULL;
int rc = ULS_SUCCESS;
int in_unistr_elem = 0;
int out_unistr_elem = 10;
UniChar *pin_unistr = (UniChar *)L"os2";
UniChar out_unistr[10];
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Create an upper case transform object */
rc = UniCreateTransformObject(locale_object,
(UniChar *)L"upper", &xform_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateTransformObject error: return code = %u\n", rc);
return 1;
}
/* Calculate the number of elements to transform */
in_unistr_elem = UniStrlen (pin_unistr) + 1;
/* Make call to transform input string to uppercase */
rc = UniTransformStr(xform_object, pin_unistr,
&in_unistr_elem, out_unistr,
&out_unistr_elem);
if (rc != ULS_SUCCESS) {
printf("UniTransformStr error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniDeleteUserLocale is used to delete a locale created by a user.
Format
#include <unidef.h>
Parameters
Remarks
UniCompleteDeleteLocale is used to remove a previously defined user locale. The
locale must have been previously created as a user locale. This is accomplished
by using the UniCompleteUserLocale API.
Related Functions
Example
This example shows how to delete a user locale once it is no longer
needed by the user.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
/* Array containing user locales */
UniChar *uniUsrLocales;
UniChar uniLocaleName[MAX_LOCALE_NAME_LENGTH];
int rc = ULS_SUCCESS;
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
.
.
.
/*
Identify the locale to be deleted - making sure the name is in
Unicode.
*/
.
.
.
/* Delete a user locale from the disk */
rc = UniDeleteUserLocale(uniLocaleName);
if (rc != ULS_SUCCESS) {
printf("UniDeleteUserLocale error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniFreeAttrObject frees the character attribute object.
Format
#include <unidef.h>
Returns
UniFreeAttrObject returns one of the following values:
Remarks
UniFreeAttrObject releases all resources associated with the character attribute
object allocated by UniCreateAttrObject.
The attr_object argument specifies a previously allocated attribute object.
Related Functions
Example
This example shows how to create and free a character attribute object.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
AttrObject attr_object = NULL;
int rc = ULS_SUCCESS;
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Create an alphabetic attribute object */
rc = UniCreateAttrObject(locale_object,
(UniChar *)L"alpha", &attr_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateAttrObject error: return code = %u\n", rc);
return 1;
}
/* Free the character attribute object */
rc = UniFreeAttrObject(attr_object);
if (rc != ULS_SUCCESS) {
printf("UniFreeAttrObject error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniFreeLocaleInfo frees a locale information structure created by UniQueryLocaleInfo.
Format
#include <unidef.h>
Returns
Related Functions
Example
This example shows how to create and free a locale information structure.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
struct UniLconv *puni_lconv = NULL;
int rc = ULS_SUCCESS;
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Retrieve locale information */
rc = UniQueryLocaleInfo(locale_object, &puni_lconv);
if (rc != ULS_SUCCESS) {
printf("UniQueryLocaleInfo error: return code = %u\n", rc);
return 1;
}
printf("Monetary decimal point is %ls\n", puni_lconv->mon_decimal_point);
/* Free the locale information structure */
rc = UniFreeLocaleInfo(puni_lconv);
if (rc != ULS_SUCCESS) {
printf("UniFreeLocaleInfo error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniFreeLocaleObject frees a locale object that was created by UniCreateLocaleObject.
Format
#include <unidef.h>
Returns
Remarks
The UniFreeLocaleObject function destroys the locale object identified by locale_object
and frees any memory associated with it.
Related Functions
Example
This example shows how to create and free a locale object.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
int rc = ULS_SUCCESS;
/* Create a locale object for French in Canada */
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"fr_CA", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Free the locale object that was just created */
rc = UniFreeLocaleObject(locale_object);
if (rc != ULS_SUCCESS) {
printf("UniFreeLocaleObject error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniFreeMem frees memory allocated by UniQueryLocaleObject.
Format
#include <unidef.h>
Returns
Remarks
UniFreeMem frees memory allocated by ULS functions. For example, the memory allocated
for the locale_name parameter of UniQueryLocaleObject should be freed using UniFreeMem.
Example
This example shows how to free memory allocated by a ULS function.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
int rc = ULS_SUCCESS;
char *locale_name;
/* Create a locale object for French in Canada */
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"fr_CA", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Determine the locale name for the LC_MESSAGES category */
rc = UniQueryLocaleObject(locale_object, LC_MESSAGES,
UNI_MBS_STRING_POINTER,
(void **)&locale_name);
if (rc != ULS_SUCCESS) {
printf("UniQueryLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Free the memory allocated by UniQueryLocaleObject */
rc = UniFreeMem((void **)locale_name);
if (rc != ULS_SUCCESS) {
printf("UniFreeMemObject error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniFreeTransformObject frees a string transformation object.
Format
#include <unidef.h>
Returns
Remarks
UniFreeTransformObject releases all resources associated with a transformation
object previously obtained by UniCreateTransformObject.
Related Functions
Example
This example shows how to create and free a transform object.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
XformObject xform_object = NULL;
int rc = ULS_SUCCESS;
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Create an upper case transform object */
rc = UniCreateTransformObject(locale_object,
(UniChar *)L"lower", &xform_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateTransformObject error: return code = %u\n", rc);
return 1;
}
/* Free the transform object created by UniCreateTransformObject */
rc = UniFreeTransformObject(xform_object);
if (rc != ULS_SUCCESS) {
printf("UniFreeTransformObject error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniLocaleStrToToken converts a locale specification string to a token.
Format
#include <unidef.h>
The LocaleStringType argument can take any of the following values, which
are constants defined in the header unidef.h:
Returns
Remarks
UniLocaleStrToToken accepts, as an argument, a locale string qualified by the
value of the LocaleStringType argument. It returns a locale token pointed
to by locale_token if such a token exists for that locale string. UniLocaleStrToToken
allocates memory to hold the locale token value. If no locale token exists for the
supplied locale string, the value returned in locale_token is undefined.
Related Functions
Example
This example shows how to convert a locale specification string to a token.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar *locale_string = L"de_DE"; /*German in Germany locale string */
LocaleToken locale_token;
int rc = ULS_SUCCESS;
rc = UniLocaleStrToToken(UNI_UCS_STRING_POINTER,
(void *)locale_string,
&locale_token);
if (rc != ULS_SUCCESS) {
printf("UniLocaleStrToToken error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniLocaleTokenToStr converts a locale token to a locale specification string.
Format
#include <unidef.h>
An address of a pointer variable locale_string that will contain the locale
specification string corresponding to locale_token.
Remarks
The UniLocaleTokenToStr() function accepts as an argument a locale token in locale_token
and returns a pointer to a locale string in locale_string qualified by the
LocaleStringType argument. The UniLocaleTokenToStr() function allocates memory to
hold the locale string value. It is the application's responsibility to free the
memory using UniFreeMem() when the locale string value is no longer needed. If no
locale string can be generated for the supplied locale token, the value returned
in locale_string is undefined.
Related Functions
Example
This example shows how to convert a locale token to a locale specification string.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar *locale_string1 = L"de_DE"; /*German in Germany locale string */
UniChar *locale_string2;
LocaleToken locale_token;
int rc = ULS_SUCCESS;
rc = UniLocaleStrToToken(UNI_UCS_STRING_POINTER,
(void *)locale_string1,
&locale_token);
if (rc != ULS_SUCCESS) {
printf("UniLocaleStrToToken error: return code = %u\n", rc);
return 1;
}
/* Convert the token to a locale string */ rc = UniLocaleTokenToStr(locale_token,
UNI_UCS_STRING_POINTER,
(void **)&locale_string2);
if (rc != ULS_SUCCESS) {
printf("UniLocaleTokenToStr error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniMakeUserLocale creates a user locale from a base system locale.
Format
#include <unidef.h>
Returns
Remarks
The names for the new locale and the base system locale must be ASCII-7 chars
and at most eight characters, in length. An existing locale name must be given as
the base locale name.
If the user locale already exists, a ULS_NOOP return code will be given, therefore,
this API can always be called before making an update to ensure that the user locale
exists.
Related Functions
Example
This example shows how to make a user locale.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
int rc = ULS_SUCCESS;
UniChar *plocaleName;
UniChar *puniSysLocale;
/* Create current default locale object for this process */
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"",
&locale_object);
if(rc) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Query the name of the default locale object */
rc = UniQueryLocaleObject(locale_object,
LC_ALL,
UNI_UCS_STRING_POINTER,
(void**)&plocaleName);
if(rc) {
printf("UniQueryLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Get the locale name from the locale object string */
puniSysLocale = UniStrtok(plocaleName, (UniChar *)L" ");
/* Make a new locale */
rc = UniMakeUserLocale(puniSysLocale, puniSysLocale);
if (rc) {
printf("UniMakeUserLocale error: return code = %u\n", rc);
return 1;
}
/* free the space used by the locale object string */
UniFreeMem(plocaleName);
if(locale_object)
UniFreeLocaleObject(locale_object);
return ULS_SUCCESS;
}
UniMapCtryToLocale converts an unsigned long country code into a locale name
represented as a UniChar string that is acceptable as input to other Unicode APIs.
Format
#include <unidef.h>
Returns
UniMapCtryToLocale returns one of the following values:
Related Functions
Example
This example shows how to map a country code to a locale name.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar ucs_locale_name[8];
size_t num_elems = 8;
unsigned long country_num = 1;
LocaleObject locale_object = NULL;
int rc = ULS_SUCCESS; /*****************************************************************/
/* Convert country number to a locale name */
/*****************************************************************/
rc = UniMapCtryToLocale(country_num, ucs_locale_name, num_elems);
if (rc != ULS_SUCCESS) {
printf("UniMapCtryToLocale error: return code = %u\n", rc);
return 1;
}
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
ucs_locale_name, &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniQueryAlnum queries character attributes.
Format
#include <unidef.h>
Returns
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr,
and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Example
This example shows how to query character attributes.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
int result = 0;
int rc = ULS_SUCCESS;
UniChar uni_char = L'a'; /* Unicode lowercase Latin letter a */
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Query character attribute */
result = UniQueryAlnum(locale_object, uni_char);
if (result)
printf("UniChar character %04X is alphanumeric\n", uni_char);
else
printf("UniChar character %04X is not alphanumeric\n", uni_char);
return ULS_SUCCESS;
}
UniQueryAlpha queries character attributes.
Format
#include <unidef.h>
Returns
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr,
and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Example
This example shows how to query character attributes.
#include <stdio.h>
#include <unidef.h>
int main(void) {
int result = 0;
int rc = ULS_SUCCESS;
UniChar uni_char = L'a'; /* Unicode lowercase Latin letter a */
/* Query character attribute */
result = UniQueryAlpha(NULL, uni_char);
if (result)
printf("UniChar character %04X is alphabetic\n", uni_char);
else
printf("UniChar character %04X is not alphabetic\n", uni_char);
return ULS_SUCCESS;
}
UniQueryAttr returns the value associated with attribute name supplied by the
user.
Format
#include <unidef.h>
Returns
Remarks
This function provides the numeric value for the standard attributes such as
alpha, graph, and number. In addition, this function provides the numeric value
for other attributes such as Hiragana, diacritic, halfwidth etc. The table below
contains the valid attribute names. Valid names are all in lower case.
Attribute names that begin with a lower case letter may be ORed together.
Attribute Name and Description Table
|
Attr Name |
Attribute Define |
Description of Attribute |
|
alnum |
CT_ALNUM |
Alphabetic and numeric characters |
|
alpha |
CT_ALPHA |
Letters and linguistic marks |
|
ascii |
CT_ASCII |
Standard ASCII character |
|
blank |
CT_BLANK |
Space and Tab |
|
cntrl |
CT_CNTRL |
Control and format characters |
|
diacritic |
C3_DIACRITIC |
Diacritic |
|
digit |
CT_DIGIT |
Digits 0 through 9 |
|
fullwidth |
C3_FULLWIDTH |
Full width variant |
|
graph |
CT_GRAPH |
All except controls and space |
|
halfwidth |
C3_HALFWIDTH |
Half width variant |
|
hiragana |
C3_HIRAGANA |
Hiragana character |
|
ideograph |
C3_IDEOGRAPH |
Kanji/Han character |
|
kashida |
C3_KASHIDA |
Arabic tatweel (used to stretch characters) |
|
katakana |
C3_KATAKANA |
Katakana character |
|
lower |
CT_LOWER |
Lower case alphabetic character |
|
nonspacing |
C3_NONSPACING |
Non-spacing mark |
|
nsdiacritic |
C3_NSDIACRITIC |
Non-spacing diacritic |
|
nsvowel |
C3_NSVOWEL |
Non-spacing vowel |
|
number |
CT_NUMBER |
Integers between 0 and 9 |
|
print |
CT_PRINT |
Everything except control characters |
|
punct |
CT_PUNCT |
Punctuation marks |
|
space |
CT_SPACE |
Whitespace and line ends |
|
symbol |
CT_SYMBOL |
Symbol |
|
upper |
CT_UPPER |
Upper case alphabetic character |
|
vowelmark |
C3_VOWELMARK |
Vowel mark |
|
xdigit |
CT_XDIGIT |
Hexadecimal digits (0-9, a-f or A-F) |
|
_apl |
CHS_APL |
APL character |
|
_arabic |
CHS_ARABIC |
Arabic character |
|
_arrow |
CHS_ARROW |
Arrow character |
|
_bengali |
CHS_BENGALI |
Bengali character |
|
_bopomofo |
CHS_BOPOMOFO |
Bopomofo character |
|
_box |
CHS_BOX |
Box or line drawing character |
|
_currency |
CHS_CURRENCY |
Currency Symbol |
|
_cyrillic |
CHS_CYRILLIC |
Cyrillic character |
|
_dash |
CHS_DASH |
Dash character |
|
_dingbat |
CHS_DINGBAT |
Dingbat |
|
_fraction |
CHS_FRACTION |
Fraction value |
|
_greek |
CHS_GREEK |
Greek character |
|
_gujarati |
CHS_GUJARATI |
Gujarati character |
|
_gurmukhi |
CHS_GURMUKHI |
Gurmukhi character |
|
_hanguel |
CHS_HANGUEL |
Hanguel character |
|
_hebrew |
CHS_HEBREW |
Hebrew character |
|
_hiragana |
CHS_HIRAGANA |
Hiragana character set |
|
_katakana |
CHS_KATAKANA |
Katakana character set |
|
_lao |
CHS_LAO |
Laotian character |
|
_latin |
CHS_LATIN |
Latin character |
|
_linesep |
CHS_LINESEP |
Line separator |
|
_math |
CHS_MATH |
Math symbol |
|
_punctstart |
CHS_PUNCTSTART |
Punctuation start |
|
_punctend |
CHS_PUNCTEND |
Punctuation end |
|
_tamil |
CHS_TAMIL |
Tamil character |
|
_telegu |
CHS_TELEGU |
Telegu character |
|
_thai |
CHS_THAI |
Thai character |
|
_userdef |
CHS_USERDEF |
User defined character |
|
#arabicnum |
C2_ARABICNUMBER |
Arabic numbers |
|
#blocksep |
C2_BLOCKSEPARATOR |
Block separator |
|
#commonsep |
C2_COMMONSEPARATOR |
Common separator |
|
#euronum |
C2_EUROPENUMBER |
European number |
|
#eurosep |
C2_EUROPESEPARATOR |
European separator |
|
#euroterm |
C2_EUROPETERMINATOR |
European terminator |
|
#left |
C2_LEFTTORIGHT |
Left to right text orientation |
|
#mirrored |
C2_MIRRORED |
Symmetrical text orientation |
|
#neutral |
C2_OTHERNEUTRAL |
Other neutral |
|
#right |
CT_RIGHTTOLEFT |
Right to left text orientation |
|
#whitespace |
C2_WHITESPACE |
Whitespace |
Related Functions
Example
This example shows how to query character attribute values using the
character attributes.
#include <stdio.h>
#include <unidef.h>
int main(void) {
char name[33];
UniChar uname[33];
UniChar * up;
char * cp;
ulong rc;
/*
* Ask the user for an attribute name
*/
printf("Enter attribute name:");
scanf("%s", &name);
if (strlen(name) > 32)
return 1;
/*
* Convert name to unicode
*/
cp = name;
up = uname;
while (*cp) {
*up++ = (UniChar)(*cp++);
}
*up = 0;
/*
* Query the attribute and print the value
*/
rc = UniQueryAttr(tolower(uname));
if (rc == 0) {
printf("UniQueryAttr error: return code = %u\n", rc);
return 1;
} else
printf("%s attribute = %x\n", name, rc);
return ULS_SUCCESS;
}
UniQueryBlank queries character attributes.
Format
#include <unidef.h>
Returns
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr,
and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Example
This example shows how to query character attributes.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
int result = 0;
int rc = ULS_SUCCESS;
UniChar uni_char = L' '; /* Unicode space character */
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Query character attribute */
result = UniQueryBlank(locale_object, uni_char);
if (result)
printf("UniChar character %04X is a blank character\n", uni_char);
else
printf("UniChar character %04X is not a blank character\n", uni_char);
return ULS_SUCCESS;
}
UniQueryChar determines if the character supplied has the attribute(s) requested.
Format
#include <unidef.h>
Returns
Remarks
This function takes the attributes supplied by the caller and tests the character
to determine if they are true for that Unicode character. Attribute names that have
a leading _ or # character represent classes of characters. These attributes must
be tested as individual attributes. The remaining attributes can be or'ed together
before testing.
Related Functions
Example
This example shows how to query if a character has particular attributes.
#include <stdio.h>
#include <unidef.h>
int main(void) {
int result = 0;
UniChar uni_char = L'A'; /* Unicode A character */
/* Query character for upper case and graphic attributes */
result = UniQueryChar(uni_char, C1_UPPER || C1_GRAPH);
if (result)
printf("UniChar is upper case and a graphic character\n");
else
printf("UniChar is not upper case and a graphic character\n"_;
/* Query character for Latin character set attribute */
result = UniQueryChar(uni_char, CHS_LATIN);
if (result)
printf("UniChar is a Latin character\n");
else
printf("UniChar is not a Latin character\n");
return ULS_SUCCESS;
}
UniQueryCharAttr queries the attributes of a character.
Format
#include <unidef.h>
Parameters
Returns
If the result of the test is false, UniQueryCharAttr returns the value
0.
Remarks
UniQueryCharAttr determines whether the code element uc has the attributes specified
by the attribute object argument, attr_object.
Related Functions
Example
This example shows how to create and use a character attribute object.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
AttrObject attr_object = NULL;
int result = 0;
int rc = ULS_SUCCESS;
UniChar uni_char = L'c'; /* Unicode lowercase Latin letter c */
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Create an attribute object */
rc = UniCreateAttrObject(locale_object,
(UniChar *)L"alpha xdigit", &attr_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateAttrObject error: return code = %u\n", rc);
return 1;
}
/* Make call to determine if character matches attributes */
result = UniQueryCharAttr(attr_object, uni_char);
if (result)
printf("UniChar character %04X matches attributes\n", uni_char);
else
printf("UniChar character %04X does not match attributes\n", uni_char);
return ULS_SUCCESS;
}
UniQueryCharType is used to query the type of the character.
Format
#include <unidef.h>
Parameters
Returns
Remarks
UniQueryCharType is designed to provide information to support both the XPG/4
character type as well as the Win32 GetCharType type. Where the function is
similar, this API is designed to be a superset of the Win32 function so that the
Win32 functions can be supported by masking off bits in the returned data structure.
GetCharType is similar to the C library "is" functions.
The UNICTYPE structure contains character set information, information regarding
Bidirectional attributes, information regarding XPG/4 attributes and information
on extended attributes.
Related Functions
Example
This example shows how to query a character type.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UNICTYPE * uct;
UniChar uni_char = 0x3456; /* Some random Unicode character */
/* Query the character type */
uct = UniQueryCharType(uni_char);
/* Examine the returned structure to determine information about
the character. For example, what is its BiDi orientation and
is the character Arabic or Hebrew? */
if (uct->bidi==C2_RIGHTTOLEFT)
printf("Character is presented right to left\n");
else
printf("Character is presented left to right\n");
if (uct->charset==CHS_ARABIC)
printf("Character is Arabic\n");
else if (uct->charset==CHS_HEBREW)
printf("Character is Hebrew\n");
else
printf("Character is not Arabic or Hebrew\n");
return ULS_SUCCESS;
}
UniQueryCharTypeTable is used to query the type of the character.
Format
#include <unidef.h>
Parameters
Returns
Remarks
UniQueryCharTypeTable is passed a pointer to a count and a pointer to a table
of UNICTYPE structures. count is set to the number of entries in the UNICTYPE
structure table. unictype is set to the first structure in the table.
Related Functions
Example
This example shows how to query a character type table.
#include <unidef.h>
#include <stdlib.h>
/*
* StringBidi: Determine bidi types for each character in a string
* Return string of bidi bits, and return value with
* OR of all bits.
*/
USHORT StringBidi(UniChar * instr, USHORT * charsets) {
ULONG count;
UNICTYPE * typetab;
USHORT index, *pcs, out;
int rc, i, len;
/*
* Get addressability to the character type table
*/
UniQueryCharTypeTable (&count, &typetab);
/*
* Create an output string
*/
len = UniStrlen(instr);
UniQueryStringType(instr, len, charsets, CT_INDEX);
/*
* Replace each index with bidi flags
*/
pcs = charsets;
out = 0;
for (i=0; i<len; i++) {
index = *pcs;
*pcs = 0;
if (typetab[index].bidi == C2_RIGHTTOLEFT)
*pcs |= 1;
if (typetab[index].charset == CHS_ARABIC)
*pcs |= 2;
if (typetab[index].charset == CHS_HEBREW)
*pcs |= 4;
out |= *pcs++;
}
return out;
}
UniQueryCntrl queries character attributes.
Format
#include <unidef.h>
Returns
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr,
and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Related Functions
Example
This example shows how to query character attributes.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
int result = 0;
int rc = ULS_SUCCESS;
UniChar uni_char = 0x000A; /* Unicode newline character */
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Query character attribute */
result = UniQueryCntrl(locale_object, uni_char);
if (result)
printf("UniChar character %04X is a control character\n", uni_char);
else
printf("UniChar character %04X is not a control character\n", uni_char);
return ULS_SUCCESS;
}
UniQueryCountryName returns the name of the country in the language specified.
Format
#include <unidef.h>
Parameters
Remarks
This function only queries system provided locales to determine valid country
names.
Related Functions
Example
This example shows how to query a country name.
#include <stdio.h>
#include <unidef.h>
#include <ulsitem.h>
int main(void) {
LocaleObject locale_object = NULL;
int result = 0;
int rc = ULS_SUCCESS;
UniChar *pinfo;
UniChar *langName;
UniChar *countryName;
UniChar *mriLanguage;
UniChar uni_char = L'5'; /* Unicode number 5 character */
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Determine the language to get the country name in */
rc = UniQueryLocaleItem(locale_object, LOCI_sLanguageID,
&mriLanguage);
if (rc != ULS_SUCCESS) {
printf("UniQueryLocaleItem error: return code = %u\n", rc);
return 1;
}
/* Get the ISO country ID
rc = UniQueryLocaleItem(locale_object, LOCI_sCountryID, &pinfo);
if (rc != ULS_SUCCESS) {
printf("UniQueryLocaleItem error: return code = %u\n", rc);
return 1;
}
/* Now we can determine the country name in the proper language */
rc = UniQueryCountryName(pinfo, mriLanguage, &countryName);
if (rc != ULS_SUCCESS) {
printf("UniQueryCountryName error: return code = %u\n", rc);
return 1;
}
printf("Country name is = %ls\n", countryName);
return ULS_SUCCESS;
}
UniQueryDigit queries character attributes.
Format
#include <unidef.h>
Parameters
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr,
and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character
attributes
Related Functions
Example
This example shows how to query character attributes.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
int result = 0;
int rc = ULS_SUCCESS;
UniChar uni_char = L'5'; /* Unicode number 5 character */
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Query character attribute */
result = UniQueryDigit(locale_object, uni_char);
if (result)
printf("UniChar character %04X is a digit\n", uni_char);
else
printf("UniChar character %04X is not a digit\n", uni_char);
return ULS_SUCCESS;
}
UniQueryGraph queries character attributes.
Format
#include <unidef.h>
Parameters
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr,
and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Example
This example shows how to query character attributes.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
int result = 0;
int rc = ULS_SUCCESS;
UniChar uni_char = L'S'; /* Unicode Latin uppercase letter S */
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Query character attribute */
result = UniQueryGraph(locale_object, uni_char);
if (result)
printf("UniChar character %04X is a graphic character\n", uni_char);
else
printf("UniChar character %04X is not a graphic character\n", uni_char);
return ULS_SUCCESS;
}
UniQueryLanguageName returns the name of the language in the language specified.
Format
#include <unidef.h>
Parameters
Remarks
This function only queries system provided locales to determine valid language
names.
Related Functions
Example
This example shows how to query a language name.
#include <stdio.h>
#include <unidef.h>
#include <ulsitem.h>
int main(void) {
LocaleObject locale_object = NULL;
int result = 0;
int rc = ULS_SUCCESS;
UniChar *pinfo;
UniChar *languageName;
UniChar *mriLanguage;
UniChar uni_char = L'5'; /* Unicode number 5 character */
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Determine the language to get the language name in */
rc = UniQueryLocaleItem(locale_object, LOCI_sLanguageID,
&mriLanguage);
if (rc != ULS_SUCCESS) {
printf("UniQueryLocaleItem error: return code = %u\n", rc);
return 1;
}
/* Get the ISO country ID
rc = UniQueryLocaleItem(locale_object, LOCI_sLanguageID, &pinfo);
if (rc != ULS_SUCCESS) {
printf("UniQueryLocaleItem error: return code = %u\n", rc);
return 1;
}
/* Now we can determine the country name in the proper language */
rc = UniQueryCountryName(pinfo, mriLanguage, &languageName);
if (rc != ULS_SUCCESS) {
printf("UniQueryCountryName error: return code = %u\n", rc);
return 1;
}
printf("Language name is = %ls\n", languageName);
return ULS_SUCCESS;
}
UniQueryLocaleInfo retrieves information about locale conventions.
Format
#include <unidef.h>
Remarks
UniQueryLocaleInfo retrieves information from the locale indicated by the locale_object
argument and places the information in a UniLconv structure. UniQueryLocaleInfo
allocates memory to hold the UniLconv structure. It is the application's responsibility
to free the memory with UniFreeLocaleInfo when the UniLconv structure is no longer
needed. The address of the UniLconv structure is returned in UniLconv_struct. The
UniLconv structure is filled in, according to the locale indicated by the locale
object handle argument.
The UniLconv structure contains the following members:
The value of grouping and mon_grouping is interpreted according to the following:
The next element is examined to determine the size of the next group of digits
before the current group.
The n_sign_posn and p_sign_posn elements are interpreted according to the following:
Related Functions
Example
This example shows how to retrieve information about locale conventions.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
struct UniLconv *puni_lconv = NULL;
int rc = ULS_SUCCESS;
/*****************************************************************/
/* Assumes LANG environment variable set to a valid locale name, */
/* such as fr_FR */
/*****************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
/* Retrieve locale information */
rc = UniQueryLocaleInfo(locale_object, &puni_lconv);
if (rc != ULS_SUCCESS) {
printf("UniQueryLocaleInfo error: return code = %u\n", rc);
return 1;
}
/* print the value of the os2 currency symbol position */
printf("The os2 currency symbol position is %d\n",
puni_lconv->os2_mondecpt);
return ULS_SUCCESS;
}
UniQueryLocaleItem retrieves locale information by item.
Format
#include <unidef.h>
Remarks
UniQueryLocaleItem returns a pointer in info_item_addr_ptr to a null-terminated
UniChar string containing information found in the locale object identified by locale_object
about the language or cultural item named by the item argument. UniQueryLocaleItem
allocates the memory to hold the UniChar string and returns a pointer in info_item_addr_ptr.
Use UniFreeMem to free the memory associated with info_item_addr_ptr by UniQueryLocaleItem.
The constant names and values for item are contained in ulsitem.h:
|
Item Name |
Item Description |
|
LOCI_sDateTime |
Date and time format string |
|
LOCI_sShortDate |
Short date format |
|
LOCI_sTimeFormat |
Time format string |