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 six 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 UniSetUserLocaleItem calls to cause the new user defined locale file to be saved.
#include <unidef.h> int UniCompleteUserLocale( void )
None required.
Return value (int) - returns
UniCompleteUserLocale is used to complete the process of defining a new locale or modifying an existing locale. An application will use the UniQueryLocale* APIs and UniSetUserLocaleItem to take an existing locale definition and customize that definition to form a new locale. When the customization process is complete, UniCompleteUserLocale 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.
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;
UniChar *uniUsrLocales; /* Array containing user locales */
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.
#include <unidef.h>
int UniCreateAttrObject (
const LocaleObject locale_object, /* I - Locale object */
const UniChar *AttrName, /* I - Attribute name(s) */
AttrObject *attr_object /* O - Attribute object */
)
Return value (int) - returns
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 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 UniQueryAttr are allowed. Those attributes which start with underscore (_) or hash (#) may not be combined with other attributes.
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.
#include <unidef.h>
int UniCreateLocaleObject (
int LocaleSpecType, /* I - Locale identifier type */
const void *LocaleSpec, /* I - Locale identifier */
LocaleObject *locale_object /* O - Locale object */
)
The constant names of the values of LocaleSpecType are defined in the header file unidef.h:
Return value (int) - returns
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.
Locale Environment Variables by Precedence and Usage
| Category | 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:
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.
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.
LC_ALL=it_IT LANG=fr_FRThe LocaleSpec argument is an empty multibyte or UCS character string.
This example creates a locale object with all categories set to it_IT.
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.
#include <unidef.h>
int UniCreateTransformObject (
const LocaleObject locale_object, /* I - Locale object */
const UniChar *xtype, /* I - Transform type */
XformObject *xform_object /* O - Transform object */
)
Return value (int) - returns
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.
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.
#include <unidef.h>
int UniDeleteUserLocale (
UniChar *locale /* I - Locale name */
)
Return value (int) - returns
UniDeleteLocale is used to remove a previously defined user locale. The UniCompleteUserLocale API must be called subsequently for the change to take effect.
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) {
UniChar uniLocaleName[ULS_LNAMEMAX];
int rc = ULS_SUCCESS;
.
.
.
/* Identify the locale to be deleted - making sure the name is in
* Unicode - and assign as uniLocaleName.
*/
.
.
.
/*****************************************************************/
/* Delete a user locale from the disk */
/*****************************************************************/
rc = UniDeleteUserLocale(uniLocaleName);
if (rc != ULS_SUCCESS) {
printf("UniDeleteUserLocale error: return code = %u\n", rc);
return 1;
}
/* Save all changes to user locales */
rc = UniCompleteUserLocale();
if (rc != ULS_SUCCESS) {
printf("UniCompleteUserLocale error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniFreeAttrObject frees a character attribute object.
#include <unidef.h>
int UniFreeAttrObject (
AttrObject attr_object /* I - Attribute object */
)
Return value (int) - returns
UniFreeAttrObject releases all resources associated with the character attribute object allocated by UniCreateAttrObject.
The attr_object argument specifies a previously allocated attribute object.
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.
#include <unidef.h>
int UniFreeLocaleInfo (
struct UniLconv *UniLconv_addr /* I - Locale information structure */
)
Return value (int) - returns
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.
#include <unidef.h>
int UniFreeLocaleObject (
LocaleObject locale_object /* I - Locale object */
)
Return value (int) - returns
The UniFreeLocaleObject function destroys the locale object identified by locale_object and frees any memory associated with it.
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.
#include <unidef.h>
int UniFreeMem (
void *memory /* I - Pointer to memory */
)
Return value (int) - returns
UniFreeMem frees memory allocated by ULS functions. For example, the memory allocated for the locale_name parameter of UniQueryLocaleObject should be freed using UniFreeMem.
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("UniFreeMem error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniFreeTransformObject frees a string transformation object.
#include <unidef.h>
int UniFreeTransformObject (
XformObject xform_object /* I - Transform object */
)
Return value (int) - returns
UniFreeTransformObject releases all resources associated with a transformation object previously obtained by UniCreateTransformObject.
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.
#include <unidef.h>
int UniLocaleStrToToken (
int LocaleStringType, /* I - Locale string format */
const void *locale_string, /* I - Locale string */
LocaleToken *locale_token /* O - Locale token */
)
The LocaleStringType argument can take any of the following values, which are constants defined in the header unidef.h:
Return value (int) - returns
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.
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.
#include <unidef.h>
int UniLocaleTokenToStr (
const LocaleToken locale_token, /* I - Locale token */
int LocaleStringType, /* I - Requested locale string format */
void **locale_string /* O - Pointer to locale string */
)
Return value (int) - returns
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.
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.
#include <unidef.h>
int UniMakeUserLocale (
UniChar *newName, /* I - Name of new locale */
UniChar *baseName /* I - Name of base locale */
)
Return value (int) - returns
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.
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.
#include <unidef.h>
int UniMapCtryToLocale (
unsigned long ulCountryCode, /* I - OS/2 country code */
UniChar *ucsLocaleName, /* O - Buffer for locale name */
size_t n /* I - Size of buffer */
)
Return value (int) - returns
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 a Unicode character's alphanumeric (alnum) attribute.
#include <unidef.h>
int UniQueryAlnum (
const LocaleObject locale_object, /* I - Locale object */
UniChar uc /* I - Character to query */
)
Return value (int) - returns
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
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 a Unicode character's alphabetic (alpha) attribute.
#include <unidef.h>
int UniQueryAlpha (
const LocaleObject locale_object, /* I - Locale object */
UniChar uc /* I - Character to query */
)
Return value (int) - returns
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
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 the attribute name supplied by the user.
#include <unidef.h>
ULONG UniQueryAttr (
UniChar *attrName /* I - Attribute name */
)
Return value (ULONG)
If the attribute name is known, the function returns the attribute value. Otherwise, 0 is returned.
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.
Attributes whose names begin with a lower-case letter may be ORed together. Attribute names that have a leading _ or # character represent classes of characters; these attributes must be tested as individual attributes.
Symbolic names beginning with "C1_" are provided as aliases for several POSIX attributes for Win32 compatibility.
Attribute Name and Description Table
| Attr Name | Attribute Define | Description of Attribute |
|---|---|---|
| alnum | CT_ALNUM | Alphabetic and numeric characters |
| alpha | CT_ALPHA C1_ALPHA |
Letters and linguistic marks |
| ascii | CT_ASCII | Standard ASCII character |
| blank | CT_BLANK C1_BLANK |
Space and Tab |
| cntrl | CT_CNTRL C1_CNTRL |
Control and format characters |
| diacritic | C3_DIACRITIC | Diacritic |
| digit | CT_DIGIT C1_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 C1_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 |
| CT_PRINT | Everything except control characters | |
| punct | CT_PUNCT C1_PUNCT |
Punctuation marks |
| space | CT_SPACE C1_SPACE |
Whitespace and line ends |
| symbol | CT_SYMBOL | Symbol |
| upper | CT_UPPER C1_UPPER |
Upper case alphabetic character |
| vowelmark | C3_VOWELMARK | Vowel mark |
| xdigit | CT_XDIGIT C1_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 |
| _devanagari | CHS_DEVANAGARI | Devanagari 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 | C2_RIGHTTOLEFT | Right to left text orientation |
| #whitespace | C2_WHITESPACE | Whitespace |
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 a Unicode character's blank attribute.
#include <unidef.h>
int UniQueryBlank (
const LocaleObject locale_object, /* I - Locale object */
UniChar uc /* I - Character to query */
)
Return value (int) - returns
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
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.
#include <unidef.h>
int UniQueryChar (
UniChar uc, /* I - Character to query */
ULONG attr /* I - Symbolic attribute name */
)
Return value (int) - returns
This function takes the attributes supplied by the caller and tests the character to determine if they are true for that Unicode character. Attribute values are listed under UniQueryAttr; only the standard POSIX attributes (CT_* or C1_*) may be used.
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"_;
return ULS_SUCCESS;
}
UniQueryCharAttr queries the attributes of a character.
#include <unidef.h>
int UniQueryCharAttr (
AttrObject attr_object, /* I - Attribute object */
UniChar uc /* I - Character to query */
)
Return value (int) - returns
UniQueryCharAttr determines whether the code element uc has the attributes specified by the attribute object argument, attr_object.
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.
#include <unidef.h>
UNICTYPE * UniQueryCharType (
UniChar uc /* I - Character to query */
)
A pointer to a structure of type UNICTYPE is returned from this call.
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.
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.
#include <unidef.h>
ULONG UniQueryCharTypeTable (
ULONG *count, /* O - Number of entries in table */
UNICTYPE **unictype /* O - Table of character type data */
)
A ULONG equal to zero is always returned.
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.
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 a Unicode character's control-character (cntrl) attribute.
#include <unidef.h>
int UniQueryCntrl (
const LocaleObject locale_object, /* I - Locale object */
UniChar uc /* I - Character to query */
)
Return value (int) - returns
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.
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.
#include <unidef.h>
int UniQueryCountryName (
UniChar *country, /* I - ID of country to query */
UniChar *isolang, /* I - ID of language to use */
UniChar **infoitem /* O - Pointer to country name */
)
Return value (int) - returns
This function only queries system provided locales to determine valid country names.
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 a Unicode character's numeric (digit) attribute.
#include <unidef.h>
int UniQueryDigit (
const LocaleObject locale_object, /* I - Locale object */
UniChar uc /* I - Character to query */
)
Return value (int) - returns
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
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 a Unicode character's graphic (graph) attribute.
#include <unidef.h>
int UniQueryGraph (
const LocaleObject locale_object, /* I - Locale object */
UniChar uc /* I - Character to query */
)
Return value (int) - returns
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
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 a language in the language specified.
#include <unidef.h>
int UniQueryLanguageName (
UniChar *language, /* I - ID of language to query */
UniChar *isolang, /* I - ID of language to use */
UniChar **infoitem /* O - Pointer to language name */
)
Return value (int) - returns
This function only queries system provided locales to determine valid language names.
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.
#include <unidef.h>
int UniQueryLocaleInfo (
const LocaleObject locale_object, /* I - Locale object */
struct UniLconv **UniLconv_addr_ptr /* O - Locale conventions */
)
Return value (int) - returns
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_addr_ptr. The UniLconv structure is filled in according to the locale indicated by the locale object handle argument.
The UniLconv structure contains the following members:
struct UniLconv {
UniChar *decimal_point; /* non-monetary decimal point */
UniChar *thousands_sep; /* non-monetary thousands separator */
UniChar *grouping; /* non-monetary size of grouping */
UniChar *int_curr_symbol; /* international currency symbol and separator */
UniChar *currency_symbol; /* local currency symbol */
UniChar *mon_decimal_point; /* monetary decimal point */
UniChar *mon_thousands_sep; /* monetary thousands separator */
UniChar *mon_grouping; /* monetary size of grouping */
UniChar *positive_sign; /* non-negative values sign */
UniChar *negative_sign; /* negative values sign */
UniChar int_frac_digits; /* number of fractional digits - int currency */
UniChar frac_digits; /* number of fractional digits - local currency */
UniChar p_cs_precedes; /* (non-neg curr sym) 1-precedes, 0-succeeds */
UniChar p_sep_by_space; /* (non-neg curr sym) 1-space, 0-no space */
UniChar n_cs_precedes; /* (neg curr sym) 1-precedes, 0-succeeds */
UniChar n_sep_by_space; /* (neg curr sym) 1-space, 0-no space */
UniChar p_sign_posn; /* positioning of non-negative monetary sign */
UniChar n_sign_posn; /* positioning of negative monetary sign */
short os2_mondecpt; /* os2 curr sym positioning */
UniChar *debit_sign; /* non-negative-valued monetary symbol - "DB"*/
UniChar *credit_sign; /* negative-valued monetary symbol - "CR" */
UniChar *left_parenthesis; /* negative-valued monetary symbol - "(" */
UniChar *right_parenthesis; /* negative-valued monetary symbol - ")" */
}
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:
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.
#include <unidef.h>
int UniQueryLocaleItem (
const LocaleObject locale_object, /* I - Locale object */
LocaleItem item, /* I - Locale item to query */
UniChar **info_item_addr_ptr /* O - Locale information */
)
Return value (int) - returns
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 |
| LOCI_s1159 | AM string |
| LOCI_s2359 | PM string |
| LOCI_sAbbrevDayName7 | Abbreviation of day 7 (Sun) |
| LOCI_sAbbrevDayName1 | Abbreviation of day 1 (Mon) |
| LOCI_sAbbrevDayName2 | Abbreviation of day 2 (Tue) |
| LOCI_sAbbrevDayName3 | Abbreviation of day 3 (Wed) |
| LOCI_sAbbrevDayName4 | Abbreviation of day 4 (Thu) |
| LOCI_sAbbrevDayName5 | Abbreviation of day 5 (Fri) |
| LOCI_sAbbrevDayName6 | Abbreviation of day 6 (Sat) |
| LOCI_sDayName7 | Name of day of week 7 (Sun) |
| LOCI_sDayName1 | Name of day of week 1 (Mon) |
| LOCI_sDayName2 | Name of day of week 2 (Tue) |
| LOCI_sDayName3 | Name of day of week 3 (Wed) |
| LOCI_sDayName4 | Name of day of week 4 (Thu) |
| LOCI_sDayName5 | Name of day of week 5 (Fri) |
| LOCI_sDayName6 | Name of day of week 6 (Sat) |
| LOCI_sAbbrevMonthName1 | Abbreviation of month 1 |
| LOCI_sAbbrevMonthName2 | Abbreviation of month 2 |
| LOCI_sAbbrevMonthName3 | Abbreviation of month 3 |
| LOCI_sAbbrevMonthName4 | Abbreviation of month 4 |
| LOCI_sAbbrevMonthName5 | Abbreviation of month 5 |
| LOCI_sAbbrevMonthName6 | Abbreviation of month 6 |
| LOCI_sAbbrevMonthName7 | Abbreviation of month 7 |
| LOCI_sAbbrevMonthName8 | Abbreviation of month 8 |
| LOCI_sAbbrevMonthName9 | Abbreviation of month 9 |
| LOCI_sAbbrevMonthName10 | Abbreviation of month 10 |
| LOCI_sAbbrevMonthName11 | Abbreviation of month 11 |
| LOCI_sAbbrevMonthName12 | Abbreviation of month 12 |
| LOCI_sMonthName1 | Name of month 1 |
| LOCI_sMonthName2 | Name of month 2 |
| LOCI_sMonthName3 | Name of month 3 |
| LOCI_sMonthName4 | Name of month 4 |
| LOCI_sMonthName5 | Name of month 5 |
| LOCI_sMonthName6 | Name of month 6 |
| LOCI_sMonthName7 | Name of month 7 |
| LOCI_sMonthName8 | Name of month 8 |
| LOCI_sMonthName9 | Name of month 9 |
| LOCI_sMonthName10 | Name of month 10 |
| LOCI_sMonthName11 | Name of month 11 |
| LOCI_sMonthName12 | Name of month 12 |
| LOCI_sDecimal | Decimal point |
| LOCI_sThousand | Triad separator |
| LOCI_sYesString | Yes string |
| LOCI_sNoString | No string |
| LOCI_sCurrency | Currency symbol |
| LOCI_sCodeSet | Locale codeset |
| LOCI_xLocaleToken | IBM Locale Token |
| LOCI_xWinLocale | Win32 Locale ID |
| LOCI_iLocaleResnum | Resource number for description |
| LOCI_sNativeDigits | String of native digits |
| LOCI_iMaxItem | Maximum item number |
| LOCI_sTimeMark | Time mark (am/pm) format |
| LOCI_sEra | Era definition |
| LOCI_sAltShortDate | Alternate short date format string |
| LOCI_sAltDateTime | Alternate date and time format |
| LOCI_sAltTimeFormat | Alternate time format |
| LOCI_sAltDigits | XPG4 alternate digist |
| LOCI_sYesExpr | xpg4 yes expression |
| LOCI_sNoExpr | xpg4 no expression |
| LOCI_sDate | Short date separator |
| LOCI_sTime | Time separator |
| LOCI_sList | List separator |
| LOCI_sMonDecimalSep | Monetary currency separator |
| LOCI_sMonThousandSep | Monetary triad separator |
| LOCI_sGrouping | Grouping of digits |
| LOCI_sMonGrouping | Monetary groupings |
| LOCI_iMeasure | Measurement (Metric, British) |
| LOCI_iPaper | Normal paper size |
| LOCI_iDigits | Digits to right of decimal |
| LOCI_iTime | Clock format |
| LOCI_iDate | Format of short date |
| LOCI_iCurrency | Format of currency |
| LOCI_iCurrDigits | Digits to right for currency |
| LOCI_iLzero | Leading zero used |
| LOCI_iNegNumber | Format of negative number |
| LOCI_iLDate | Format of long date |
| LOCI_iCalendarType | Type of default calandar |
| LOCI_iFirstDayOfWeek | First day of week (0=Mon) |
| LOCI_iFirstWeekOfYear | First week of year |
| LOCI_iNegCurr | Format of negative currency |
| LOCI_iTLzero | Leading zero on time |
| LOCI_iTimePrefix | AM/PM preceeds time |
| LOCI_iOptionalCalendar | Alternate calandar type |
| LOCI_sIntlSymbol | International currency symbol |
| LOCI_sAbbrevLangName | Windows language abbreviation |
| LOCI_sCollate | Collation table |
| LOCI_iUpperType | Upper case algorithm |
| LOCI_iUpperMissing | Action for missing upper case |
| LOCI_sPositiveSign | Positive sign |
| LOCI_sNegativeSign | Negative sign |
| LOCI_sLeftNegative | Left paren for negative |
| LOCI_sRightNegative | Right paren for negative |
| LOCI_sLongDate | Long date formatting string |
| LOCI_sAltLongDate | Alternate long date format string |
| LOCI_sMonthName13 | Name of month 13 |
| LOCI_sAbbrevMonthName13 | Abbreviation of month 13 |
| LOCI_sName | OS/2 locale name |
| LOCI_sLanguageID | Abbreviation for language (ISO) |
| LOCI_sCountryID | Abbreviation for country (ISO) |
| LOCI_sEngLanguage | English name of Language |
| LOCI_sLanguage | Native name of language |
| LOCI_sEngCountry | English name of country |
| LOCI_sCountry | Name of country in current language |
| LOCI_sNativeCtryName | Name of country in native language |
| LOCI_iCountry | Country code |
| LOCI_sISOCodepage | ISO codepage name |
| LOCI_iAnsiCodepage | Windows codepage |
| LOCI_iCodepage | OS/2 primary codepage |
| LOCI_iAltCodepage | OS/2 alternate codepage |
| LOCI_iMacCodepage | Mac codepage |
| LOCI_iEbcdicCodepage | Ebcdic codepage |
| LOCI_sOtherCodepages | Other ASCII codepages |
| LOCI_sSetCodepage | Codpage to set on activation |
| LOCI_sKeyboard | Primary keyboard name |
| LOCI_sAltKeyboard | Alternate keyboard name |
| LOCI_sSetKeyboard | Keyboard to set on activation |
| LOCI_sDebit | Debit string |
| LOCI_sCredit | Credit string |
| LOCI_sLatin1Locale | Locale for Latin 1 names |
| LOCI_wTimeFormat | Win32 Time format |
| LOCI_wShortDate | Win32 Date format |
| LOCI_wLongDate | Win32 Long date format |
| LOCI_jISO3CountryName | Java Abbrev for country (ISO-3) |
| LOCI_jPercentPattern | Java percent pattern |
| LOCI_jPercentSign | Java percent symbol |
| LOCI_jExponent | Java exponential symbol |
| LOCI_jFullTimeFormat | Java full time format |
| LOCI_jLongTimeFormat | Java long time format |
| LOCI_jShortTimeFormat | Java short time format |
| LOCI_jFullDateFormat | Java full date format |
| LOCI_jMediumDateFormat | Java medium date format |
| LOCI_jDateTimePattern | Java date time format pattern |
| LOCI_jEraStrings | Java era strings |
This example shows how to retrieve locale information by item.
#include <stdio.h>
#include <unidef.h>
#include <uconv.h>
int main(void) {
UconvObject uconv_object = NULL;
LocaleObject locale_object = NULL;
UniChar *pinfo_item;
char char_buffer[50];
size_t buf_size = 50;
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 localized country name locale item */
/*****************************************************************/
rc = UniQueryLocaleItem(locale_object, LOCI_sCountry, &pinfo_item);
if (rc != ULS_SUCCESS) {
printf("UniQueryLocaleItem error: return code = %u\n", rc);
return 1;
}
/********************************************************************/
/* Create a conversion object for the current codepage */
/********************************************************************/
rc = UniCreateUconvObject((UniChar *)L"", &uconv_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateUconvObject error: return code = %u\n", rc);
return 1;
}
/*********************************************************************/
/* Convert the unicode string into a printable codepage string */
/*********************************************************************/
rc = UniStrFromUcs(uconv_object, char_buffer, pinfo_item, buf_size);
if(rc != ULS_SUCCESS) {
printf("UniStrFromUcs error: return code = %u\n", rc);
return 1;
}
printf("Localized country name is: %s\n", char_buffer );
/*********************************************************************/
/* Free the allocated memory */
/*********************************************************************/
rc = UniFreeMem(pinfo_item);
if (rc != ULS_SUCCESS) {
printf("UniFreeMem error: return code = %u\n", rc);
return 1;
}
UniFreeUconvObject(uconv_object);
if (rc != ULS_SUCCESS) {
printf("UniFreeUconvObject error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniQueryLocaleList returns a buffer filled with a list of the locales defined on the system.
#include <unidef.h>
int UniQueryLocaleList (
int flag, /* I - Indicates system or user defined locales */
UniChar *uniBuffer, /* O - Buffer for list of defined locales */
int numUniChars /* I - Maximum size of buffer */
)
The flag argument can take any of the following values, which are constants defined in the header unidef.h:
Return value (int) - returns
The flag parameter can be used to select either system defined locales or user defined locales. The system and user defined choices can be or'ed together to retrieve the complete list of locales.
Upon successful completion, uniBuffer will contain a list of locale names separated by null code elements.
The maximum length of an individual locale name (including the terminating null code element) is ULS_LNAMEMAX, which is a constant defined in unidef.h.
This example shows how to retrieve a list of locales available on the system.
#include <stdio.h>
#include <stdlib.h>
#include <unidef.h>
#include <uconv.h>
#define BUFFER_SIZE 2048
int main(void) {
UconvObject uconv_object = NULL;
UniChar *uniUsrLocales,
*ucbuf;
char char_buffer[ULS_LNAMEMAX];
int rc = ULS_SUCCESS,
offset;
/********************************************************************/
/* Query the list of user defined locales */
/********************************************************************/
uniUsrLocales = (UniChar *) calloc(BUFFER_SIZE, sizeof(UniChar));
rc = UniQueryLocaleList(UNI_USER_LOCALES, uniUsrLocales, BUFFER_SIZE);
if (rc != ULS_SUCCESS) {
printf("UniQueryLocaleList error: return code = %u\n", rc);
free(uniUsrLocales);
return 1;
}
/*********************************************************************/
/* Parse the null-terminated locale names from the UCS buffer */
/*********************************************************************/
printf("Defined user locales: ");
offset = 0;
while ((offset < BUFFER_SIZE) && (*(uniUsrLocales+offset) != 0)) {
ucbuf = uniUsrLocales + offset;
/* This simply prints the UCS locale name verbatim, which is fine if
* it contains only ASCII characters. However, in case it contains
* multilingual characters it would be better to convert it properly
* using a UconvObject and UniStrFromUcs().
*/
printf(" %ls", ucbuf );
offset += UniStrlen(ucbuf) + 1;
}
printf("\n");
free(uniUsrLocales);
return ULS_SUCCESS;
}
UniQueryLocaleObject retrieves the locale identifier.
#include <unidef.h>
int UniQueryLocaleObject (
const LocaleObject locale_object, /* I - Locale object */
int category, /* I - Locale category */
int LocaleSpecType, /* I - Locale identifier type */
void **locale_name /* O - Locale identifier */
)
The permissible values for category are:
These are as described under UniCreateLocaleObject.
Return value (int) - returns
UniQueryLocaleObject returns a pointer to a locale specification in the area pointed to by locale_name. UniQueryLocaleObject allocates memory to hold the generated value as necessary. Use UniFreeMem to free the memory associated with locale_name by UniQueryLocaleObject.
The value returned in the area pointed to by locale_name will point to either a string or a token, as indicated by the value of the LocaleSpecType argument.
When the LocaleSpecType argument is UNI_TOKEN_POINTER and the category argument is valid, a pointer to a token that represents the locale value associated with the category argument is returned, if such a token exists.
When the LocaleSpecType argument is UNI_MBS_STRING_POINTER or UNI_UCS_STRING_POINTER, UniQueryLocaleObject returns a pointer to a string that represents the locale value associated with the category argument.
When the LocaleSpecType argument is UNI_MBS_STRING_POINTER or UNI_UCS_STRING_POINTER and the category argument is LC_ALL, a string that represents the values of all of the locale categories of locale_object is returned. The returned string may be used as the LocaleSpec argument to UniCreateLocaleObject to create a locale object that is a functional equivalent of locale_object.
When the LocaleSpecType argument is UNI_MBS_STRING_POINTER or UNI_UCS_STRING_POINTER and the category argument is LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, or LC_TIME, a string that represents the value of the respective locale category of locale_object is returned. The returned string may be used as the LocaleSpec argument to UniCreateLocaleObject to create a locale object. All locale category values are set to the value of the queried locale category of locale_object.
If locale_object contains a NULL pointer, UniQueryLocaleObject returns a locale specification pointer identifying the respective categories of the default locale. If the category argument is LC_ALL, this value can be passed to UniCreateLocaleObject to create a locale object that is the functional equivalent of the current default locale, as specified by the environment variables of the current process.
If locale_object is invalid, the contents of locale_name are undefined and no memory is allocated.
This example shows how to retrieve a locale category name.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
UniChar *plocale_name;
int rc = ULS_SUCCESS;
/********************************************************************/
/* Retrieve locale name of default locale */
/********************************************************************/
rc = UniQueryLocaleObject(NULL, LC_ALL, UNI_UCS_STRING_POINTER,
(void **)&plocale_name);
if (rc != ULS_SUCCESS) {
printf("UniQueryLocaleObject error: return code = %u\n", rc);
return 1;
}
/********************************************************************/
/* Create a locale object based upon the default setting */
/********************************************************************/
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)plocale_name, &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
rc = UniFreeMem(plocale_name);
if (rc != ULS_SUCCESS) {
printf("UniFreeMem error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniQueryLocaleValue returns an integral value associated with the requested locale item.
#include <unidef.h>
int UniQueryLocaleValue (
const LocaleObject locale_object, /* I - Locale object */
LocaleItem item, /* I - Locale item to query */
int *info_item /* O - Locale item value */
)
Return value (int) - returns
UnyQueryLocaleValue is used to query locale items with integral values. These are indicated by the prefix "LOCI_i" or "LOCI_x" (see UniQueryLocaleItem for the complete list of locale items).
When a locale item is requested that does not have an integral value, -1 is returned to the caller.
This function provides a more convenient method of querying integral locale items compared to UniQueryLocaleItem.
This example shows how to retrieve the value for a locale item.
#include <stdio.h>
#include <unidef.h>
#include <ulsitem.h>
int main(void) {
LocaleObject locale_object = NULL;
ULONG pmCodepage;
int result = 0;
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;
}
rc = UniQueryLocaleValue(locale_object, LOCI_iCodepage,
(int *)&pmCodepage);
if (rc != ULS_SUCCESS) {
printf("UniQueryLocaleValue error: return code = %u\n", rc);
return 1;
}
printf("Presentation manager is using codepage %d\n", pmCodepage);
return ULS_SUCCESS;
}
UniQueryLower queries a Unicode character's lowercase (lower) attribute.
#include <unidef.h>
int UniQueryLower (
const LocaleObject locale_object, /* I - Locale object */
UniChar uc /* I - Character to query */
)
Return value (int) - returns
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
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'd'; /* Unicode lowercase Latin letter d */
/*****************************************************************/
/* 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 = UniQueryLower(locale_object, uni_char);
if (result)
printf("UniChar character %04X is a lowercase character\n", uni_char);
else
printf("UniChar character %04X is not a lowercase character\n", uni_char);
return ULS_SUCCESS;
}
UniQueryNumericValue returns the numeric value associated with a Unicode character.
#include <unidef.h>
int UniQueryNumericValue (
UniChar uc /* I - Character to query */
)
Return value (int)
The function returns -1 if unsuccessful. Otherwise, the numeric value of the Unicode character is returned.
This function returns numeric values for ranges of Unicode numeric characters. The function can be used to identify the digits, both decimal and hexadecimal, for Latin numbers, Arabic, Indian dialects, Laotian, Thai, Han and others represented in the Unicode character set.
This example shows how to query the numeric value of a character.
#include <stdio.h>
#include <unidef.h>
int main(void) {
int result = 0;
int rc = ULS_SUCCESS;
UNICTYPE *ct;
UniChar *uptr;
/* Set up a Unicode numeric character to test */
uptr = L'1';
/* Determine the characters type */
ct = UniQueryCharType(*uptr);
/* Test the Unicode character to see if it is a digit.
* It can be either decimal or hex.
*/
if ((ct->itype & CT_XDIGIT) || (ct->itype & CT_NUMBER)) {
num = UniQueryNumericValue(*uptr);
if (num == -1) {
printf("UniQueryNumericValue error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniQueryPrint queries a Unicode character's printable-character (print) attribute.
#include <unidef.h>
int UniQueryPrint (
const LocaleObject locale_object, /* I - Locale object */
UniChar uc /* I - Character to query */
)
Return value (int) - returns
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
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'd'; /* Unicode lowercase Latin letter d */
/*****************************************************************/
/* 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 = UniQueryPrint(locale_object, uni_char);
if (result)
printf("UniChar character %04X is a printable character\n", uni_char);
else
printf("UniChar character %04X is not a printable character\n", uni_char);
return ULS_SUCCESS;
}
UniQueryPunct queries a Unicode character's punctuation (punct) attribute.
#include <unidef.h>
int UniQueryPunct (
const LocaleObject locale_object, /* I - Locale object */
UniChar uc /* I - Character to query */
)
Return value (int) - returns
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
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 Latin question mark */
/*****************************************************************/
/* 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 = UniQueryPrint(locale_object, uni_char);
if (result)
printf("UniChar character %04X is a punctuation character\n", uni_char);
else
printf("UniChar character %04X is not a punctuation character\n", uni_char);
return ULS_SUCCESS;
}
UniQuerySpace queries a Unicode character's space-character (space) attribute.
#include <unidef.h>
int UniQuerySpace (
const LocaleObject locale_object, /* I - Locale object */
UniChar uc /* I - Character to query */
)
Return value (int) - returns
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
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 = UniQuerySpace(locale_object, uni_char);
if (result)
printf("UniChar character %04X is a space character\n", uni_char);
else
printf("UniChar character %04X is not a space character\n", uni_char);
return ULS_SUCCESS;
}
UniQueryStringType is used to query character types for a string.
#include <unidef.h>
ULONG UniQueryStringType (
UniChar *ustr, /* I - Unicode input string to be queried */
int size, /* I - Size of input string */
USHORT *outstr, /* O - Array of Unicode character types */
int kind /* I - Input string type */
)
Return value (ulong) - returns
Valid values for kind are:
This example shows how to query string types.
#include <unidef.h>
#include <stdlib.h>
/*
* CountJapanese: Count the number of Japanese chars in string
*/
int CountJapanese(UniChar * instr) {
int len;
USHORT * outbuf, * pout;
int count;
/* Get some memory to return the string */
len = UniStrlen(instr);
outbuf = malloc(len * sizeof(UniChar));
/* Query the extended character type of the string */
UniQueryStringType(instr, len, outbuf, CT_EXTENDED);
/* Search the returned array of types for Japanese chars */
count = 0;
pout = outbuf;
while (len--) {
if (*pout & (C3_KATAKANA|C3_HIRAGANA|C3_IDEOGRAPH)) {
count++;
}
pout++;
}
/* Free up type array and return */
free(outbuf);
return count;
}
UniQueryUpper queries a Unicode character's uppercase (upper) attribute.
#include <unidef.h>
int UniQueryUpper (
const LocaleObject locale_object, /* I - Locale object */
UniChar uc /* I - Character to query */
)
Return value (int) - returns
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
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'D'; /* Unicode uppercase Latin letter D */
/*****************************************************************/
/* 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 = UniQueryUpper(locale_object, uni_char);
if (result)
printf("UniChar character %04X is an uppercase character\n", uni_char);
else
printf("UniChar character %04X is not an uppercase character\n", uni_char);
return ULS_SUCCESS;
}
UniQueryXdigit queries a Unicode character's hexadecimal-digit (xdigit) attribute.
#include <unidef.h>
int UniQueryXdigit (
const LocaleObject locale_object, /* I - Locale object */
UniChar uc /* I - Character to query */
)
Return Value (int) - returns
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
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'D'; /* Unicode uppercase Latin letter D */
/*****************************************************************/
/* 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 = UniQueryXdigit(locale_object, uni_char);
if (result)
printf("UniChar character %04X is a hex digit\n", uni_char);
else
printf("UniChar character %04X is not a hex digit\n", uni_char);
return ULS_SUCCESS;
}
UniScanForAttr scans a Unicode string for an attribute match.
#include <unidef.h>
int UniScanForAttr (
AttrObject attr_object, /* I - Attribute object */
const UniChar *ucs, /* I - Unicode input string to be scanned */
size_t num_elems, /* I - Maximum number of characters to scan */
ulsBool inverse_op, /* I - Search type flag */
size_t *offset /* O - Position of first character found */
)
Return value (int) - returns
UniScanForAttr scans the array of code elements identified by ucs, from the position specified by ucs, searching for the first code element that matches or does not match the set of attributes specified by attr_object.
The inverse_op argument determines the rules for scanning and is an integer type containing one of the following values:
If inverse_op is set to FALSE, the function searches for the first code element that matches all of the attributes of the specified attr_object; if inverse_op is set to TRUE, the function searches for the first code element that matches none of the attributes of attr_object.
The search begins from the code element identified by ucs, through the next num_elems code elements. A non-negative integer identifying the location of the first code element meeting all of the criteria specified by attr_object is returned in the area pointed to by offset. This indicates the number of code elements offset from the code element identified by ucs, to the code element at which the attribute match is satisfied. If no code element meets the specified criteria, the contents of offset are undefined.
This example shows how to scan a Unicode string for an attribute match.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
AttrObject attr_object = NULL;
int result = 0;
int rc = ULS_SUCCESS;
size_t offset = 0;
UniChar *uni_char = L"os2";
/*****************************************************************/
/* 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"digit", &attr_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateAttrObject error: return code = %u\n", rc);
return 1;
}
/* Make call to determine if string matches attributes */
rc = UniScanForAttr(attr_object, uni_char, UniStrlen(uni_char),
FALSE, &offset);
if (rc != ULS_SUCCESS) {
printf("UniScanForAttr error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniSetUserLocaleItem is used to set a locale override for a locale item.
#include <unidef.h>
int UniSetUserLocaleItem (
UniChar *locale, /* I - Locale name */
int item, /* I - Locale item */
int type, /* I - Item type */
void *value /* I - New item value */
)
Return value (int) - returns
UniSetUserLocaleItem modifies an item in a user locale. This affects all users of that locale. After doing this function, a call to UniCompleteUserLocale is necessary to make the changes permanent.
This example shows how to set a user locale item.
#include <stdio.h>
#include <unidef.h>
int main(void) {
int rc = ULS_SUCCESS;
/*****************************************************************/
/* Set the time separator for John's locale to a period. (The */
/* user locale "Johns_Locale" is assumed to exist.) */
/* Note that this won't affect the time format strings like */
/* LOCI_sTimeFormat or LOCI_sDateTime (unless those are */
/* explicitly changed as well). */
/*****************************************************************/
rc = UniSetUserLocaleItem((UniChar *)L"Johns_Locale",
LOCI_sTime, 3, (UniChar *)L".");
if (rc != ULS_SUCCESS) {
printf("UniSetUserLocaleItem error: return code = %u\n", rc);
return 1;
}
/* Save all user locale changes */
rc = UniCompleteUserLocale();
if (rc != ULS_SUCCESS) {
printf("UniCompleteUserLocale error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniStrcat concatenates one Unicode string onto another.
#include <unidef.h>
UniChar *UniStrcat (
UniChar *ucs1, /* IO - String being appended to */
const UniChar *ucs2 /* I - String to append */
)
Return value (UniChar *) - returns
Concatenated string.
UniStrcat appends a copy of the Unicode string pointed to by ucs2 (including the terminating null code element) to the end of the Unicode string pointed to by ucs1. The initial code element of ucs2 overwrites the null code element at the end of ucs1. If copying takes place between objects that overlap, the results are unpredictable.
This example shows how to concatenate Unicode strings.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar ucs1[40] = L"computer";
UniChar *puni;
puni = UniStrcat(ucs1, (UniChar *)L" program");
return (ULS_SUCCESS);
}
UniStrchr searches for the first occurrence of a Unicode character within a string.
#include <unidef.h>
UniChar *UniStrchr (
const UniChar *ucs, /* I - String being searched */
UniChar uc /* I - Character to search for */
)
Return value (UniChar *)
UniStrchr returns either a pointer to the located code element or a null pointer, if the code element does not occur in the string.
UniStrchr locates the first occurrence of uc in the array of code elements pointed to by ucs. The terminating null code element is considered to be part of the string.
This example shows how to search a Unicode string for the first occurence of a code element.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar ucs1[] = L"computer program";
UniChar *puni;
UniChar uni_char = L'p';
puni = UniStrchr(ucs1, uni_char);
if(puni) {
printf("The character was found in the string\n");
return (ULS_SUCCESS);
}
}
UniStrcmp compares Unicode strings.
#include <unidef.h>
int UniStrcmp (
const UniChar *ucs1, /* I - First string to compare */
const UniChar *ucs2 /* I - Second string to compare */
)
Return value (int) - returns
UniStrcmp returns an integer greater than, equal to, or less than zero, according to whether the Unicode string pointed to by ucs1 is greater than, equal to, or less than the Unicode string pointed to by ucs2.
UniStrcmp compares the code element string pointed to by ucs1 to the code element string pointed to by ucs2.
This example shows how to compare Unicode strings.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar ucs1[] = L"computer";
UniChar ucs2[] = L"program";
int result = 0;
result = UniStrcmp(ucs1, ucs2);
if ( result == 0 )
printf("The strings are identical\n");
else
printf("The strings are not identical\n");
return (ULS_SUCCESS);
}
UniStrcmpi compares Unicode strings without sensitivity to case.
#include <unidef.h>
int UniStrcmpi (
const LocaleObject locale_object, /* I - Locale object for case conversion */
const UniChar *ucs1, /* I - First string to compare */
const UniChar *ucs2 /* I - Second string to compare */
)
Return value (int) - returns
UniStrcmpi compares ucs1 and ucs2 without sensitivity to case. All characters are converted to lowercase before the comparison. The locale object is used to convert the characters to lowercase. The locale may be specified as NULL to indicate default Unicode casing.
This example shows how to compare Unicode strings without sensitivity to case.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
UniChar ucs1[] = L"computer";
UniChar ucs2[] = L"COMPUTER";
int result = 0;
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;
}
result = UniStrcmpi(locale_object, ucs1, ucs2);
if ( result == 0 )
printf("The strings are identical\n");
else
printf("The strings are not identical\n");
return (ULS_SUCCESS);
}
UniStrcoll compares language collation strings.
#include <unidef.h>
int UniStrcoll (
const LocaleObject locale_object, /* I - Locale object */
const UniChar *ucs1, /* I - First string to compare */
const UniChar *ucs2 /* I - Second string to compare */
)
Return value (int) - returns
UniStrcoll compares the string pointed to by ucs1 to the string pointed to by ucs2, both interpreted as appropriate to the LC_COLLATE category of the locale indicated by the locale object handle argument, locale_object. The locale may be specified as NULL to indicate default Unicode collation.
This example shows how to compare Unicode strings using the collating sequence specified by the locale object.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
UniChar ucs1[] = L"axe";
UniChar ucs2[] = L"ant";
int result = 0;
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;
}
result = UniStrcoll(locale_object, ucs1, ucs2);
if ( result == 0 )
printf("The strings are identical\n");
else if ( result < 0 )
printf("String1 is less than String2\n");
else
printf("String1 is greater than String2\n");
return (ULS_SUCCESS);
}
UniStrcpy copies a Unicode string.
#include <unidef.h>
UniChar *UniStrcpy (
UniChar *ucs1, /* O - Target string */
const UniChar *ucs2 /* I - Source string */
)
Return value (UniChar *)
UniStrcpy returns ucs1.
UniStrcpy copies the Unicode string pointed to by ucs2 (including the terminating null code element) into the Unicode pointed to by ucs1. If copying takes place between objects that overlap, the results are unpredictable.
This example shows how to copy Unicode strings.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar ucs1[] = L"computer";
UniChar ucs2[10];
UniChar *puni;
puni = UniStrcpy(ucs2, ucs1);
}
UniStrcspn searches for the position of characters within a Unicode string.
#include <unidef.h>
size_t UniStrcspn (
const UniChar *ucs1, /* I - String to search */
const UniChar *ucs2 /* I - Characters to search for */
)
Return value (size_t)
UniStrcspn returns the index of the first character found in ucs1 which matches any character in ucs2.
If none of the characters in ucs2 occurs in ucs1, the return value will be equal to the number of code elements in ucs1.
The return value from UniStrcspn is equivalent to the length of the maximum initial substring of ucs1 which consists entirely of code elements not in ucs2.
This function is the inverse of UniStrspn.
This example shows how to search Unicode strings.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar ucs1[] = L"This is the source string";
UniChar ucs2[] = L"aces";
size_t result;
result = UniStrcspn(ucs1, ucs2);
if (result < UniStrlen(ucs1))
printf("The first matching character is at position: %d\n", result );
return (ULS_SUCCESS);
}
UniStrfmon converts a monetary value to a string.
#include <unidef.h>
int UniStrfmon (
const LocaleObject locale_object, /* I - Locale object */
UniChar *ucs, /* O - Target string */
size_t maxsize, /* I - Maximum length of string */
const UniChar *format, /* I - String formatting template */
... /* I - Template conversion arguments */
)
Return value (int)
If the total number of code elements, including the null terminating code element, is not more than maxsize, UniStrfmon returns the number of code elements placed into the array pointed to by ucs, not including the null terminating code element.
UniStrfmon converts numeric values to monetary strings. Characters are placed into the array pointed to by ucs, as controlled by the string pointed to by format. No more than maxsize code elements are placed into the array. The LC_MONETARY category of the locale indicated by locale_object governs the format of the conversion.
The format parameter specifies a character string that can contain plain characters and conversion specifications. Plain characters are copied to the output stream. Conversion specifications result in the fetching of zero or more arguments, which are converted and formatted.
If there are insufficient arguments for the format parameter, the results are undefined. If arguments remain after the format parameter is exhausted, the excess arguments are ignored.
A conversion specification sequence consists of a % (percent) sign, optional flags, optional field width, optional left precision, optional right precision, and a required conversion character that determine the conversion to be performed.
The locale may be specified as NULL to indicate C locale.
UniStrfmon can be called multiple times by including additional format structures, as specified by the format parameter.
One or more of the following flags can be specified to control the conversion:
FIELD WIDTH
LEFT PRECISION
If defined for the current locale and not suppressed with the ^ flag, grouping separators are inserted before the fill characters (if any) are added. Grouping separators are not applied to fill characters even if the fill character is a digit.
RIGHT PRECISION
CONVERSION CHARACTERS
This example shows how to convert a monetary value to a Unicode string using the specified locale object.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
UniChar ucs[20];
int max_size = 20;
int elements;
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;
}
/* elements contains number of code elements placed into ucs */
elements = UniStrfmon(locale_object, ucs,
max_size, (UniChar *)L"%n", 123.45);
return (ULS_SUCCESS);
}
UniStrftime formats date and time.
#include <unidef.h>
#include <time.h>
size_t UniStrftime (
const LocaleObject locale_object, /* I - Locale object */
UniChar *ucs, /* O - Target string */
size_t maxsize, /* I - Maximum length of string */
const UniChar *format, /* I - String formatting template */
const struct tm *timeptr /* I - Date/time to be formatted */
)
Return value (size_t)
If the total number of resulting code elements, including the null code element, is not more than maxsize, the number of code elements placed into the memory location addressed by ucs (not including the null code element) is returned. Otherwise, zero is returned and the contents of the memory location are indeterminate.
UniStrftime converts the internal time and date specification into a character string and places the null-terminated results in the array pointed to by ucs under the direction of format. No more than maxsize code elements are placed into the array. The characters that are converted are determined by the LC_TIME category of the locale indicated by locale_object and by the values in the time structure pointed to by timeptr. The results are unpredictable when objects being copied overlap.
The format parameter is a character string containing two types of objects: plain characters that are simply placed in the output string and conversion specifications that convert information from the timeptr parameter into readable form in the output string.
A % (percent sign) introduces a conversion specification.
The type of conversion is specified by one or two conversion characters. The characters and their meanings are:
Some conversion specifiers can be modified by the E or O modifier characters to indicate that an alternative format or specification should be used rather than the one normally used by the unmodified conversion specifier. If the alternative format or specification does not exist for the current locale, the behavior will be as if the unmodified conversion specification were used.
This example shows how to convert a date and time to a Unicode string using the specified locale object.
#include <stdio.h>
#include <time.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
struct tm *ptime;
time_t time_date;
UniChar ucs[30];
int max_size = 30;
int elements;
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;
}
time_date = time(NULL);
ptime = localtime(&time_date);
/* elements contains number of code elements placed into ucs */
elements = UniStrftime(locale_object, ucs,
max_size, (UniChar *)L"%a %b %d\n %I:%M %p",
ptime);
return (ULS_SUCCESS);
}
UniStrlen determines the length of a Unicode string.
#include <unidef.h>
size_t UniStrlen (
const UniChar *ucs /* I - Unicode string */
)
Return value (size_t)
UniStrlen returns the number of code elements that precede the terminating null code element.
UniStrlen computes the length of the code element string pointed to by ucs.
This example shows how to determine the code element count of a Unicode string.
#include <stdio.h>
#include <unidef.h>
int main(void) {
int elements;
/* elements contains number of code elements in the Unicode string */
elements = UniStrlen((UniChar *)L"program");
return (ULS_SUCCESS);
}
UniStrlwr converts a Unicode string to lowercase according to the language neutral case mapping tables.
#include <unidef.h>
UniChar *UniStrlwr (
UniChar *ucsUniStringIn /* I - String to convert */
)
Return value (UniChar *) - returns
Converted lowercase string.
The input string must be null-terminated.
This example shows how to convert a Unicode string to lowercase.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar *plwr_unistr;
/* plwr_unistr points to the converted lowercase Unicode string */
plwr_unistr = UniStrlwr((UniChar *)L"IBM");
return (ULS_SUCCESS);
}
UniStrncat concatenates up to a maximum number of characters from one Unicode string onto another.
#include <unidef.h>
UniChar *UniStrncat (
UniChar *ucs1, /* IO - String being appended to */
const UniChar *ucs2, /* I - String to append */
size_t n /* I - Number of characters to append */
)
Return value (UniChar *) - returns
Concatenated string.
UniStrncat appends not more than n code elements (a null code element and code elements that follow it are not appended) from the code element array pointed to by ucs2 to the end of the code element string pointed to by ucs1. The initial code element of ucs2 overwrites the null code element at the end of ucs1. A terminating null code element is always appended to the result. If copying takes place between objects that overlap, the results are unpredictable.
This example shows how to concatenate a specific number of code elements onto a Unicode string.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar ucs1[40] = L"computer";
size_t num_elems = 3;
UniStrncat(ucs1, (UniChar *)L" program", num_elems);
return (ULS_SUCCESS);
}
UniStrncmp compares up to a maximum number of characters from two Unicode strings.
#include <unidef.h>
int UniStrncmp (
const UniChar *ucs1, /* I - First string to compare */
const UniChar *ucs2, /* I - Second string to compare */
size_t n /* I - Number of characters to compare */
)
Return value (int) - returns
UniStrncmp returns an integer greater than, equal to, or less than zero. The integer returned depends on whether the possibly null-terminated code element array pointed to by ucs1 is greater than, equal to, or less than the possibly null-terminated code element array pointed to by ucs2.
UniStrncmp compares not more than n code elements (code elements that follow a null code element are not compared) from the code element array pointed to by ucs1 to the code element array pointed to by ucs2.
This example shows how to compare a specific number of code elements.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar ucs1[] = L"computer";
UniChar ucs2[] = L"computer program";
size_t num_elems = 3;
int result = 0;
result = UniStrncmp(ucs1, ucs2, num_elems);
if ( result == 0 )
printf("The strings are identical\n");
else
printf("The strings are not identical\n");
return (ULS_SUCCESS);
}
UniStrncmpi compares up to a maximum number of characters from two Unicode strings without sensitivity to case.
#include <unidef.h>
int UniStrncmpi (
const LocaleObject locale_object, /* I - Locale object for case conversion */
const UniChar *ucs1, /* I - First string to compare */
const UniChar *ucs2, /* I - Second string to compare */
const size_t n /* I - Number of characters to compare */
)
Return value (int) - returns
UniStrncmpi compares ucs1 and ucs2 without sensitivity to case. All n code elements are converted to lowercase before the comparison. The locale object is used to convert the characters to lowercase. A maximum of n code elements are compared. The locale may be specified as NULL to indicate Unicode casing.
This example shows how to compare a specific number of code elements without sensitivity to case.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object;
UniChar ucs1[] = L"COMPUTER";
UniChar ucs2[] = L"computer program";
size_t num_elems = 3;
int result = 0;
int rc;
/*****************************************************************/
/* 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;
}
result = UniStrncmpi(locale_object, ucs1, ucs2, num_elems);
if ( result == 0 )
printf("The strings are identical\n");
else
printf("The strings are not identical\n");
return (ULS_SUCCESS);
}
UniStrncpy copies a Unicode string up to a maximum number of characters.
#include <unidef.h>
UniChar *UniStrncpy (
UniChar *ucs1, /* O - Target string */
const UniChar *ucs2, /* I - Source string */
size_t n /* I - Number of characters to copy */
)
Return value (UniChar *)
UniStrncpy returns ucs1.
UniStrncpy copies not more than n code elements (code elements that follow a null code element are not copied) from the code element array pointed to by ucs2 to the code element array pointed to by ucs1. If copying takes place between objects that overlap, the results are unpredictable. If the code element array pointed to by ucs2 is a code element string that is shorter than n code elements, null code elements are appended to the copy in the code element array pointed to by ucs1, until n code elements, in all, have been written.
This example shows how to copy a specific number of code elements in a Unicode string.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar ucs1[] = L"computer";
UniChar ucs2[10];
UniChar *puni;
size_t num_elems = 4;
puni = UniStrncpy(ucs2, ucs1, num_elems);
return (ULS_SUCCESS);
}
UniStrpbrk searches for characters within a Unicode string.
#include <unidef.h>
UniChar *UniStrpbrk (
const UniChar *ucs1, /* I - String to search */
const UniChar *ucs2 /* I - Characters to search for */
)
Return value (UniChar *)
UniStrpbrk returns a pointer to the first character found in ucs1 which matches a character in ucs2, or a null pointer if ucs1 and ucs2 have no characters in common.
UniStrpbrk locates the first occurrence, in the string pointed to by ucs1, of any code element from the code element string pointed to by ucs2.
This example shows how to locate code elements in a Unicode string.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar ucs1[] = L"computer";
UniChar ucs2[] = L"put";
UniChar *puni;
puni = UniStrpbrk(ucs1, ucs2);
if (puni)
printf("The sub string was found\n");
return (ULS_SUCCESS);
}
UniStrptime converts date and time.
#include <unidef.h>
#include <time.h>
UniChar *UniStrptime (
const LocaleObject locale_object, /* I - Locale object */
const UniChar *buf, /* I - Source string */
const UniChar *fmt, /* I - String format specification */
struct tm *tm /* O - Converted date/time data */
)
Return value (UniChar *)
Returns a pointer to the character following the last character; otherwise, a NULL pointer is returned and the contents of the tm structure are undefined.
UniStrptime converts the character string pointed to by buf to a time value, which is stored in the structure pointed to by tm, using the format specified by fmt. A pointer to the character following the last character in the string pointed to by buf is returned.
The character string pointed to by fmt consists of field descriptors and text characters, similar to the scanf library function. Each field descriptor consists of a % character followed by another character that specifies the replacement for the field descriptor. The type of conversion is specified by one or two conversion characters. The characters and their meanings are specified in the Format Strings and Modified Directives sections.
FORMAT STRINGS
MODIFIED DIRECTIVES
Some directives can be modified by the E and O modifier characters to indicate that an alternative format or specification should be used rather than the one normally used by the unmodified directive. If the alternative format or specification does not exist in the current locale, the behavior will be as if the unmodified directive were used.
A format specification consisting of white-space characters is performed by reading input until the first nonwhite-space character (which is not read) or no more characters can be read.
A format specification consisting of an ordinary character is performed by reading the next character from the string parameter. If this character differs from the character comprising the directive, the directive fails and the differing character and any characters following it remain unread. Case is ignored when matching string items, such as month or weekday names.
This example shows how to convert a time date string to a time structure.
#include <stdio.h>
#include <time.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object;
UniChar uni_fmt[] = L"%A %b %d %r %Y";
UniChar uni_time_str[] = L"Wednesday Oct 23 03:07:00 PM 1995";
UniChar *puni;
struct tm convrt_time;
int rc;
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
(UniChar *)L"en_US", &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
puni = UniStrptime(locale_object, uni_time_str, uni_fmt,
&convrt_time);
if ( puni == NULL ) {
printf("UniStrptime error\n");
return (1);
}
else
return (ULS_SUCCESS);
}
UniStrrchr locates the last occurrence of a character in a Unicode string.
#include <unidef.h>
UniChar *UniStrrchr (
const UniChar *ucs, /* I - String to search */
UniChar uc /* I - Character to search for */
)
Return value (UniChar *)
UniStrrchr returns either a pointer to the found character, or a null pointer if uc does not occur in the Unicode string.
UniStrrchr locates the last occurrence of uc in the code element string pointed to by ucs. The terminating null code element is considered to be part of the string.
This example shows how to locate the last occurrence of a code element in a Unicode string.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar ucs[] = L"computer";
UniChar uc = L't';
UniChar *puni;
puni = UniStrrchr(ucs, uc);
if (puni)
printf("The character is contained in the string\n");
return (ULS_SUCCESS);
}
UniStrspn determines the length of the initial substring of a Unicode string that consists only of the specified characters.
#include <unidef.h>
size_t UniStrspn (
const UniChar *ucs1, /* I - String to search */
const UniChar *ucs2 /* I - Characters to search for */
)
Return value (size_t)
UniStrspn returns the index of the first character found in ucs1 which does not occur in ucs2.
If all of the characters in ucs1 occur in ucs2, the return value will be equal to the number of code elements in ucs1.
The return value from UniStrspn is equivalent to the length of the maximum initial substring of ucs1 which consists entirely of code elements from ucs2.
This function is the inverse of UniStrcspn.
This example shows how to determine the number of elements in a Unicode string.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar ucs1[] = L"computer";
UniChar ucs2[] = L"omc";
size_t num_elems = 0;
num_elems = UniStrspn(ucs1, ucs2);
if (num_elems > 0)
printf("The first %d characters were found\n", num_elems);
return (ULS_SUCCESS);
}
UniStrstr locates a substring within a Unicode string.
#include <unidef.h>
UniChar *UniStrstr (
const UniChar *ucs1, /* I - String to search */
const UniChar *ucs2 /* I - String to search for */
)
Return value (UniChar *)
UniStrstr returns either a pointer to the located substring, or a null pointer if the substring is not found.
If ucs2 points to a code element string with zero length, the function returns ucs1.
UniStrstr locates the first occurrence, in the Unicode string pointed to by ucs1, of the sequence of code elements (excluding the terminating null code element) specified in the Unicode string pointed to by ucs2.
This example shows how to locate a code element sequence in a Unicode string.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar ucs1[] = L"computer";
UniChar ucs2[] = L"put";
UniChar *puni;
puni = UniStrstr(ucs1, ucs2);
if (puni)
printf("The code element sequence was found\n");
return (ULS_SUCCESS);
}
UniStrtod converts a character string to double-precision floating point.
#include <unidef.h>
int UniStrtod (
const LocaleObject locale_object, /* I - Locale object */
const UniChar *nptr, /* I - String to convert */
UniChar **endptr, /* O - Leftover characters */
double *result /* O - Converted value */
)
Return value (int) - returns
UniStrtod converts the initial portion of the string pointed to by nptr to double-precision floating-point representation. First, it decomposes the input string into three parts:
Then, it attempts to convert the subject sequence to a floating-point number, and returns the result in the area pointed to by result. A pointer to the final string is stored in the object pointed to by endptr, provided that endptr is not a null pointer.
This example shows how to convert a Unicode string to a double precision floating point number.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object;
UniChar uni_string[] = L"3.1415926This stopped it";
UniChar *uni_stop_string;
double double_num;
int rc;
/*****************************************************************/
/* 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;
}
rc = UniStrtod(locale_object, uni_string, &uni_stop_string,
&double_num);
if (rc != ULS_SUCCESS) {
printf("UniStrtod error: return code = %u\n", rc);
return 1;
}
else {
printf("The double precision number is %f\n", double_num);
return (ULS_SUCCESS);
}
}
UniStrtok converts a Unicode string to tokens.
#include <unidef.h>
UniChar *UniStrtok (
UniChar *ucsString1, /* I - String to tokenize */
const UniChar *ucsString2 /* I - Delimiter characters */
)
ucsString1 is a string of zero or more tokens. The tokens in ucsString1 can be separated by one or more of the delimiters in ucsString2. UniStrtok does not support the passing of NULL for ucsString1 parameter as is supported in the ANSI C strtok function.
ucsString2 is the set of characters serving as delimiters of the tokens in ucsString1.
Return value (UniChar *) - returns
Pointer to the first token.
UniStrtok will return the first token in the string specified in ucsString1. UniStrtok replaces the delimiter character with 0x0000 and returns a pointer to the token.
This example shows how to tokenize a Unicode string.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar *uni_string = L"a string, of, ,tokens";
UniChar *puni_token;
int uni_len1;
int uni_len2;
int token_count = 0;
uni_len1 = UniStrlen(uni_string);
puni_token = UniStrtok(uni_string, (UniChar *)L",");
++token_count;
/* Continue to loop through the string looking for tokens */
do
{
uni_len2 = UniStrlen(puni_token) + 1;
puni_token += uni_len2;
if(puni_token < uni_string + uni_len1)
{
puni_token = UniStrtok(puni_token, (UniChar *)L",");
++token_count;
}
else
break;
} while (1);
printf("%d tokens were found\n", token_count);
return (ULS_SUCCESS);
}
UniStrtol converts a character string to a long integer.
#include <unidef.h>
int UniStrtol (
const LocaleObject locale_object, /* I - Locale object */
const UniChar *nptr, /* I - String to convert */
UniChar **endptr, /* O - Leftover characters */
int base, /* I - Number base (radix) */
long int *result /* O - Converted value */
)
Return value (int) - returns
The locale may be specified as NULL to indicate the C locale.
UniStrtol converts the initial portion of the string pointed to by nptr to long int representation. First, it decomposes the input string into three parts:
Then, it attempts to convert the subject sequence to an unsigned integer, and returns the result in the area pointed to by result. A pointer to the final string is stored in the object pointed to by endptr, provided that endptr is not a null pointer.
If the value of base is between 2 and 36, the letters a (or A) to z (or Z), inclusive, are ascribed the values 10 to 35. Only letters whose ascribed value is less than base are permitted.
If base is set to 0, the expected form of the subject sequence is a decimal, octal, or hexadecimal constant. Decimal constants begin with a nonzero digit. Octal constants begin with 0. Hexadecimal constants begin with 0x or 0X.
This example shows how to convert a Unicode string to a long integer.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object;
UniChar uni_string[] = L"110134932";
UniChar *uni_stop_string;
long int long_num;
int rc;
/*****************************************************************/
/* 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;
}
rc = UniStrtol(locale_object, uni_string, &uni_stop_string,
10, &long_num);
if (rc != ULS_SUCCESS) {
printf("UniStrtol error: return code = %u\n", rc);
return 1;
}
else {
printf("The long integer is %ld\n", long_num);
return (ULS_SUCCESS);
}
}
UniStrtoul converts a character string to an unsigned long integer.
#include <unidef.h>
int UniStrtoul (
const LocaleObject locale_object, /* I - Locale object */
const UniChar *nptr, /* I - String to convert */
UniChar **endptr, /* O - Leftover characters */
int base, /* I - Number base (radix) */
unsigned long int *result /* O - Converted value */
)
Return value (int) - returns
The locale may be specified as NULL to indicate the C locale.
UniStrtoul converts the initial portion of the string pointed to by nptr to unsigned long int representation. First, it decomposes the input string into three parts:
Then, it attempts to convert the subject sequence to an unsigned integer, and returns the result in the area pointed to by result. A pointer to the final string is stored in the object pointed to by endptr, provided that endptr is not a null pointer.
If the value of base is between 2 and 36, the letters a (or A) to z (or Z) inclusive are ascribed the values 10 to 35. Only letters whose ascribed value is less than base are permitted.
If base is set to 0, the expected form of the subject sequence is a decimal, octal or hexadecimal constant. Decimal constants begin with a nonzero digit. Octal constants begin with 0. Hexadecimal constants begin with 0x or 0X.
This example shows how to convert a Unicode string to an unsigned long integer.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object;
UniChar uni_string[] = L"110134932";
UniChar *uni_stop_string;
unsigned long int long_num;
int rc;
/*****************************************************************/
/* 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;
}
rc = UniStrtoul(locale_object, uni_string, &uni_stop_string,
10, &long_num);
if (rc != ULS_SUCCESS) {
printf("UniStrtoul error: return code = %u\n", rc);
return 1;
}
else {
printf("The unsigned long integer is %lu\n", long_num);
return (ULS_SUCCESS);
}
}
UniStrupr converts a Unicode string to uppercase according to the language neutral case mapping tables.
#include <unidef.h>
UniChar *UniStrupr (
UniChar *ucsUniStringIn /* I - String to convert */
)
Return value (UniChar *) - returns
Converted uppercase string.
The input string must be null-terminated.
This example shows how to uppercase Unicode strings according to the language neutral case mapping tables.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar ucs[] = L"computer";
UniChar *puni;
puni = UniStrupr(ucs);
return (ULS_SUCCESS);
}
UniStrxfrm transforms a character string into collating weights.
#include <unidef.h>
size_t UniStrxfrm (
const LocaleObject locale_object, /* I - Locale object */
UniChar *ucs1, /* O - Target string */
const UniChar *ucs2, /* I - Source string */
size_t n /* I - Size of target string */
)
Return value (size_t) - returns
UniStrxfrm returns the length of the transformed string (not including the terminating null code element). If the value returned is n or more, the contents of the array pointed to by ucs1 are indeterminate. If ucs1 is a null pointer, UniStrxfrm returns the number of elements required to contain the transformed character string.
UniStrxfrm transforms the string pointed to by ucs2 to values that represent character collating weights and places the resulting string into the array pointed to by ucs1. The transformation is such that, if UniStrcmp is applied to two transformed strings, it returns a value greater than, equal to, or less than 0, corresponding to the result of UniStrcoll applied to the same two original strings.
No more than n elements are placed into the resulting array pointed to by ucs1, including the terminating null code element. If n is zero, ucs1 is permitted to be a null pointer.
If copying takes place between objects that overlap, the results are unpredictable.
UniStrxfrm is controlled by the LC_COLLATE category of the locale as indicated by the locale object handle argument, locale_object. The locale may be specified as NULL to indicate Unicode collation.
This example shows how to collect character collating weights from Unicode strings using the specified locale object.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object = NULL;
UniChar *pucs1;
UniChar *pucs2 = L"computer";
int num_elems = 8;
int num_elems_trx = 0;
int result = 0;
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;
}
/********************************************************************/
/* Calculate the space needed for the collating weights */
/********************************************************************/
num_elems = UniStrxfrm (locale_object, NULL, pucs2, 0);
pucs1 = (UniChar *) malloc((num_elems + 1) * sizeof(UniChar));
if(!pucs1)
return 1;
/********************************************************************/
/* Obtain the collating weights for the Unicode string. */
/* num_elems_trx should be less than num_elems */
/********************************************************************/
num_elems_trx = UniStrxfrm (locale_object, pucs1,
pucs2, num_elems + 1);
if(num_elems_trx >= (num_elems + 1)) {
printf("UniStrxfrm error:\n");
return 1;
}
return (ULS_SUCCESS);
}
UniTolower converts a Unicode character to lowercase according to the language neutral case mapping tables.
#include <unidef.h>
UniChar UniTolower (
UniChar ucUniCharIn /* I - Character to convert */
)
Return value (UniChar) - returns
Converted lowercase character.
This example shows how to convert a Unicode character to lowercase according to the language neutral case mapping tables.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar uni_upr = L'C';
UniChar uni_lwr;
uni_lwr = UniTolower(uni_upr);
return (ULS_SUCCESS);
}
UniToupper converts a Unicode character to uppercase according to the language neutral case mapping tables.
#include <unidef.h>
UniChar UniToupper (
UniChar ucUniCharIn /* I - Character to convert */
)
Return value (UniChar) - returns
Converted uppercase character.
This example shows how to convert a Unicode character to uppercase according to the language neutral case mapping tables.
#include <stdio.h>
#include <unidef.h>
int main(void) {
UniChar uni_lwr = L'c';
UniChar uni_upr;
uni_upr = UniToupper(uni_lwr);
return (ULS_SUCCESS);
}
UniTransformStr transforms strings according to a XformObject created by UniCreateTransformObject.
#include <unidef.h>
int UniTransformStr (
XformObject xform_object, /* I - Transform object */
const UniChar *InpBuf, /* I - String to transform */
int *InpSize, /* IO - Number of characters to transform */
UniChar *OutBuf, /* O - Target string */
int *OutSize /* IO - Number of characters in target string */
)
Return value (int) - returns
UniTransformStr transforms a UniChar character string as specified by the transformation object handle xform_object for the LC_CTYPE category. This category applies to the locale object that was used to create the transformation handle xform_object (by UniCreateTransformObject). The text from the input buffer is transformed and the result is placed in the output buffer. Any characters not included in the transformation type referenced by xform_object are moved, to the output buffer, unchanged.
The InpSize argument, on input, specifies the number of code elements to be transformed. A value of -1 indicates that the input is delimited by a UniChar null character (0x0000). On return, the value is modified to the actual number of code elements processed in the source string.
The OutSize argument, on input, specifies the size of the output buffer (number of code elements). On return, the value is modified to the actual number of code elements placed in OutBuf.
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;
}
UniTransLower converts a Unicode character to lowercase using the specified locale.
#include <unidef.h>
UniChar UniTransLower (
const LocaleObject locale_object, /* I - Locale object for case conversion */
UniChar uc /* I - Character to convert */
)
Return value (UniChar)
UniTransLower returns the transformed character. The input character is returned if there is no transformation defined for the character in locale_object.
This example shows how to convert a Unicode character to lowercase.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object;
UniChar uni_upr = L'C';
UniChar uni_lwr;
int rc;
/*****************************************************************/
/* 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;
}
uni_lwr = UniTransLower(locale_object, uni_upr);
return (ULS_SUCCESS);
}
UniTransUpper converts a Unicode character to uppercase using the specified locale.
#include <unidef.h>
UniChar UniTransUpper (
const LocaleObject locale_object, /* I - Locale object for case conversion */
UniChar uc /* I - Character to convert */
)
Return value (UniChar)
This function returns the transformed character. The input character is returned if there is no transformation defined for the character in locale_object.
This example shows how to convert a Unicode character to uppercase.
#include <stdio.h>
#include <unidef.h>
int main(void) {
LocaleObject locale_object;
UniChar uni_lwr = L'c';
UniChar uni_upr;
int rc;
/*****************************************************************/
/* 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;
}
uni_upr = UniTransUpper(locale_object, uni_lwr);
return (ULS_SUCCESS);
}
It is expected that most of the processing by applications using the ULS will be done using UniChar* strings. However, many applications will need to export data to and import data from non-UCS encodings (for example, ASCII or EBCDIC). For this purpose, a set of functions is defined to perform conversions between UCS and non-UCS encodings. These functions are capable of doing only UCS conversions, such as converting to/from UCS.
Note: "UCS" and "Unicode" are used more or less interchangeably throughout this document. UCS refers to the encoding format (UCS-2) by which Unicode characters are represented: a UCS string is a Unicode string in the basic multilingual plane.
Non-UCS codepages (whose encoding is based on the char data type as opposed to UniChars) are referred to as "multi-byte character sets" (MBCS).
UniCreateUconvObject creates and initializes a Unicode conversion object.
#include <uconv.h>
int UniCreateUconvObject (
UniChar *cpname, /* I - UCS conversion specifier */
UconvObject *uconv_object /* O - Conversion object handle */
)
Return value (int) - returns
UniCreateUconvObject returns a conversion object that describes a UCS-2 conversion between the code page specified by cpname and UCS.
A conversion object remains valid until it is freed.
The cpname field is normally the Unicode string IBM- followed by the decimal number of the code page. Other names may be used. UCONV tables are kept in the \language\codepage directory on the boot drive.
If the cpname parameter contains an empty string, UniCreateUconvObject will create a conversion object based upon the value of the process codepage setting.
UniCreateUconvObject allows modifiers to be concatenated onto cpname; these modifiers change the default behavior of conversion objects. The caller can concatenate the following modifiers onto cpname.
Modifiers are separated from the conversion object name by an at sign (@), and multiple modifiers are separated by a comma (,).
displaymask
converttype
endian
The endian type can be one of the following:
For example
@endian=little
@endian=big:system
options
Examples of typical usage
IBM-942@path=yes,map=display
This example creates a conversion object based upon an IBM-942 encoding. When conversions are performed all strings will be treated as pathnames and all characters less than space will be considered to be glyphs.
@path=yes,sub=no
This example creates a conversion object based upon the current process codepage setting. When conversions are performed all strings will be treated as pathnames and no substitutions will occur.
IBM-850@path=no,sub=yes
This example creates a conversion object based upon an IBM-850 encoding. When conversions are performed all strings will be treated as non pathnames and substitutions will occur when converting to and from Unicode if necessary.
UniCreateUconvObject returns a conversion object in uconv_object for use in subsequent calls to UniUconvFromUcs / UniUconvToUcs or UniStrFromUcs / UniStrToUcs.
This example shows how to create a conversion object.
#include <stdio.h>
#include <uconv.h>
int main(void) {
UconvObject uconv_object = NULL;
int rc = ULS_SUCCESS;
/********************************************************************/
/* Create a conversion object based upon the process codepage */
/* setting with the path modifier enabled and the substitution */
/* character set to 0x3F ('?') */
/********************************************************************/
rc = UniCreateUconvObject((UniChar *)L"@path=yes,subchar=\\x3F",
&uconv_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateUconvObject error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniFreeUconvObject frees a conversion object.
#include <uconv.h>
int UniFreeUconvObject (
UconvObject uconv_object /* I - Conversion object */
)
Return value (int) - returns
UniFreeUconvObject closes the conversion object.
This example shows how to create and free a conversion object.
#include <stdio.h>
#include <uconv.h>
int main(void) {
UconvObject uconv_object = NULL;
int rc = ULS_SUCCESS;
/********************************************************************/
/* Create a conversion object based upon the process codepage */
/* setting with the path modifier enabled */
/********************************************************************/
rc = UniCreateUconvObject((UniChar *)L"@path=yes", &uconv_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateUconvObject error: return code = %u\n", rc);
return 1;
}
/********************************************************************/
/* Free the conversion object */
/********************************************************************/
rc = UniFreeUconvObject(uconv_object);
if (rc != ULS_SUCCESS) {
printf("UniFreeUconvObject error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniMapCpToUcsCp converts a code page number into a codepage represented as a UniChar string that is acceptable as input to UniCreateUconvObject.
#include <uconv.h>
int UniMapCpToUcsCp (
unsigned long ulCodepage, /* I - Codepage to convert */
UniChar *ucsCodepage, /* O - Output buffer */
size_t n /* I - Size of output buffer */
)
Return value (int) - returns
This example shows how to convert a codepage number to a Unicode string.
#include <stdio.h>
#include <uconv.h>
int main(void) {
UniChar ucs_code_page[12];
size_t num_elems = 12;
UconvObject uconv_object = NULL;
int rc = ULS_SUCCESS;
/********************************************************************/
/* Convert a code page number to a unichar string */
/********************************************************************/
rc = UniMapCpToUcsCp(850, ucs_code_page, num_elems);
if (rc != ULS_SUCCESS) {
printf("UniMapCpToUcsCp error: return code = %u\n", rc);
return 1;
}
rc = UniCreateUconvObject(ucs_code_page, &uconv_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateUconvObject error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniQueryUconvObject queries the attributes of a conversion object.
#include <uconv.h>
int UniQueryUconvObject (
UconvObject uobj, /* I - Conversion object */
uconv_attribute_t *attr, /* O - Conversion attributes */
size_t size, /* I - Size of attribute structure */
char first[ 256 ], /* O - Lead bytes for multibyte characters */
char other[ 256 ], /* O - Trailing bytes for multibyte characters */
udcrange_t udcrange[ 32 ] /* O - User defined character range */
)
Note: Some codepages may not set this flag correctly.
Return value (int) - returns
UniQueryUconvObject queries the attributes and characteristics of the given conversion object. The attributes are used to modify the default conversion.
The substitution character attributes specify to the conversion object how to perform in cases that there is no identical character for a given code element. UniQueryUconvObject may be used to query the substitution characters used by the conversion.
Some of these are static and bound to the conversion table; others are settable through UniSetUconvObject.
The attr, first, other, and udcrange parameters can be NULL to indicate that this data should not be returned.
See uconv_attribute_t to see the conversion object attributes; the structure indicates which fields can be queried and which can be set through UniSetUconvObject.
This example shows how to query a conversion object.
#include <stdio.h>
#include <uconv.h>
int main(void) {
uconv_attribute_t ucattr;
UconvObject uconv_object = NULL;
int rc = ULS_SUCCESS;
/********************************************************************/
/* Create a conversion object based upon the process codepage */
/* setting with the path modifier set */
/********************************************************************/
rc = UniCreateUconvObject((UniChar *)L"@path=yes", &uconv_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateUconvObject error: return code = %u\n", rc);
return 1;
}
/********************************************************************/
/* Query the conversion object */
/********************************************************************/
rc = UniQueryUconvObject(uconv_object, &ucattr,
sizeof(uconv_attribute_t), NULL, NULL, NULL);
if (rc != ULS_SUCCESS) {
printf("UniQueryUconvObject error: return code = %u\n", rc);
return 1;
}
/* Print the results */
printf("Version: %u\n",
ucattr.version );
printf("Minimum size of a codepage character: %u\n",
ucattr.mb_min_len );
printf("Maximum size of a codepage character: %u\n",
ucattr.mb_max_len );
printf("Minimum size of a UCS character: %u\n",
ucattr.usc_min_len );
printf("Maximum size of a UCS character: %u\n",
ucattr.usc_max_len );
printf("Encoding scheme ID: 0x%X\n",
ucattr.esid );
printf("Substitution flag: %u\n",
ucattr.options );
printf("Conversion state: %u\n",
ucattr.state );
printf("Endian type when converting to UCS: 0x%04X\n",
ucattr.endian.target );
printf("Endian type when converting from UCS: 0x%04X\n",
ucattr.endian.source );
printf("Display mask for characters below space: 0x%08X\n",
ucattr.displaymask );
printf("Conversion type: 0x%08X\n",
ucattr.converttype );
printf("Size of codepage substitution character: %u\n",
ucattr.subchar_len );
printf("Size of UCS substitution character: %u\n",
ucattr.subuni_len );
printf("Codepage substitution character: 0x");
for ( i = 0; i < ucattr.subchar_len; i++ )
printf("%02X", ucattr.subchar[i] );
printf("\n");
printf("UCS substitution character: 0x");
for ( i = 0; i < ucattr.subuni_len; i++ )
printf("%04X", ucattr.subuni[i] );
printf("\n");
/*********************************************************************/
/* Free the allocated memory */
/*********************************************************************/
rc = UniFreeUconvObject(uconv_object);
if (rc != ULS_SUCCESS) {
printf("UniFreeUconvObject error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniSetUconvObject sets the attributes of a conversion object.
#include <uconv.h>
int UniSetUconvObject (
UconvObject uconv_object, /* I - Conversion object */
uconv_attribute_t *attr_t /* I - Conversion attributes */
)
Return value (int) - returns
UniSetUconvObject sets the attributes of the given conversion object. The attributes are used to modify the default conversion. It is left up to each conversion to decide which attributes it will recognize.
The substitution character attributes specify to the conversion object how to perform in cases that there is no identical character for a given code element.
This example sets the displaymask to all display and path to yes, meaning all code points below space are mapped as glyphs and not as controls. It also treats data as pathnames. To modify only some attributes, a query should first be done using UniQueryUconvObject.
#include <stdio.h>
#include <uconv.h>
int main(void) {
uconv_attribute_t attr;
UconvObject uconv_object = NULL;
int rc = ULS_SUCCESS;
/********************************************************************/
/* Create a conversion object based upon the process codepage */
/* setting with the path modifier set */
/********************************************************************/
rc = UniCreateUconvObject((UniChar *)L"@path=yes", &uconv_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateUconvObject error: return code = %u\n", rc);
return 1;
}
/* Query the conversion object */
rc = UniQueryUconvObject(uconv_object, &attr,
sizeof(uconv_attribute_t), NULL,
NULL, NULL);
if (rc != ULS_SUCCESS) {
printf("UniQueryUconvObject error: return code = %u\n", rc);
return 1;
}
/* Turn the path modifier and display attributes on */
attr.converttype = attr.converttype | CVTTYPE_PATH;
attr.displaymask = DSPMASK_DISPLAY;
rc = UniSetUconvObject(uconv_object, &attr);
if (rc != ULS_SUCCESS) {
printf("UniSetUconvObject error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniUconvFromUcs converts a UCS string to a codepage string, with or without character substitution.
#include <uconv.h>
int UniUconvFromUcs (
UconvObject uconv_object, /* I - Conversion object */
UniChar **ucsbuf, /* IO - Input buffer */
size_t *UniCharsleft, /* IO - Input buffer size (UniChars) */
void **outbuf, /* IO - Output buffer */
size_t *outbytesleft, /* IO - Output buffer size (bytes) */
size_t *nonidentical /* IO - Substitution count */
)
Return value (int) - returns
UniUconvFromUcs updates the variables pointed to by the arguments to reflect the extent of the conversion and returns, in nonidentical, the number of substitution (nonidentical conversions) performed. If the entire string in the input buffer is converted, the value pointed to by UniCharsleft will be 0. If the input conversion is stopped due to any condition mentioned above, the value pointed to by UniCharsleft will be nonzero. If any error occurs, UniUconvToUcs returns a nonzero value.
UniUconvFromUcs converts a sequence of UCS code elements, in the array specified by ucsbuf, into a sequence of corresponding characters in another codepage, in the array specified by outbuf. The codepage of outbuf is the string specified in the UniCreateUconvObject call that returned the conversion object uconv_object. The ucsbuf argument points to a variable that points to the first UniChar code element in the input buffer, and UniCharsleft indicates the number of code elements in the buffer. The outbuf argument points to a variable that points to the first available character in outbuf, and outbytesleft indicates the number of bytes available to the end of the buffer.
If the output buffer outbuf is not large enough to hold the entire converted input, conversion stops just prior to the input code element that would cause the output buffer to overflow. The variable pointed to by ucsbuf is updated to point to the next code element following the last code element that was successfully converted. The value pointed to by outbytesleft is decremented to reflect the number of bytes still available in outbuf.
If UniUconvFromUcs encounters a code element in ucsbuf that is legal, but for which an identical character does not exist in the target codepage, then the character will be replaced with a predefined substitution character if the attributes of the conversion object so permit. If substitution is not permitted, an error is returned and conversion stops after the last successfully converted code element.
This example shows how to convert a Unicode string to codepage characters.
#include <stdio.h>
#include <uconv.h>
int main(void) {
UconvObject uconv_object = NULL;
int rc = ULS_SUCCESS;
size_t out_bytes_left;
size_t uni_chars_left;
size_t num_subs;
size_t char_buf_size = 50;
char char_buffer[50];
char *pout_char_str;
UniChar *pin_uni_str;
UniChar uni_data[] = L"UniCode string to convert";
/********************************************************************/
/* Create a conversion object based upon the process codepage */
/********************************************************************/
rc = UniCreateUconvObject((UniChar *)L"", &uconv_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateUconvObject error: return code = %u\n", rc);
return 1;
}
/*********************************************************************/
/* pin_uni_str points to the unicode string to be converted to */
/* codepage characters */
/*********************************************************************/
pout_char_str = char_buffer;
pin_uni_str = uni_data;
uni_chars_left = UniStrlen(pin_uni_str)+1;
out_bytes_left = char_buf_size;
/*********************************************************************/
/* Make call to convert unicode string to codepage characters */
/*********************************************************************/
rc = UniUconvFromUcs(uconv_object, &pin_uni_str, &uni_chars_left,
(void **)&pout_char_str, &out_bytes_left,
&num_subs);
if(rc != ULS_SUCCESS && uni_chars_left > 0) {
printf("UniUconvFromUcs error: return code = %u\n", rc);
printf("Unicode string was not completely converted\n");
return 1;
}
return ULS_SUCCESS;
}
UniUconvToUcs converts a codepage string to a UCS string, with or without character substitution.
#include <uconv.h>
int UniUconvToUcs (
UconvObject uconv_object, /* I - Conversion object */
void **inbuf, /* IO - Input buffer */
size_t *inbytesleft, /* IO - Input buffer size (bytes) */
UniChar **ucsbuf, /* IO - Output buffer */
size_t *UniCharsleft, /* IO - Output buffer size (UniChars) */
size_t *nonidentical /* IO - Substitution count */
)
Return value (int) - returns
UniUconvToUcs updates the variables pointed to by the arguments to reflect the extent of the conversion and returns, in nonidentical, the number of substitutions (non-identical conversions) performed. If the entire string in the input buffer is converted, the value pointed to by inbytesleft will be 0. If the input conversion is stopped due to any condition mentioned above, the value pointed to by inbytesleft will be nonzero and a nonzero value is returned to indicate the condition. If an error occurs, UniUconvToUcs returns a nonzero value.
UniUconvToUcs converts a sequence of characters encoded in one codepage, in the array specified by inbuf, into a sequence of corresponding UCS code elements, in the array specified by ucsbuf. The codepage of the inbuf is the string specified in the UniCreateUconvObject call that returned the conversion object uconv_object. The inbuf argument points to a variable that points to the first character in the input buffer, and inbytesleft indicates the number of bytes to the end of the buffer. The ucsbuf argument points to a variable that points to the first available UniChar code element in ucsbuf, and UniCharsleft indicates the number of code elements available to the end of the buffer.
If a sequence of bytes within inbuf does not form a valid character in the specified code page and substitution to UCS is not turned on, conversion stops after the last successfully converted character. If the input buffer ends with an incomplete character, conversion stops after the last successfully converted bytes.
If the output buffer ucsbuf is not large enough to hold the entire converted input, conversion stops just prior to the input bytes that would cause the output buffer to overflow. The variable pointed to by inbuf is updated to point to the byte following the last byte successfully used in the conversion. The value pointed to by UniCharsleft is decremented to reflect the number of code elements still available in ucsbuf.
This example shows how to convert codepage encoded characters to Unicode.
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <uconv.h>
int main(void) {
UconvObject uconv_object = NULL;
int rc = ULS_SUCCESS;
size_t in_bytes_left;
size_t uni_chars_left;
size_t num_subs;
int uni_buf_length = 50;
UniChar uni_buffer[50];
UniChar *pout_uni_str;
char char_data[] = "Character string to convert";
char *pin_char_str;
/********************************************************************/
/* Create a conversion object based upon the process codepage */
/********************************************************************/
rc = UniCreateUconvObject((UniChar *)L"", &uconv_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateUconvObject error: return code = %u\n", rc);
return 1;
}
/*********************************************************************/
/* pin_char_str points to the character string to be converted to */
/* Unicode characters */
/*********************************************************************/
pout_uni_str = uni_buffer;
pin_char_str = char_data;
uni_chars_left = uni_buf_length;
in_bytes_left = ( strlen(char_data) + 1 ) * sizeof(char);
/**********************************************************************/
/* Make call to convert codepage character string to a Unicode string */
/**********************************************************************/
rc = UniUconvToUcs(uconv_object, (void **)&pin_char_str, &in_bytes_left,
&pout_uni_str, &uni_chars_left,
&num_subs);
if(rc != ULS_SUCCESS && in_bytes_left > 0) {
printf("UniUconvToUcs error: return code = %u\n", rc);
printf("Character string was not completely converted to Unicode\n");
return 1;
}
return ULS_SUCCESS;
}
UniStrFromUcs converts a UCS string to a codepage string.
#include <uconv.h>
int UniStrFromUcs (
UconvObject uconv_object, /* I - Conversion object */
char *outbuf, /* O - Output buffer */
UniChar *ucsstr, /* I - Input buffer */
int size /* I - Output buffer size (bytes) */
)
Return value (int) - returns
UniStrFromUcs always performs conversions with substitution on.
UniStrFromUcs converts a sequence of code elements (up to and including the null terminator), in the array specified by ucsstr, into a sequence of corresponding characters in another codepage, in the array specified by outbuf. The code page of outbuf is the string specified in the UniCreateUconvObject call that returned the conversion object uconv_object. The ucsstr argument points to the first UniChar in the input buffer. The outbuf argument points to the first available character in the output buffer, and size indicates the number of bytes which the output buffer can hold.
If the outbuf buffer is not large enough to hold the entire converted input, conversion aborts and no data is written to outbuf.
If UniStrFromUcs encounters a code element in ucsstr that is legal, but for which an identical character does not exist in the target codepage, UniStrFromUcs replaces the character with a predefined substitution character.
This example shows how to convert a Unicode string to codepage characters.
#include <stdio.h>
#include <uconv.h>
int main(void) {
UconvObject uconv_object = NULL;
int rc = ULS_SUCCESS;
size_t buf_size = 50;
char char_buffer[50];
UniChar uni_data[] = L"UniCode string to convert";
/********************************************************************/
/* Create a conversion object based upon the process codepage */
/********************************************************************/
rc = UniCreateUconvObject((UniChar *)L"", &uconv_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateUconvObject error: return code = %u\n", rc);
return 1;
}
/*********************************************************************/
/* make call to convert unicode string to codepage characters */
/*********************************************************************/
rc = UniStrFromUcs(uconv_object, char_buffer, uni_data, buf_size);
if(rc != ULS_SUCCESS) {
printf("UniStrFromUcs error: return code = %u\n", rc);
printf("Unicode string was not completely converted\n");
return 1;
}
return ULS_SUCCESS;
}
UniStrToUcs converts a codepage string to a UCS string.
#include <uconv.h>
int UniStrToUcs (
UconvObject uconv_object, /* I - Conversion object */
UniChar *ucsbuf, /* O - Output buffer */
char *inbuf, /* I - Input buffer */
int size /* I - Output buffer size (UniChars) */
)
Return value (int) - returns
UniStrToUcs converts a sequence of characters encoded in one codepage, in the array specified by inbuf, into a sequence of corresponding UCS code elements in the array specified by ucsbuf. The codepage of the inbuf is the string specified in the UniCreateUconvObject call that returned the conversion object, uconv_object. The inbuf argument points to the first byte in the input buffer. The ucsbuf argument points to the first available UniChar in the output buffer, and size indicates the number of UniChar elements which the output buffer can hold.
If the ucsbuf buffer is not large enough to hold the entire converted input, conversion aborts and no data is written to ucsbuf.
This example shows how to convert codepage encoded characters to a Unicode string.
#include <stdio.h>
#include <uconv.h>
int main(void) {
UconvObject uconv_object = NULL;
int rc = ULS_SUCCESS;
size_t buf_size = 50;
char char_buffer[] = "Character string to convert";
UniChar uni_data[50];
/********************************************************************/
/* Create a conversion object based upon the process codepage */
/********************************************************************/
rc = UniCreateUconvObject((UniChar *)L"", &uconv_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateUconvObject error: return code = %u\n", rc);
return 1;
}
/*********************************************************************/
/* make call to convert codepage characters to unicode string */
/*********************************************************************/
rc = UniStrToUcs(uconv_object, uni_data, char_buffer, buf_size);
if (rc != ULS_SUCCESS) {
printf("UniStrToUcs error: return code = %u\n", rc);
printf("Character string was not completely converted to Unicode\n");
return 1;
}
return ULS_SUCCESS;
}
When a user presses a key on the keyboard, the device driver maps to the appropriate scan code. To process the translation of the scan code to a Unicode character or virtual function key, a set of ULS keyboard functions are provided.
The keyboard functions maintain a state that includes information about:
The keyboard functions include:
Loads a keyboard layout from the disk and returns a handle.
#include <unikbd.h>
int UniCreateKeyboard(
KHAND pkhand; /* O - Keyboard handle */
KBDNAME pname; /* I - Keyboard name */
ULONG mode; /* I - Reserved (must be 0) */
)
Return value (int) - returns
For a full list of error codes and their decimal and hexadecimal values, see Return Codes.
If the keyboard layout is already in use, a use count is incremented.
This example loads a keyboard layout and gets the handle.
#include <stdio.h>
#include <unikbd.h>
int main(void) {
KHAND kbdhandle;
KBDNAME *kbd_name;
ULONG mode = 0;
APIRET rc;
/***************************************************/
/* Create a keyboard handle for US keyboard layout */
/***************************************************/
kbd_name = (UniChar*)L"us";
rc = UniCreateKeyboard( &kbdhandle, kbd_name, mode );
if ( rc != ULS_SUCCESS ) {
printf("UniCreateKeyboard error: return code = %u\n", rc );
return 1;
}
return ULS_SUCCESS;
}
Closes a keyboard handle.
#include <unikbd.h>
int UniDestroyKeyboard(
KHAND khand; /* I - Keyboard handle */
)
Result value (int) - returns
For a full list of error codes and their decimal and hexadecimal values, see Return Codes.
This function closes the keyboard handle and decrements the use count. When the use count goes to zero, the handle associated with the keyboard is closed.
This example closes a keyboard handle.
#include <stdio.h>
#include <unikbd.h>
int main(void) {
KHAND kbdhandle;
KBDNAME *kbd_name;
ULONG mode = 0;
APIRET rc;
/***************************************************/
/* Create a keyboard handle for US keyboard layout */
/***************************************************/
kbd_name = (UniChar*)L"us";
rc = UniCreateKeyboard( &kbdhandle, kbd_name, mode );
if ( rc != ULS_SUCCESS ) {
printf("UniCreateKeyboard error: return code = %u\n", rc );
return 1;
}
rc = UniDestroyKeyboard( kbdhandle );
if ( rc != ULS_SUCCESS ) {
printf("UniDestroyKeyboard error: return code = %u\n", rc );
return 1;
}
return ULS_SUCCESS;
}
Queries information from the header in a keyboard table.
#include <unikbd.h>
int UniQueryKeyboard(
KHAND khand; /* I - Keyboard handle */
KEYBOARDINFO *pkbdinfo; /* O - Keyboard info structure */
)
Return value (int) - returns
For a full list of error codes and their decimal and hexadecimal values, see Return Codes.
This example queries information from a loaded keyboard table.
#include <stdio.h>
#include <unikbd.h>
int main(void) {
KHAND kbdhandle;
KBDNAME *kbd_name;
KEYBOARDINFO kbdinfo;
ULONG mode = 0;
APIRET rc;
/***************************************************/
/* Create a keyboard handle for US keyboard layout */
/***************************************************/
kbd_name = (UniChar*)L"us";
rc = UniCreateKeyboard( &kbdhandle, kbd_name, mode );
if ( rc != ULS_SUCCESS ) {
printf("UniCreateKeyboard error: return code = %u\n", rc );
return 1;
}
/* Query Keyboard Information Packet*/
rc = UniQueryKeyboard( kbdhandle, &kbdinfo );
if ( rc != ULS_SUCCESS ) {
printf("UniQueryKeyboard error: return code = %u\n", rc );
return 1;
}
return ULS_SUCCESS;
}
Resets the actual and effective shift states and LED status.
#include <unikbd.h>
int UniResetShiftState(
KHAND khand; /* I - Keyboard handle */
USHIFTSTATE *pUss; /* IO - New shift states */
ULONG type; /* I - Reset type */
)
Return value (int) - returns
For a full list of error codes and their decimal and hexadecimal values, see Return Codes.
UniResetShiftState is used when the shift state is changed other than through the normal key sequence. This allows the LED status to be maintained based on the shift state.
This example resets the shift state to release all pressed keys.
#include <stdio.h>
#include <unikbd.h>
int main(void) {
KHAND kbdhandle;
KBDNAME *kbd_name;
ULONG mode = 0;
USHIFTSTATE Uss = {0}; /* indicates no shift keys, toggle keys,
* dead keys, or layer keys are pressed.
*/
ULONG type;
APIRET rc;
/***************************************************/
/* Create a keyboard handle for US keyboard layout */
/***************************************************/
kbd_name = (UniChar*)L"us";
rc = UniCreateKeyboard( &kbdhandle, kbd_name, mode );
if ( rc != ULS_SUCCESS ) {
printf("UniCreateKeyboard error: return code = %u\n", rc );
return 1;
}
Uss.Shift = KBD_LEFTSHIFT | KBD_SHIFT; /* actual state is Left shift key */
Uss.Effective = KBD_SHIFT; /* effective state is shift key */
type = KEYEV_ZERO; /* Reset shift state status to indicate the release of all
* pressed and locked keys
*/
rc = UniResetShiftState( kbdhandle, &Uss, type );
if ( rc != ULS_SUCCESS ) {
printf("UniResetShiftState error: return code = %u\n", rc );
return 1;
}
return ULS_SUCCESS;
}
Translates a dead key and a Unicode character to a composite character.
#include <unikbd.h>
int UniTranslateDeadKey(
KHAND khand; /* I - Keyboard handle */
VDKEY *vdk; /* I - Dead key value */
UniChar inchar; /* I - Input character */
UniChar *outchar; /* O - Ouput composite character */
VDKEY *newdead; /* O - Output dead key value */
)
Return value (int) - returns
For a full list of error codes and their decimal and hexadecimal values, see Return Codes.
The calling program is expected to maintain the dead key state so that when a dead key is found, the next will be used to form the full character. After doing the dead key translate, the dead key state should be reset.
There is a provision in the tables for a dead key formed multiple dead keys, and this is used in the Japanese logic. It should not be used because OS/2 does not support chained dead keys.
This example translates a dead key and a Unicode character to a composite character.
#include <stdio.h>
#include <unikbd.h>
int main(void) {
KHAND kbdhandle;
KBDNAME *kbd_name;
ULONG mode = 0;
VDKEY invdk;
VDKEY outvdk;
UniChar inchar;
UniChar outchar;
APIRET rc;
/***************************************************/
/* Create a keyboard handle for US keyboard layout */
/***************************************************/
kbd_name = (UniChar*)L"us";
rc = UniCreateKeyboard( &kbdhandle, kbd_name, mode );
if ( rc != ULS_SUCCESS ) {
printf("UniCreateKeyboard error: return code = %u\n", rc );
return 1;
}
/**************************************************************************/
/* Translate following dead key and unicode to composite character tilde A*/
/**************************************************************************/
invdk = DK_TILDE;
inchar = 0x0041;
rc = UniTranslateDeadkey( kbdhandle, invdk, inchar, &outchar, &outvdk );
if ( rc != ULS_SUCCESS ) {
printf("UniTranslateDeadkey error: return code = %u\n", rc );
return 1;
}
return ULS_SUCCESS;
}
Translates a scan code and effective shift state to a Unicode and virtual and dead key. Sets the BIOS scan code.
#include <unikbd.h>
int UniTranslateKey(
KHAND khand; /* I - Keyboard handle */
ULONG eshift; /* I - Input shift state */
VSCAN scan; /* I - Input scan code */
UniChar *uc; /* O - Output character */
VDKEY *vdk; /* O - Output virtual or dead key */
BYTE *bscan; /* O - Output BIOS scan code */
)
Return value (int) - returns
For a full list of error codes and their decimal and hexadecimal values, see Return Codes.
In most cases, there is either a Unicode character or a PM (virtual) scan code. In a few cases (Esc, Tab, Backspace), both exists. It is normal when a dead key is returned to also return a Unicode character for the stand-alone character associated with the dead key.
The BIOS scan code is returned because the translation is dependent on the keyboard layout. This is done to emulate the earlier DOS and OS/2 keyboard layouts that allow the translated (BIOS) scan code to be set by the layout.
This example translates virtual scan code and effective shift state for [ to Unicode.
#include <stdio.h>
#include <unikbd.h>
int main(void) {
KHAND kbdhandle;
KBDNAME *kbd_name;
ULONG mode = 0;
USHIFTSTATE Uss = {0}; /* indicates no shift keys, toggle keys,
* dead keys, or layer keys are pressed.
*/
VSCAN v_scan;
BYTE makebreak;
UniChar uc;
VDKEY vk;
BYTE bscan;
APIRET rc;
/***************************************************/
/* Create a keyboard handle for US keyboard layout */
/***************************************************/
kbd_name = (UniChar*)L"us";
rc = UniCreateKeyboard( &kbdhandle, kbd_name, mode );
if ( rc != ULS_SUCCESS ) {
printf("UniCreateKeyboard error: return code = %u\n", rc );
return 1;
}
v_scan = 0x5B; /* PM scan code for [ */
makebreak = KEYEV_MAKE; /* indicate key is pressed down */
rc = UniUpdateShiftState( kbdhandle, &Uss, v_scan, makebreak );
if ( rc != ULS_SUCCESS ) {
printf("UniUpdateShiftState error: return code = %u\n", rc );
return 1;
}
rc = UniTranslateKey( kbdhandle, Uss.Effective, v_scan, &uc, &vk, &bscan );
if ( rc != ULS_SUCCESS ) {
printf("UniTranslateKey error: return code = %u\n", rc );
return 1;
}
return ULS_SUCCESS;
}
Translates a Unicode character and virtual or dead key to a scan code and creates the effective shift state.
#include <unikbd.h>
int UniUntranslateKey(
KHAND khand; /* I - Keyboard handle */
UniChar uc; /* I - Input character */
VDKEY vdk; /* I - Virtual or dead key */
VSCAN *pscan; /* O - Output scan code */
ULONG *eshift; /* O - Output shift state */
)
Return value (int) - returns
For a full list of error codes and their decimal and hexadecimal values, see Return Codes.
UniUntranslateKey does a reverse translation in respect to UniTranslateKey. This is used to create a complete keyboard packet when an already translated character is entered. This is used mostly when the input to the event is the translated character.
Normally, either the Unicode character, or the virtual or dead key is given. If both are given, UniUntranslateKey processes the virtual or dead key first.
This example translates a Unicode character to a scan code and creates the effective shift state.
#include <stdio.h>
#include <unikbd.h>
int main(void) {
KHAND kbdhandle;
KBDNAME *kbd_name;
ULONG mode = 0;
UniChar unichar;
VDKEY vdkey = 0;
VSCAN pscan;
ULONG eshift;
APIRET rc;
/***************************************************/
/* Create a keyboard handle for US keyboard layout */
/***************************************************/
kbd_name = (UniChar*)L"us";
rc = UniCreateKeyboard( &kbdhandle, kbd_name, mode );
if ( rc != ULS_SUCCESS ) {
printf("UniCreateKeyboard error: return code = %u\n", rc );
return 1;
}
/***********************************/
/* Untranslate Unicode character A */
/***********************************/
unichar = 0x0041;
rc = UniUntranslateKey( kbdhandle, unichar, vdkey, &pscan, &eshift );
if ( rc != ULS_SUCCESS ) {
printf("UniUntranslateKey error: return code = %u\n", rc );
return 1;
}
return ULS_SUCCESS;
}
Updates the actual and effective shift states and LED status.
#include <unikbd.h>
int UniUpdateShiftState(
KHAND khand; /* I - Keyboard handle */
USHIFTSTATE *pUss; /* IO - Shift state */
VSCAN v_scan; /* I - Input scan code */
BYTE makebreak; /* I - Make/break/repeat indicator */
)
Return value (int) - returns
For a full list of error codes and their decimal and hexadecimal values, see Return Codes.
UniUpdateShiftState modifies the shift state as required by the scan code, using the specified keyboard translation tables. The shift state consists of three parts:
The effective shift is equal to the 16 lower bits of the actual shift, but when a lock state modifies an actual shift (such as caps lock affecting shift), the effective shift is modified. This means that the effective shift is only correct for the specified scan code.
This example updates the shift state for a loaded keyboard table.
#include <stdio.h>
#include <unikbd.h>
int main(void) {
KHAND kbdhandle;
KBDNAME *kbd_name;
ULONG mode = 0;
USHIFTSTATE Uss = {0}; /* indicates no shift keys, toggle keys,
* dead keys, or layer keys are pressed.
*/
VSCAN v_scan;
BYTE makebreak;
APIRET rc;
/***************************************************/
/* Create a keyboard handle for US keyboard layout */
/***************************************************/
kbd_name = (UniChar*)L"us";
rc = UniCreateKeyboard( &kbdhandle, kbd_name, mode );
if ( rc != ULS_SUCCESS ) {
printf("UniCreateKeyboard error: return code = %u\n", rc );
return 1;
}
Uss.Shift = KBD_LEFTSHIFT; /* indicate left shift */
Uss.Effective = KBD_SHIFT; /* effective shift state */
v_scan = 0x61; /* scan code for a */
makebreak = KEYEV_MAKE; /* indicate key is pressed down */
rc = UniUpdateShiftState( kbdhandle, &Uss, v_scan, makebreak );
if ( rc != ULS_SUCCESS ) {
printf("UniUpdateShiftState error: return code = %u\n", rc );
return 1;
}
return ULS_SUCCESS;
}
The following data types are used by the Unicode functions.
AttrObject is used to determine character classifications.
typedef void *AttrObject;
Information about the source and target endian (byte order) of a Unicode string.
typedef struct _conv_endian_rec {
unsigned short source; /* Used by Uni*FromUcs */
unsigned short target; /* Used by Uni*ToUcs */
} conv_endian_t;
Each field can contain one of the following values:
Keyboard name.
typedef UniChar KBDNAME;
Query keyboard structure.
typedef struct _KEYBOARDINFO {
ULONG len; /* Length of structure. */
USHORT kbid; /* Keyboard architecture identifier. */
USHORT version; /* Version number. */
BYTE language[2]; /* Normal language. */
BYTE country[2]; /* Normal country. */
USHORT flags; /* Flags. */
USHORT resv; /* Reserved. */
UniChar description[32]; /* Description of keyboard. */
} KEYBOARDINFO;
typedef KEYBOARDINFO *PKEYBOARDINFO;
The following are the valid query keyboard flags:
| Flag | Hexadecimal value | Meaning |
|---|---|---|
| KBDF_DEFAULTVKEY | 0x0001 | Use default VKEYs. |
| KBDF_NOCTRLSHIFT | 0x0002 | Ctrl+Shift equals Ctrl. |
| KBDF_NOALTGR | 0x0004 | Alt graphics is not used. |
| KBDF_SHIFTALTGR | 0x0010 | Altgr, shift-altgr separate. |
| KBDF_DEADGOOD | 0x0020 | Invalid dead use second char. |
| KBDF_DEADPRIVATE | 0x0040 | Use only private dead keys. |
| KBDF_SYSTEM | 0x8000 | System supplied keyboard. |
| KBDF_INTERNATIONAL | 0x4000 | Full-range character set. |
| KBDF_DVORAK | 0x2000 | Alternate letter keys. |
| KBDF_NATIONAL | 0x1000 | National letter keys. |
| KBDF_LETTERKEYS | 0x3000 | Letter key type. |
| KBDF_ISOKEYS | 0x0800 | Use ISO icons for key names. |
Handle to translate table. typedef unsigned int KHAND;
LocaleItem is used to identify a language or cultural item within a locale.
typedef int LocaleItem;
LocaleObject is used by APIs that require language- or cultural-sensitive processing.
typedef void *LocaleObject;
LocaleToken is used as a shorthand method for identifying locales.
typedef unsigned int LocaleToken;
struct UniLconv describes the locale conventions.
struct UniLconv {
UniChar *decimal_point; /* non-monetary decimal point */
UniChar *thousands_sep; /* non-monetary thousands separator */
short *grouping; /* non-monetary size of grouping */
UniChar *int_curr_symbol; /* int'l currency symbol and separator */
UniChar *currency_symbol; /* local currency symbol */
UniChar *mon_decimal_point; /* monetary decimal point */
UniChar *mon_thousands_sep; /* monetary thousands separator */
short *mon_grouping; /* monetary size of grouping */
UniChar *positive_sign; /* non-negative values sign */
UniChar *negative_sign; /* negative values sign */
short int_frac_digits; /* no of fractional digits int currency */
short frac_digits; /* no of fractional digits loc currency */
short p_cs_precedes; /* nonneg curr sym 1-precedes,0-succeeds */
short p_sep_by_space; /* nonneg curr sym 1-space,0-no space */
short n_cs_precedes; /* neg curr sym 1-precedes,0-succeeds */
short n_sep_by_space; /* neg curr sym 1-space 0-no space */
short p_sign_posn; /* positioning of nonneg monetary sign */
short n_sign_posn; /* positioning of negative monetary sign */
short os2_mondecpt; /* os2 curr sym positioning */
UniChar *debit_sign; /* non-neg-valued monetary sym - "DB" */
UniChar *credit_sign; /* negative-valued monetary sym - "CR" */
UniChar *left_parenthesis; /* negative-valued monetary sym - "(" */
UniChar *right_parenthesis; /* negative-valued monetary sym - ")" */
} UNILCONV;
This structure describes the attributes and characteristics of a conversion object. All of these fields are queryable through UniQueryUconvObject. Some of the fields are settable through UniSetUconvObject; these are marked in the descriptions.
typedef struct _uconv_attribute_t {
unsigned long version; /* Q/S Version (must be zero) */
char mb_min_len; /* Q Minimum char size */
char mb_max_len; /* Q Maximum char size */
char usc_min_len; /* Q UCS min size */
char usc_max_len; /* Q UCS max size */
unsigned short esid; /* Q Encoding scheme ID */
char options; /* Q/S Substitution options */
char state; /* Q/S State for stateful convert */
conv_endian_t endian; /* Q/S Source and target endian */
unsigned long displaymask; /* Q/S Display/data mask */
unsigned long converttype; /* Q/S Conversion type */
unsigned short subchar_len; /* Q/S MBCS sub len 0=table */
unsigned short subuni_len; /* Q/S Unicode sub len 0=table */
char subchar[16]; /* Q/S MBCS sub characters */
UniChar subuni[8]; /* Q/S Unicode sub characters */
} uconv_attribute_t;
This identifies the environments for which a codepage is valid:
| Name | Value | Process | Display | VIO | GPI |
|---|---|---|---|---|---|
| ESID_sbcs_data | 0x2100 | x | x | x | x |
| ESID_sbcs_pc | 0x3100 | x | x | x | x |
| ESID_sbcs_ebcdic | 0x1100 | x | x | x | |
| ESID_sbcs_iso | 0x4100 | x | x | x | x |
| ESID_sbcs_windows | 0x4105 | x | x | x | x |
| ESID_sbcs_alt | 0xF100 | x | x | x | |
| ESID_dbcs_data | 0x2200 | x | x | ||
| ESID_dbcs_pc | 0x3200 | x | x | x | x |
| ESID_dbcs_ebcdic | 0x1200 | x | |||
| ESID_mbcs_data | 0x2300 | x | x | x | |
| ESID_mbcs_pc | 0x3300 | x | x | ||
| ESID_mbcs_ebcdic | 0x1301 | ||||
| ESID_ucs_2 | 0x7200 | ||||
| ESID_ugl | 0x72FF | ||||
| ESID_utf_8 | 0x7807 | x | x | x | |
| ESID_upf_8 | 0x78FF | x | x | x | x |
Substitution options can have one of these values, which are defined in uconv.h:
When set to 0, the conversion object is put into the base conversion state.
This is a 32-bit mask in which each bit represents a control character below space (1 << char). If the bit is 0, the character is treated as a display glyph. If the bit is 1, the character is treated as a control. There are several predefined values for this mask (defined in uconv.h), but any value can be used:
This is a mask in which the following flags exist, and can be ORed together (defined in uconv.h):
This can be a value between 0 and 13, but may not exceed the maximum size of a character in the encoding. A value of 0 indicates that the default substitution character (from the codepage conversion table) should be used.
This can be either 0 or 1. A value of 0 indicates that the default substitution character (from the Unicode conversion table) should be used.
This is the actual character value whose length is specified by subchar_len.
If subuni_len is set to 1, the first element in this array gives the Unicode substitution character.
UconvObject is used by APIs that convert to and from Unicode.
typedef void *UconvObject;
udcrange_t provides a set of ranges of characters that make up the user-defined character range.
typedef struct {
unsigned short first; /* First codepoint */
unsigned short last; /* Last codepoint */
} udcrange_t;
Boolean used with internationalization functions.
typedef int ulsBool;
A Unicode character (also referred to as a code element). Unicode is a universal character code that is independent of language and culture, and supports multiple simultaneous character sets.
Each UniChar is a two-byte value encoded according to the UCS-2 standard.
C wide character conventions may be used to handle UniChar characters and strings, under environments where wchar_t is an unsigned short integer.
typedef unsigned short UniChar;
The UNICTYPE structure provides a range of information regarding the type of a character.
typedef struct {
USHORT itype; /* CTYPE1 - xpg4 attributes */
CHAR bidi; /* CTYPE2 - Bidi attributes */
CHAR charset; /* CHARSET- Character set */
USHORT extend; /* CTYPE3 - Extended attributes */
USHORT codepage; /* Codepage mask (CCP) */
} UNICTYPE;
Unicode shift states.
typedef struct _USHIFTSTATE {
ULONG shift; /* Actual shift and lock state. */
ULONG Effective; /* Effective shift and lock state. */
ULONG Led; /* Keyboard indicators. */
} USHIFTSTATE;
typedef USHIFTSTATE *PUSHIFTSTATE;
Virtual or dead key.
typedef USHORT VDKEY;
Virtual scan code.
typedef UCHAR VSCAN;
An XformObject is used to perform string transformations.
typedef void *XformObject;
The following values may be returned by the various ULS functions.
| Hexadecimal value | Decimal value | Symbolic name(s) |
|---|---|---|
| 0x00000 | 0 | ULS_SUCCESS |
| 0x20401 | 132097 | ULS_OTHER UCONV_EOTHER |
| 0x20402 | 132098 | ULS_ILLEGALSEQUENCE UCONV_EILSEQ |
| 0x20403 | 132099 | ULS_MAXFILESPERPROC UCONV_EMFILE |
| 0x20404 | 132100 | ULS_MAXFILES UCONV_ENFILE |
| 0x20405 | 132101 | ULS_NOOP |
| 0x20406 | 132102 | ULS_TOOMANYKBD |
| 0x20407 | 132103 | ULS_KBDNOTFOUND |
| 0x20408 | 132104 | ULS_BADHANDLE |
| 0x20409 | 132105 | ULS_NODEAD |
| 0x2040A | 132106 | ULS_NOSCAN |
| 0x2040B | 132107 | ULS_INVALIDSCAN |
| 0x2040C | 132108 | ULS_NOTIMPLEMENTED UCONV_NOTIMPLEMENTED |
| 0x2040D | 132109 | ULS_NOMEMORY UCONV_ENOMEM |
| 0x2040E | 132110 | ULS_INVALID UCONV_EINVAL |
| 0x2040F | 132111 | ULS_BADOBJECT UCONV_EBADF |
| 0x20410 | 132112 | ULS_NOTOKEN |
| 0x20411 | 132113 | ULS_NOMATCH |
| 0x20412 | 132114 | ULS_BUFFERFULL UCONV_E2BIG |
| 0x20413 | 132115 | ULS_RANGE |
| 0x20414 | 132116 | ULS_UNSUPPORTED |
| 0x20415 | 132117 | ULS_BADATTR UCONV_BADATTR |
| 0x20416 | 132118 | ULS_VERSION |
Note: Symbolic names beginning with "UCONV_" are provided for compatibility with legacy code written for previous versions of the ULS API. Their use is discouraged.
This document is based in part on the following IBM publication, hereafter referred to as the IBM Unicode Functions Reference, which is governed by the legal notices listed below.
Unicode Functions (OS/2 Warp) – Second Edition (October 1997)
The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.
This publication was developed for products and services offered in the United States of America. IBM may not offer the products, services, or features discussed in this document in other countries, and the information is subject to change without notice. Consult your local IBM representative for information on the products, services, and features available in your area.
Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.
The following copyright notices apply to material in this document which is derived from the IBM Unicode Functions Reference.
COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface.
Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: "© (your company name) (year). All rights reserved."
© Copyright International Business Machines Corporation 1997. All rights reserved.
Note to U.S. Government Users: Documentation related to restricted rights - use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program or service is not intended to state or imply that only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, are the responsibility of the user.
IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
500 Columbus Avenue
Thornwood, NY 10594
U.S.A.
Asia-Pacific users can inquire, in writing, to the IBM Director of Intellectual Property and Licensing, IBM World Trade Asia Corporation, 2-31 Roppongi 3-chome, Minato-ku, Tokyo 106, Japan.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Department LZKS, 11400 Burnet Road, Austin, TX 78758 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The following terms are trademarks of the IBM Corporation in the United States or other countries or both:
The following terms are trademarks of other companies:
Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service marks of others.