Second Edition (October 1997)
This document describes the OS/2 Warp Universal Language Support (ULS) functions. These functions provide APIs and data types to support internationalization of applications.
This document is broken up into four major sections:
Locale and Character Classification Functions
Internationalized applications are required to operate in a variety of environments based on some territory, language, and/or cultural definition. These environments are identified by a locale, an object which encapsulates culturally specific information. The locale identifies the culture, language, and territory that it supports.
UniCompleteUserLocale is used to finish a locale modification. This API is called after one or more UniSetLocaleItem calls to cause the new user defined locale file to be saved.
Format
#include <unidef.h>
Parameters
None required.
Remarks
UniCompleteUserLocale is used to complete the process of defining a new locale or modifying an existing locale. An application will use the UniQueryLocale API's and UniSetUserLocaleItem API to take an existing locale definition and customize that definition to form a new locale. When the customization process is complete, the UniCompleteUserLocale API is invoked to save the results as a new locale.
The result of calling this API is that the locale is saved to disk as a new user locale or changes to an existing locale are saved to disk to represent the newly created locale.
Related Functions
Example
This example shows how to complete a user locale after modifying one or more locale items. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL; /* Array containing user locales */ UniChar *uniUsrLocales; int rc = ULS_SUCCESS; /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* allocate space for the user defined locales */ uniUsrLocales = (UniChar *) malloc(4096); /* Query the list of user defined locales available to modify */ rc = UniQueryLocaleList(UNI_USER_LOCALES, uniUsrLocales, 2048); if (rc != ULS_SUCCESS) { printf("UniQueryLocaleList error: return code = %u\n", rc); return 1; } . . . /* Change locale definition by calling UniSetUserLocaleItem to make locale item changes. */ . . . /* Write the current set of user locales to disk */ rc = UniCompleteUserLocale(); if (rc != ULS_SUCCESS) { printf("UniCompleteUserLocale error: return code = %u\n", rc); return 1; } return ULS_SUCCESS;
}
UniCreateAttrObject creates an attribute object that is used to determine character classifications.
Format
#include <unidef.h>
Remarks
UniCreateAttrObject allocates resources associated with an attribute defined in the LC_CTYPE category of the locale indicated by the locale_object argument.
The locale_object argument specifies a locale object handle returned by UniCreateLocaleObject. It should not be a NULL pointer.
The AttrName argument specifies the attribute names for which an attribute object handle should be created. Multiple attribute names are specified as a string of space-separated names.
When UniCreateAttrObject completes without errors, the attr_object argument specifies a valid pointer to an attribute object.
The attribute object pointer should be used in all subsequent calls to the UniQueryCharAttr. If the function result is other than ULS_SUCCESS, the contents of the area pointed to by attr_object are undefined.
The following attribute names are the base POSIX attributes. All attribute names which can be specified in UniQueryCharAttr are allowed. Those attributes which start with underscore (_) or hash (#) may not be combined with other attributes.
Related Functions
Example
This example shows how to create and use a character attribute object. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL;
AttrObject attr_object = NULL; int result = 0; int rc = ULS_SUCCESS; UniChar uni_char = L'a'; /* Unicode lowercase Latin letter a */ /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Create an alphabetic attribute object */ rc = UniCreateAttrObject(locale_object, (UniChar *)L"alpha", &attr_object); if (rc != ULS_SUCCESS) { printf("UniCreateAttrObject error: return code = %u\n", rc); return 1; } /* Make call to determine if character is alphabetic */ result = UniQueryCharAttr(attr_object, uni_char); if (result) printf("UniChar character %04X is alphabetic\n", uni_char); else printf("UniChar character %04X is not alphabetic\n", uni_char); return ULS_SUCCESS;
}
UniCreateLocaleObject creates a locale object.
Format
#include <unidef.h>
The constant names of the values of LocaleSpecType are defined in the header unidef.h:
Remarks
UniCreateLocaleObject creates a locale object for the locale specified by LocaleSpec. The object created is an opaque object containing all the data and methods necessary to perform the language-sensitive operations or functions that accept an argument of type LocaleObject. If the function is successful, all categories of the locale object are created and initialized.
When the LocaleSpec argument is a pointer to a character string (UCS character string or multibyte character string), it identifies the name of the locale to be initialized. The locale name is used to locate physical resources associated with this locale. The locale name UNIV is reserved and refers to the definitions that provide default behavior for functions.
When the LocaleSpec argument is a NULL pointer (without regard to the value of the LocaleSpecType argument), UniCreateLocaleObject creates a locale object for the UNIV locale.
When the LocaleSpec argument points to a locale token value as indicated by the value of the LocaleSpecType argument, the token identifies the locale to be initialized.
When the LocaleSpec argument is an empty multibyte or UCS character string, UniCreateLocaleObject creates a locale object based upon the settings of the locale environment variables.
Catgeory |
Precedence |
Usage |
|---|---|---|
LC_ALL |
Highest |
Setting LC_ALL takes precedence over any other locale environment variable. |
LC_COLLATE |
Equal precedence |
Specifies collation (sorting) rules. |
LC_CTYPE |
Equal precedence |
Specifies character classification and case conversion. |
LC_MESSAGES |
Equal precedence |
Specifies the values for affirmative and negative answers, and the language for displayed messages. |
LC_MONETARY |
Equal precedence |
Specifies monetary formats and currency symbol. |
LC_NUMERIC |
Equal precedence |
Specifies decimal formats. |
LC_TIME |
Equal precedence |
Specifies date and time formats. |
LANG |
Lowest |
Setting LANG takes precedence over any undefined locale environment variable. This may be used in conjunction with LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, and LC_TIME. |
If the specified locale is valid and supported, UniCreateLocaleObject allocates memory for the new object and returns the address of the created locale object in the area pointed to by locale_object. It is the application's responsibility to free this memory with a call to UniFreeLocaleObject when the object is no longer needed. If the function fails for any reason, the contents of the area pointed to by locale_object are undefined.
The locale token provides a shorthand notation for specifying a locale. The format of the locale token is as returned by a call to UniLocaleStrToToken. The format is defined as an unsigned integer of four octets.
Examples of typical usage:
The locale environment variables are set as follows:
LANG=de_DE
LC_MONETARY=en_US
The LocaleSpec argument is an empty multibyte or UCS character string.
This example creates a locale object with all categories set to de_DE except for LC_MONETARY which has the value of en_US.
The locale environment variables are set as follows:
LANG=fr_FR
The LocaleSpec argument is an empty multibyte or UCS character string.
This example creates a locale object with all categories set to fr_FR.
The locale environment variables are set as follows:
LC_ALL=it_IT
LANG=fr_FR
The LocaleSpec argument is an empty multibyte or UCS character string.
This example creates a locale object with all categories set to it_IT.
Related Functions
Example
This example shows how to create a locale object. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL;
int rc = ULS_SUCCESS; /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } return ULS_SUCCESS;
}
UniCreateTransformObject creates a string transform object.
Format
#include <unidef.h>
Returns
Remarks
UniCreateTransformObject obtains a transformation object for a transformation type as defined in the locale indicated by the locale_object argument. The function returns a transformation object that can be used as an argument in UniTransformStr.
The following transformation types are defined in all locales:
In addition to the above transformation-type names, other transformation-type names in the locale (including user-defined transformation-type names) may be passed to UniCreateTransformObject through the xtype argument. To obtain a successful return, the transformation-type name must be defined in locale_object.
When UniCreateTransformObject completes without errors, the xform_object argument value specifies a valid pointer to a transformation object. The transformation object should be used in all subsequent calls to UniTransformStr. If the function result is other than ULS_SUCCESS, the contents of the area pointed to by xform_object are undefined.
Related Functions
Example
This example shows how to create and use a transform object. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL;
XformObject xform_object = NULL; int rc = ULS_SUCCESS; int in_unistr_elem = 0; int out_unistr_elem = 10; UniChar *pin_unistr = (UniChar *)L"os2"; UniChar out_unistr[10]; /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Create an upper case transform object */ rc = UniCreateTransformObject(locale_object, (UniChar *)L"upper", &xform_object); if (rc != ULS_SUCCESS) { printf("UniCreateTransformObject error: return code = %u\n", rc); return 1; } /* Calculate the number of elements to transform */ in_unistr_elem = UniStrlen (pin_unistr) + 1; /* Make call to transform input string to uppercase */ rc = UniTransformStr(xform_object, pin_unistr, &in_unistr_elem, out_unistr, &out_unistr_elem); if (rc != ULS_SUCCESS) { printf("UniTransformStr error: return code = %u\n", rc); return 1; } return ULS_SUCCESS;
}
UniDeleteUserLocale is used to delete a locale created by a user.
Format
#include <unidef.h>
Parameters
Remarks
UniCompleteDeleteLocale is used to remove a previously defined user locale. The locale must have been previously created as a user locale. This is accomplished by using the UniCompleteUserLocale API.
Related Functions
Example
This example shows how to delete a user locale once it is no longer needed by the user. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL; /* Array containing user locales */ UniChar *uniUsrLocales; UniChar uniLocaleName[MAX_LOCALE_NAME_LENGTH]; int rc = ULS_SUCCESS; /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } . . . /* Identify the locale to be deleted - making sure the name is in Unicode. */ . . . /* Delete a user locale from the disk */ rc = UniDeleteUserLocale(uniLocaleName); if (rc != ULS_SUCCESS) { printf("UniDeleteUserLocale error: return code = %u\n", rc); return 1; } return ULS_SUCCESS;
}
UniFreeAttrObject frees the character attribute object.
Format
#include <unidef.h>
Returns
UniFreeAttrObject returns one of the following values:
Remarks
UniFreeAttrObject releases all resources associated with the character attribute object allocated by UniCreateAttrObject.
The attr_object argument specifies a previously allocated attribute object.
Related Functions
Example
This example shows how to create and free a character attribute object. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL;
AttrObject attr_object = NULL;
int rc = ULS_SUCCESS; /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Create an alphabetic attribute object */ rc = UniCreateAttrObject(locale_object, (UniChar *)L"alpha", &attr_object); if (rc != ULS_SUCCESS) { printf("UniCreateAttrObject error: return code = %u\n", rc); return 1; } /* Free the character attribute object */ rc = UniFreeAttrObject(attr_object); if (rc != ULS_SUCCESS) { printf("UniFreeAttrObject error: return code = %u\n", rc); return 1; } return ULS_SUCCESS;
}
UniFreeLocaleInfo frees a locale information structure created by UniQueryLocaleInfo.
Format
#include <unidef.h>
Returns
Related Functions
Example
This example shows how to create and free a locale information structure. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL; struct UniLconv *puni_lconv = NULL;
int rc = ULS_SUCCESS; /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Retrieve locale information */ rc = UniQueryLocaleInfo(locale_object, &puni_lconv); if (rc != ULS_SUCCESS) { printf("UniQueryLocaleInfo error: return code = %u\n", rc); return 1; } printf("Monetary decimal point is %ls\n", puni_lconv->mon_decimal_point); /* Free the locale information structure */ rc = UniFreeLocaleInfo(puni_lconv); if (rc != ULS_SUCCESS) { printf("UniFreeLocaleInfo error: return code = %u\n", rc); return 1; } return ULS_SUCCESS;
}
UniFreeLocaleObject frees a locale object that was created by UniCreateLocaleObject.
Format
#include <unidef.h>
Returns
Remarks
The UniFreeLocaleObject function destroys the locale object identified by locale_object and frees any memory associated with it.
Related Functions
Example
This example shows how to create and free a locale object. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL; int rc = ULS_SUCCESS; /* Create a locale object for French in Canada */ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"fr_CA", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Free the locale object that was just created */ rc = UniFreeLocaleObject(locale_object); if (rc != ULS_SUCCESS) { printf("UniFreeLocaleObject error: return code = %u\n", rc); return 1; } return ULS_SUCCESS;
}
UniFreeMem frees memory allocated by UniQueryLocaleObject.
Format
#include <unidef.h>
Returns
Remarks
UniFreeMem frees memory allocated by ULS functions. For example, the memory allocated for the locale_name parameter of UniQueryLocaleObject should be freed using UniFreeMem.
Example
This example shows how to free memory allocated by a ULS function. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL; int rc = ULS_SUCCESS; char *locale_name; /* Create a locale object for French in Canada */ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"fr_CA", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Determine the locale name for the LC_MESSAGES category */ rc = UniQueryLocaleObject(locale_object, LC_MESSAGES, UNI_MBS_STRING_POINTER, (void **)&locale_name); if (rc != ULS_SUCCESS) { printf("UniQueryLocaleObject error: return code = %u\n", rc); return 1; } /* Free the memory allocated by UniQueryLocaleObject */ rc = UniFreeMem((void **)locale_name); if (rc != ULS_SUCCESS) { printf("UniFreeMemObject error: return code = %u\n", rc); return 1; } return ULS_SUCCESS;
}
UniFreeTransformObject frees a string transformation object.
Format
#include <unidef.h>
Returns
Remarks
UniFreeTransformObject releases all resources associated with a transformation object previously obtained by UniCreateTransformObject.
Related Functions
Example
This example shows how to create and free a transform object. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL;
XformObject xform_object = NULL;
int rc = ULS_SUCCESS; /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Create an upper case transform object */ rc = UniCreateTransformObject(locale_object, (UniChar *)L"lower", &xform_object); if (rc != ULS_SUCCESS) { printf("UniCreateTransformObject error: return code = %u\n", rc); return 1; } /* Free the transform object created by UniCreateTransformObject */ rc = UniFreeTransformObject(xform_object); if (rc != ULS_SUCCESS) { printf("UniFreeTransformObject error: return code = %u\n", rc); return 1; } return ULS_SUCCESS;
}
UniLocaleStrToToken converts a locale specification string to a token.
Format
#include <unidef.h>
The LocaleStringType argument can take any of the following values, which are constants defined in the header unidef.h:
Returns
Remarks
UniLocaleStrToToken accepts, as an argument, a locale string qualified by the value of the LocaleStringType argument. It returns a locale token pointed to by locale_token if such a token exists for that locale string. UniLocaleStrToToken allocates memory to hold the locale token value. If no locale token exists for the supplied locale string, the value returned in locale_token is undefined.
Related Functions
Example
This example shows how to convert a locale specification string to a token. #include <stdio.h>
#include <unidef.h> int main(void) { UniChar *locale_string = L"de_DE"; /*German in Germany locale string */ LocaleToken locale_token;
int rc = ULS_SUCCESS; rc = UniLocaleStrToToken(UNI_UCS_STRING_POINTER, (void *)locale_string, &locale_token); if (rc != ULS_SUCCESS) { printf("UniLocaleStrToToken error: return code = %u\n", rc); return 1; } return ULS_SUCCESS;
}
UniLocaleTokenToStr converts a locale token to a locale specification string.
Format
#include <unidef.h>
An address of a pointer variable locale_string that will contain the locale specification string corresponding to locale_token.
Remarks
The UniLocaleTokenToStr() function accepts as an argument a locale token in locale_token and returns a pointer to a locale string in locale_string qualified by the LocaleStringType argument. The UniLocaleTokenToStr() function allocates memory to hold the locale string value. It is the application's responsibility to free the memory using UniFreeMem() when the locale string value is no longer needed. If no locale string can be generated for the supplied locale token, the value returned in locale_string is undefined.
Related Functions
Example
This example shows how to convert a locale token to a locale specification string. #include <stdio.h>
#include <unidef.h> int main(void) { UniChar *locale_string1 = L"de_DE"; /*German in Germany locale string */ UniChar *locale_string2;
LocaleToken locale_token;
int rc = ULS_SUCCESS; rc = UniLocaleStrToToken(UNI_UCS_STRING_POINTER, (void *)locale_string1, &locale_token); if (rc != ULS_SUCCESS) { printf("UniLocaleStrToToken error: return code = %u\n", rc); return 1; }
/* Convert the token to a locale string */
rc = UniLocaleTokenToStr(locale_token,
UNI_UCS_STRING_POINTER,
(void **)&locale_string2);
if (rc != ULS_SUCCESS) {
printf("UniLocaleTokenToStr error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniMakeUserLocale creates a user locale from a base system locale.
Format
#include <unidef.h>
Returns
Remarks
The names for the new locale and the base system locale must be ASCII-7 chars and at most eight characters, in length. An existing locale name must be given as the base locale name.
If the user locale already exists, a ULS_NOOP return code will be given, therefore, this API can always be called before making an update to ensure that the user locale exists.
Related Functions
Example
This example shows how to make a user locale. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL;
int rc = ULS_SUCCESS; UniChar *plocaleName; UniChar *puniSysLocale; /* Create current default locale object for this process */ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if(rc) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Query the name of the default locale object */ rc = UniQueryLocaleObject(locale_object, LC_ALL, UNI_UCS_STRING_POINTER, (void**)&plocaleName); if(rc) { printf("UniQueryLocaleObject error: return code = %u\n", rc); return 1; } /* Get the locale name from the locale object string */ puniSysLocale = UniStrtok(plocaleName, (UniChar *)L" "); /* Make a new locale */ rc = UniMakeUserLocale(puniSysLocale, puniSysLocale); if (rc) { printf("UniMakeUserLocale error: return code = %u\n", rc); return 1; } /* free the space used by the locale object string */ UniFreeMem(plocaleName); if(locale_object) UniFreeLocaleObject(locale_object); return ULS_SUCCESS;
}
UniMapCtryToLocale converts an unsigned long country code into a locale name represented as a UniChar string that is acceptable as input to other Unicode APIs.
Format
#include <unidef.h>
Returns
UniMapCtryToLocale returns one of the following values:
Related Functions
Example
This example shows how to map a country code to a locale name. #include <stdio.h>
#include <unidef.h> int main(void) { UniChar ucs_locale_name[8]; size_t num_elems = 8;
unsigned long country_num = 1;
LocaleObject locale_object = NULL;
int rc = ULS_SUCCESS;
/*****************************************************************/
/* Convert country number to a locale name */
/*****************************************************************/
rc = UniMapCtryToLocale(country_num, ucs_locale_name, num_elems);
if (rc != ULS_SUCCESS) {
printf("UniMapCtryToLocale error: return code = %u\n", rc);
return 1;
}
rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER,
ucs_locale_name, &locale_object);
if (rc != ULS_SUCCESS) {
printf("UniCreateLocaleObject error: return code = %u\n", rc);
return 1;
}
return ULS_SUCCESS;
}
UniQueryAlnum queries character attributes.
Format
#include <unidef.h>
Returns
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Example
This example shows how to query character attributes. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL; int result = 0; int rc = ULS_SUCCESS; UniChar uni_char = L'a'; /* Unicode lowercase Latin letter a */ /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Query character attribute */ result = UniQueryAlnum(locale_object, uni_char); if (result) printf("UniChar character %04X is alphanumeric\n", uni_char); else printf("UniChar character %04X is not alphanumeric\n", uni_char);
return ULS_SUCCESS;
}
UniQueryAlpha queries character attributes.
Format
#include <unidef.h>
Returns
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Example
This example shows how to query character attributes. #include <stdio.h>
#include <unidef.h> int main(void) { int result = 0; int rc = ULS_SUCCESS; UniChar uni_char = L'a'; /* Unicode lowercase Latin letter a */ /* Query character attribute */ result = UniQueryAlpha(NULL, uni_char); if (result) printf("UniChar character %04X is alphabetic\n", uni_char); else printf("UniChar character %04X is not alphabetic\n", uni_char);
return ULS_SUCCESS;
}
UniQueryAttr returns the value associated with attribute name supplied by the user.
Format
#include <unidef.h>
Returns
Remarks
This function provides the numeric value for the standard attributes such as alpha, graph, and number. In addition, this function provides the numeric value for other attributes such as Hiragana, diacritic, halfwidth etc. The table below contains the valid attribute names. Valid names are all in lower case.
Attribute names that begin with a lower case letter may be ORed together.
Attribute Name and Description Table
| Attr Name | Attribute Define | Description of Attribute |
| alnum | CT_ALNUM | Alphabetic and numeric characters |
| alpha | CT_ALPHA | Letters and linguistic marks |
| ascii | CT_ASCII | Standard ASCII character |
| blank | CT_BLANK | Space and Tab |
| cntrl | CT_CNTRL | Control and format characters |
| diacritic | C3_DIACRITIC | Diacritic |
| digit | CT_DIGIT | Digits 0 through 9 |
| fullwidth | C3_FULLWIDTH | Full width variant |
| graph | CT_GRAPH | All except controls and space |
| halfwidth | C3_HALFWIDTH | Half width variant |
| hiragana | C3_HIRAGANA | Hiragana character |
| ideograph | C3_IDEOGRAPH | Kanji/Han character |
| kashida | C3_KASHIDA | Arabic tatweel (used to stretch characters) |
| katakana | C3_KATAKANA | Katakana character |
| lower | CT_LOWER | Lower case alphabetic character |
| nonspacing | C3_NONSPACING | Non-spacing mark |
| nsdiacritic | C3_NSDIACRITIC | Non-spacing diacritic |
| nsvowel | C3_NSVOWEL | Non-spacing vowel |
| number | CT_NUMBER | Integers between 0 and 9 |
| CT_PRINT | Everything except control characters | |
| punct | CT_PUNCT | Punctuation marks |
| space | CT_SPACE | Whitespace and line ends |
| symbol | CT_SYMBOL | Symbol |
| upper | CT_UPPER | Upper case alphabetic character |
| vowelmark | C3_VOWELMARK | Vowel mark |
| xdigit | CT_XDIGIT | Hexadecimal digits (0-9, a-f or A-F) |
| _apl | CHS_APL | APL character |
| _arabic | CHS_ARABIC | Arabic character |
| _arrow | CHS_ARROW | Arrow character |
| _bengali | CHS_BENGALI | Bengali character |
| _bopomofo | CHS_BOPOMOFO | Bopomofo character |
| _box | CHS_BOX | Box or line drawing character |
| _currency | CHS_CURRENCY | Currency Symbol |
| _cyrillic | CHS_CYRILLIC | Cyrillic character |
| _dash | CHS_DASH | Dash character |
| _dingbat | CHS_DINGBAT | Dingbat |
| _fraction | CHS_FRACTION | Fraction value |
| _greek | CHS_GREEK | Greek character |
| _gujarati | CHS_GUJARATI | Gujarati character |
| _gurmukhi | CHS_GURMUKHI | Gurmukhi character |
| _hanguel | CHS_HANGUEL | Hanguel character |
| _hebrew | CHS_HEBREW | Hebrew character |
| _hiragana | CHS_HIRAGANA | Hiragana character set |
| _katakana | CHS_KATAKANA | Katakana character set |
| _lao | CHS_LAO | Laotian character |
| _latin | CHS_LATIN | Latin character |
| _linesep | CHS_LINESEP | Line separator |
| _math | CHS_MATH | Math symbol |
| _punctstart | CHS_PUNCTSTART | Punctuation start |
| _punctend | CHS_PUNCTEND | Punctuation end |
| _tamil | CHS_TAMIL | Tamil character |
| _telegu | CHS_TELEGU | Telegu character |
| _thai | CHS_THAI | Thai character |
| _userdef | CHS_USERDEF | User defined character |
| #arabicnum | C2_ARABICNUMBER | Arabic numbers |
| #blocksep | C2_BLOCKSEPARATOR | Block separator |
| #commonsep | C2_COMMONSEPARATOR | Common separator |
| #euronum | C2_EUROPENUMBER | European number |
| #eurosep | C2_EUROPESEPARATOR | European separator |
| #euroterm | C2_EUROPETERMINATOR | European terminator |
| #left | C2_LEFTTORIGHT | Left to right text orientation |
| #mirrored | C2_MIRRORED | Symmetrical text orientation |
| #neutral | C2_OTHERNEUTRAL | Other neutral |
| #right | CT_RIGHTTOLEFT | Right to left text orientation |
| #whitespace | C2_WHITESPACE | Whitespace |
Related Functions
Example
This example shows how to query character attribute values using the
character attributes.
#include <stdio.h>
#include <unidef.h>
int main(void) {
char name[33];
UniChar uname[33];
UniChar * up;
char * cp;
ulong rc;
/*
* Ask the user for an attribute name
*/
printf("Enter attribute name:");
scanf("%s", &name);
if (strlen(name) > 32)
return 1;
/*
* Convert name to unicode
*/
cp = name;
up = uname;
while (*cp) {
*up++ = (UniChar)(*cp++);
}
*up = 0;
/*
* Query the attribute and print the value
*/
rc = UniQueryAttr(tolower(uname));
if (rc == 0) {
printf("UniQueryAttr error: return code = %u\n", rc);
return 1;
} else
printf("%s attribute = %x\n", name, rc);
return ULS_SUCCESS;
}
UniQueryBlank queries character attributes.
Format
#include <unidef.h>
Returns
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Example
This example shows how to query character attributes. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL; int result = 0; int rc = ULS_SUCCESS; UniChar uni_char = L' '; /* Unicode space character */ /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Query character attribute */ result = UniQueryBlank(locale_object, uni_char); if (result) printf("UniChar character %04X is a blank character\n", uni_char); else printf("UniChar character %04X is not a blank character\n", uni_char);
return ULS_SUCCESS;
}
UniQueryChar determines if the character supplied has the attribute(s) requested.
Format
#include <unidef.h>
Returns
Remarks
This function takes the attributes supplied by the caller and tests the character to determine if they are true for that Unicode character. Attribute names that have a leading _ or # character represent classes of characters. These attributes must be tested as individual attributes. The remaining attributes can be or'ed together before testing.
Related Functions
Example
This example shows how to query if a character has particular attributes.
#include <stdio.h>
#include <unidef.h>
int main(void) {
int result = 0;
UniChar uni_char = L'A'; /* Unicode A character */
/* Query character for upper case and graphic attributes */
result = UniQueryChar(uni_char, C1_UPPER || C1_GRAPH);
if (result)
printf("UniChar is upper case and a graphic character\n");
else
printf("UniChar is not upper case and a graphic character\n"_;
/* Query character for Latin character set attribute */
result = UniQueryChar(uni_char, CHS_LATIN);
if (result)
printf("UniChar is a Latin character\n");
else
printf("UniChar is not a Latin character\n");
return ULS_SUCCESS;
}
UniQueryCharAttr queries the attributes of a character.
Format
#include <unidef.h>
Parameters
Returns
If the result of the test is false, UniQueryCharAttr returns the value 0.
Remarks
UniQueryCharAttr determines whether the code element uc has the attributes specified by the attribute object argument, attr_object.
Related Functions
Example
This example shows how to create and use a character attribute object. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL;
AttrObject attr_object = NULL; int result = 0; int rc = ULS_SUCCESS; UniChar uni_char = L'c'; /* Unicode lowercase Latin letter c */ /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Create an attribute object */ rc = UniCreateAttrObject(locale_object, (UniChar *)L"alpha xdigit", &attr_object); if (rc != ULS_SUCCESS) { printf("UniCreateAttrObject error: return code = %u\n", rc); return 1; } /* Make call to determine if character matches attributes */ result = UniQueryCharAttr(attr_object, uni_char); if (result) printf("UniChar character %04X matches attributes\n", uni_char); else printf("UniChar character %04X does not match attributes\n", uni_char); return ULS_SUCCESS;
}
UniQueryCharType is used to query the type of the character.
Format
#include <unidef.h>
Parameters
Returns
Remarks
UniQueryCharType is designed to provide information to support both the XPG/4 character type as well as the Win32 GetCharType type. Where the function is similar, this API is designed to be a superset of the Win32 function so that the Win32 functions can be supported by masking off bits in the returned data structure. GetCharType is similar to the C library "is" functions.
The UNICTYPE structure contains character set information, information regarding Bidirectional attributes, information regarding XPG/4 attributes and information on extended attributes.
Related Functions
Example
This example shows how to query a character type. #include <stdio.h>
#include <unidef.h> int main(void) { UNICTYPE * uct; UniChar uni_char = 0x3456; /* Some random Unicode character */ /* Query the character type */ uct = UniQueryCharType(uni_char); /* Examine the returned structure to determine information about the character. For example, what is its BiDi orientation and is the character Arabic or Hebrew? */ if (uct->bidi==C2_RIGHTTOLEFT) printf("Character is presented right to left\n"); else printf("Character is presented left to right\n"); if (uct->charset==CHS_ARABIC) printf("Character is Arabic\n"); else if (uct->charset==CHS_HEBREW) printf("Character is Hebrew\n"); else printf("Character is not Arabic or Hebrew\n"); return ULS_SUCCESS; }
UniQueryCharTypeTable is used to query the type of the character.
Format
#include <unidef.h>
Parameters
Returns
Remarks
UniQueryCharTypeTable is passed a pointer to a count and a pointer to a table of UNICTYPE structures. count is set to the number of entries in the UNICTYPE structure table. unictype is set to the first structure in the table.
Related Functions
Example
This example shows how to query a character type table.
#include <unidef.h>
#include <stdlib.h>
/*
* StringBidi: Determine bidi types for each character in a string
* Return string of bidi bits, and return value with
* OR of all bits.
*/
USHORT StringBidi(UniChar * instr, USHORT * charsets) {
ULONG count;
UNICTYPE * typetab;
USHORT index, *pcs, out;
int rc, i, len;
/*
* Get addressability to the character type table
*/
UniQueryCharTypeTable (&count, &typetab);
/*
* Create an output string
*/
len = UniStrlen(instr);
UniQueryStringType(instr, len, charsets, CT_INDEX);
/*
* Replace each index with bidi flags
*/
pcs = charsets;
out = 0;
for (i=0; i<len; i++) {
index = *pcs;
*pcs = 0;
if (typetab[index].bidi == C2_RIGHTTOLEFT)
*pcs |= 1;
if (typetab[index].charset == CHS_ARABIC)
*pcs |= 2;
if (typetab[index].charset == CHS_HEBREW)
*pcs |= 4;
out |= *pcs++;
}
return out;
}
UniQueryCntrl queries character attributes.
Format
#include <unidef.h>
Returns
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Related Functions
Example
This example shows how to query character attributes. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL; int result = 0; int rc = ULS_SUCCESS; UniChar uni_char = 0x000A; /* Unicode newline character */ /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Query character attribute */ result = UniQueryCntrl(locale_object, uni_char); if (result) printf("UniChar character %04X is a control character\n", uni_char); else printf("UniChar character %04X is not a control character\n", uni_char);
return ULS_SUCCESS;
}
UniQueryCountryName returns the name of the country in the language specified.
Format
#include <unidef.h>
Parameters
Remarks
This function only queries system provided locales to determine valid country names.
Related Functions
Example
This example shows how to query a country name. #include <stdio.h>
#include <unidef.h> #include <ulsitem.h> int main(void) { LocaleObject locale_object = NULL; int result = 0; int rc = ULS_SUCCESS; UniChar *pinfo; UniChar *langName; UniChar *countryName; UniChar *mriLanguage; UniChar uni_char = L'5'; /* Unicode number 5 character */ /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Determine the language to get the country name in */ rc = UniQueryLocaleItem(locale_object, LOCI_sLanguageID, &mriLanguage); if (rc != ULS_SUCCESS) { printf("UniQueryLocaleItem error: return code = %u\n", rc); return 1; } /* Get the ISO country ID rc = UniQueryLocaleItem(locale_object, LOCI_sCountryID, &pinfo); if (rc != ULS_SUCCESS) { printf("UniQueryLocaleItem error: return code = %u\n", rc); return 1; } /* Now we can determine the country name in the proper language */ rc = UniQueryCountryName(pinfo, mriLanguage, &countryName); if (rc != ULS_SUCCESS) { printf("UniQueryCountryName error: return code = %u\n", rc); return 1; } printf("Country name is = %ls\n", countryName);
return ULS_SUCCESS;
}
UniQueryDigit queries character attributes.
Format
#include <unidef.h>
Parameters
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Example
This example shows how to query character attributes. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL; int result = 0; int rc = ULS_SUCCESS; UniChar uni_char = L'5'; /* Unicode number 5 character */ /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Query character attribute */ result = UniQueryDigit(locale_object, uni_char); if (result) printf("UniChar character %04X is a digit\n", uni_char); else printf("UniChar character %04X is not a digit\n", uni_char);
return ULS_SUCCESS;
}
UniQueryGraph queries character attributes.
Format
#include <unidef.h>
Parameters
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Example
This example shows how to query character attributes. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL; int result = 0; int rc = ULS_SUCCESS; UniChar uni_char = L'S'; /* Unicode Latin uppercase letter S */ /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Query character attribute */ result = UniQueryGraph(locale_object, uni_char); if (result) printf("UniChar character %04X is a graphic character\n", uni_char); else printf("UniChar character %04X is not a graphic character\n", uni_char);
return ULS_SUCCESS;
}
UniQueryLanguageName returns the name of the language in the language specified.
Format
#include <unidef.h>
Parameters
Remarks
This function only queries system provided locales to determine valid language names.
Related Functions
Example
This example shows how to query a language name. #include <stdio.h>
#include <unidef.h> #include <ulsitem.h> int main(void) { LocaleObject locale_object = NULL; int result = 0; int rc = ULS_SUCCESS; UniChar *pinfo; UniChar *languageName; UniChar *mriLanguage; UniChar uni_char = L'5'; /* Unicode number 5 character */ /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Determine the language to get the language name in */ rc = UniQueryLocaleItem(locale_object, LOCI_sLanguageID, &mriLanguage); if (rc != ULS_SUCCESS) { printf("UniQueryLocaleItem error: return code = %u\n", rc); return 1; } /* Get the ISO country ID rc = UniQueryLocaleItem(locale_object, LOCI_sLanguageID, &pinfo); if (rc != ULS_SUCCESS) { printf("UniQueryLocaleItem error: return code = %u\n", rc); return 1; } /* Now we can determine the country name in the proper language */ rc = UniQueryCountryName(pinfo, mriLanguage, &languageName); if (rc != ULS_SUCCESS) { printf("UniQueryCountryName error: return code = %u\n", rc); return 1; } printf("Language name is = %ls\n", languageName);
return ULS_SUCCESS;
}
UniQueryLocaleInfo retrieves information about locale conventions.
Format
#include <unidef.h>
Remarks
UniQueryLocaleInfo retrieves information from the locale indicated by the locale_object argument and places the information in a UniLconv structure. UniQueryLocaleInfo allocates memory to hold the UniLconv structure. It is the application's responsibility to free the memory with UniFreeLocaleInfo when the UniLconv structure is no longer needed. The address of the UniLconv structure is returned in UniLconv_struct. The UniLconv structure is filled in, according to the locale indicated by the locale object handle argument.
The UniLconv structure contains the following members:
The value of grouping and mon_grouping is interpreted according to the following:
The next element is examined to determine the size of the next group of digits before the current group.
The n_sign_posn and p_sign_posn elements are interpreted according to the following:
Related Functions
Example
This example shows how to retrieve information about locale conventions. #include <stdio.h> #include <unidef.h>
int main(void) { LocaleObject locale_object = NULL; struct UniLconv *puni_lconv = NULL;
int rc = ULS_SUCCESS; /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Retrieve locale information */ rc = UniQueryLocaleInfo(locale_object, &puni_lconv); if (rc != ULS_SUCCESS) { printf("UniQueryLocaleInfo error: return code = %u\n", rc); return 1; } /* print the value of the os2 currency symbol position */ printf("The os2 currency symbol position is %d\n", puni_lconv->os2_mondecpt); return ULS_SUCCESS;
}
UniQueryLocaleItem retrieves locale information by item.
Format
#include <unidef.h>
Remarks
UniQueryLocaleItem returns a pointer in info_item_addr_ptr to a null-terminated UniChar string containing information found in the locale object identified by locale_object about the language or cultural item named by the item argument. UniQueryLocaleItem allocates the memory to hold the UniChar string and returns a pointer in info_item_addr_ptr. Use UniFreeMem to free the memory associated with info_item_addr_ptr by UniQueryLocaleItem.
The constant names and values for item are contained in ulsitem.h:
| Item Name | Item Description |
| LOCI_sDateTime | Date and time format string |
| LOCI_sShortDate | Short date format |
| LOCI_sTimeFormat | Time format string |
| LOCI_s1159 | AM string |
| LOCI_s2359 | PM sring |
| 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 | Localized country name |
| 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 |
Related Functions
Example
This example shows how to retrieve locale information by item. #include <stdio.h> #include <unidef.h>
int main(void) { LocaleObject locale_object = NULL; UniChar *pinfo_item; 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 name of the tenth month locale item */ rc = UniQueryLocaleItem(locale_object, MON_10, &pinfo_item); if (rc != ULS_SUCCESS) { printf("UniQueryLocaleItem error: return code = %u\n", rc); return 1; } rc = UniFreeMem(pinfo_item); if (rc != ULS_SUCCESS) { printf("UniFreeMem 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.
Format
#include <unidef.h>
int UniQueryLocaleList
(int flag, UniChar * uniBuffer, int numUniChars)
Remarks
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.
Related Functions
Example
This example shows how to retrieve a list of locales available on the system. #include <stdio.h>
#include <unidef.h> int main(void) { int rc = ULS_SUCCESS; /* Arrays containing system and user locales */ UniChar *uniSysLocales; UniChar *uniUsrLocales; /* Allocate space for the locale list (2 bytes/UniChar) */ uniSysLocales = (UniChar *) malloc(4096); uniUsrLocales = (UniChar *) malloc(4096); if(!uniSysLocales || !uniUsrLocales) { printf("Malloc failed error: return code = %u\n", rc); return 1; } /************************************************************/ /* Obtain the list of system and user defined locales */ /************************************************************/ rc = UniQueryLocaleList(UNI_SYSTEM_LOCALES, uniSysLocales, 2048); if(rc) { printf("UniQueryLocaleList error: return code = %u\n", rc); return 1; } rc = UniQueryLocaleList(UNI_USER_LOCALES, uniUsrLocales, 2048); if(rc) { printf("UniQueryLocaleList error: return code = %u\n", rc); return 1; } return ULS_SUCCESS;
}
UniQueryLocaleObject retrieves the locale name.
Format
#include <unidef.h>
Parameters
The permissible values for category are:
Returns
Remarks
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 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.
Related Functions
Example
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.
Format
#include <unidef.h>
int UniQueryLocaleValue
(const LocaleObject locale_object, LocaleItem item, int * info_item)
Remarks
When a locale item is requested that does not have an integral value, zero is returned to the caller.
Related Functions
Example
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; 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; } 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 character attributes.
Format
#include <unidef.h>
Parameters
Returns
Remarks
This function provides the functionality of UniCreateAttrObject UniQueryCharAttr, and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Example
This example shows how to query character attributes. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL; int result = 0; int rc = ULS_SUCCESS; UniChar uni_char = L'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.
Format
#include <unidef.h>
Remarks
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.
Related Functions
Example
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 character attributes.
Format .
#include <unidef.h>
Parameters
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Example
This example shows how to query character attributes. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL; int result = 0; int rc = ULS_SUCCESS; UniChar uni_char = L'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 character attributes.
Format
#include <unidef.h>
Parameters
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Example
This example shows how to query character attributes. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL; int result = 0; int rc = ULS_SUCCESS; UniChar uni_char = L'?'; /* 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 character attributes.
Format
#include <unidef.h>
Parameters
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Example
This example shows how to query character attributes. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL; int result = 0; int rc = ULS_SUCCESS; UniChar uni_char = L' '; /* 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.
Format
#include <unidef.h>
Parameters
Remarks
Valid values for kind are:
Related Functions
Example
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 retuned 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 character attributes.
Format
#include <unidef.h>
Parameters
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Example
This example shows how to query character attributes. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL; int result = 0; int rc = ULS_SUCCESS; UniChar uni_char = L'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 character attributes.
Format
#include <unidef.h>
Parameters
Remarks
This function provides the functionality of UniCreateAttrObject, UniQueryCharAttr, and UniFreeAttrObject as an atomic operation for the invariant attributes.
The locale may be specified as NULL to indicate default Unicode character attributes
Related Functions
Example
This example shows how to query character attributes. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL; int result = 0; int rc = ULS_SUCCESS; UniChar uni_char = L'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.
Format
#include <unidef.h>
Parameters
Returns
UniScanForAttr returns one of the following:
Remarks
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:
0 - FALSE
1 - TRUE
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.
Related Functions
Example
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.
Format
#include <unidef.h>
Parameters
Returns
UniSetUserLocaleItem returns one of the following:
Remarks
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.
Related Functions
Example
This example shows how to set a user locale item. #include <stdio.h>
#include <unidef.h> int main(void) {
UniChar unilocaleName[John's_Locale]; LocaleObject locale_object = NULL;
int result = 0; int rc = ULS_SUCCESS; size_t offset = 0; /*****************************************************************/ /* 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; } /* Set the time separator for John's locale to a semicolon */ rc = UniSetUserLocaleItem(unilocaleName, TIMESEP, ULTYPE_UNICODE, (UniChar *)L":"); if (rc != ULS_SUCCESS) { printf("UniSetUserLocaleItem error: return code = %u\n", rc); return 1; } return ULS_SUCCESS; }
UniStrcat concatenates code element strings.
Format
#include <unidef.h>
Parameters
Returns
Remarks
UniStrcat appends a copy of the code element string pointed to by ucs2 (including the terminating null code element) to the end of the code element string pointed to by ucs1. The initial wide 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.
Related Functions
Example
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 code element.
Format
#include <unidef.h>
Parameters
Remarks
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.
Related Functions
Example
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 code element strings.
Format
#include <unidef.h>
Remarks
UniStrcmp compares the code element string pointed to by ucs1 to the code element string pointed to by ucs2.
Related Functions
Example
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 strings without sensitivity to case.
Format
#include <unidef.h>
Parameters
Remarks
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.
Related Functions
Example
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.
Format
#include <unidef.h>
Parameters
Returns
UniStrcoll returns an integer greater than, equal to, or less than zero. The integer returned depends on whether:
Remarks
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.
Example
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 code element string.
Format
#include <unidef.h>
Remarks
UniStrcpy copies the code element string pointed to by ucs2 (including the terminating null code element) into the code element array pointed to by ucs1. If copying takes place between objects that overlap, the results are unpredictable. Related Functions
Example
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 code element string.
Format
#include <unidef.h>
Returns
Remarks
UniStrcspn computes the length of the maximum initial segment of the code element string, pointed to by ucs1, which consists entirely of code elements not from the string pointed to by ucs2.
Related Functions
Example
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"source";
size_t result; result = UniStrcspn(ucs1, ucs2); return (ULS_SUCCESS); }
UniStrfmon converts monetary value to string.
Format
#include <unidef.h>
Parameters
Remarks
The locale may be specified as NULL to indicate C locale.
UniStrfmon places characters 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 character string format contains two types of objects: plain characters, which are copied to the output stream, and directives, each of which results in the fetching of zero or more converted and formatted arguments. The results are unpredictable if there are insufficient arguments for the format. If the format is exhausted while arguments remain, the excess arguments are ignored. A directive consists of a % character, optional conversion specifications, and a terminating character that determines the directive's behavior.
UniStrfmon converts numeric values to monetary strings, according to the specifications in the format parameter. This parameter also contains numeric values to be converted. Characters are placed into this ucs array, as controlled by the format parameter. The LC_MONETARY category governs the format of the conversion.
UniStrfmon can be called multiple times by including additional format structures, as specified by the format parameter.
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.
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
Related Functions
Example
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.
Format
#include <unidef.h> #include <time.h>
Parameters
Remarks
Convert the internal time and date specification into a character string and place the results in the area pointed to by ucs under the direction of format. The null-terminated result of, at most, maxsize code elements, is placed in the memory location addressed by ucs. The format string may contain conversion specification characters and characters that are placed unchanged into the array. The characters that are converted are determined by the LC_TIME category of the locale indicated by the locale object handle argument 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.
Related Functions
Example
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 code element count.
Format
#include <unidef.h>
Parameters
Returns
Remarks
UniStrlen computes the length of the code element string pointed to by ucs.
Example
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.
Format
#include <unidef.h>
Returns
Remarks
The input string must be null-terminated.
Related Functions
Example
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 a specific number of code elements.
Format
#include <unidef.h>
Returns
Remarks
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.
Related Functions
Example
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 a specific number of code elements.
Format
#include <unidef.h>
Parameters
Remarks
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.
Related Functions
Example
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 one or more code elements of strings without sensitivity to case.
Format
#include <unidef.h>
Parameters
Returns
Remarks
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.
Related Functions
Example
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 specific number of code elements.
Format
#include <unidef.h>
Parameters
Returns
Remarks
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.
Related Functions
Example
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 locates code elements in a code element string.
Format
#include <unidef.h>
Parameters
Remarks
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. Related Functions
Example
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.
Format
#include <unidef.h> #include <time.h>
Parameters
Remarks
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. 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.
Related Functions
Example
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 last occurrence of code element.
Format
#include <unidef.h>
Remarks
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.
Related Functions
Example
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 number of code elements in a segment.
Format
#include <unidef.h>
Parameters
Remarks
UniStrspn computes the length of the maximum initial segment of the code element string pointed to by ucs1, which consists entirely of code elements from the code element string pointed to by ucs2.
Related Functions
Example
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) printf("The first %d characters were found\n", num_elems); return (ULS_SUCCESS);
}
UniStrstr locates a code element sequence.
Format
#include <unidef.h>
Parameters
Returns
If ucs2 points to a code element string with zero length, the function returns ucs1.
Remarks
UniStrstr locates the first occurrence, in the code element string pointed to by ucs1 of the sequence of code elements (excluding the ending null code element), in the code element string pointed to by ucs2.
Related Functions
Example
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 character string to double-precision floating point.
Format
#include <unidef.h>
Parameters
UniStrtod returns one of the following values:
Remarks
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.
Related Functions
Example
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); }
}
UniStrtol converts a character string to a long integer.
Format
#include <unidef.h>
UniStrtol returns one of the following values:
Remarks
The locale may be specified as NULL to indicate 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.
Related Functions
Example
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); }
}
UniStrtok converts a Unicode string to tokens.
Format
#include <unidef.h>
Parameters
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.
Remarks
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.
Related Functions
Example
This example shows how to convert a Unicode string to tokens. #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);
}
UniStrtoul converts a character string to an unsigned long integer.
Format
#include <unidef.h>
Parameters
UniStrtoul returns one of the following values:
Related Functions
Remarks
The locale may be specified as NULL to indicate 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.
Example
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.
Format
#include <unidef.h>
Parameters
Remarks
The input string must be null-terminated.
Related Functions
Example
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.
Format
#include <unidef.h>
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.
Remarks
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.
Example
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.
Format
#include <unidef.h>
Parameters
Related Functions
Example
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.
Format
#include <unidef.h>
Parameters
Returns
Related Functions
Example
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.
Format
#include <unidef.h>
Parameters
UniTransformStr returns one of the following:
Remarks
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.
Related Functions
Example
This example shows how to create and use a transform object. #include <stdio.h>
#include <unidef.h> int main(void) { LocaleObject locale_object = NULL;
XformObject xform_object = NULL; int rc = ULS_SUCCESS; int in_unistr_elem = 0; int out_unistr_elem = 10; UniChar *pin_unistr = (UniChar *)L"os2"; UniChar out_unistr[10]; /*****************************************************************/ /* Assumes LANG environment variable set to a valid locale name, */ /* such as fr_FR */ /*****************************************************************/ rc = UniCreateLocaleObject(UNI_UCS_STRING_POINTER, (UniChar *)L"", &locale_object); if (rc != ULS_SUCCESS) { printf("UniCreateLocaleObject error: return code = %u\n", rc); return 1; } /* Create an upper case transform object */ rc = UniCreateTransformObject(locale_object, (UniChar *)L"upper", &xform_object); if (rc != ULS_SUCCESS) { printf("UniCreateTransformObject error: return code = %u\n", rc); return 1; } /* Calculate the number of elements to transform */ in_unistr_elem = UniStrlen (pin_unistr) + 1; /* Make call to transform input string to uppercase */ rc = UniTransformStr(xform_object, pin_unistr, &in_unistr_elem, out_unistr, &out_unistr_elem); if (rc != ULS_SUCCESS) { printf("UniTransformStr error: return code = %u\n", rc); return 1; } return ULS_SUCCESS;
}
UniTransLower converts a Unicode character to lowercase using the specified locale.
Format
#include <unidef.h>
Returns
Related Functions
Example
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 Unicode character to uppercase using the specified locale.
Format
#include <unidef.h>
Parameters
Returns
Related Functions
Example
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. Yet, 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 are defined to perform conversions between UCS and non-UCS encodings. The Uconv name is used to indicate these functions. The Uconv functions are capable of doing only UCS conversions, such as converting to/from UCS.
UniCreateUconvObject creates and initializes a Uconv object.
Format
#include <uconv.h>
Parameters
Returns
Remarks
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
@map=data All characters less than space are controls.
(default)
@map=display All characters less than space are glyphs.
@map=cdra Use IBM standard control conversion.
@map=clrf CR and LF are controls, others are glyphs.
converttype
@path=yes When performing Unicode conversions strings
are assumed to contain pathnames. This
setting is only applicable when converting
to or from DBCS codepages.
(default)
@path=no When performing Unicode conversions strings
are assumed to contain non path data. This
setting is only applicable when converting
to or from DBCS codepages.
endian
@endian=Source:Target
@endian=Both
Source applies to UniUconvFromUcs; Target applies to
UniUconvToUcs. If only one endian is given, it applies
to both source and target.
The endian type can be one of the following:
system Use system endian.
big Use big endian.
little Use little endian.
(default)
For example @endian=little
@endian=big:system
options
@sub=yes Perform substitutions when converting to and
from Unicode.
@sub=no Do not perform substitutions when converting
to and from Unicode.
@sub=to-ucs Only perform substitutions when converting to
Unicode.
@sub=from-ucs Only perform substitutions when converting from
Unicode.
(default)
@subchar=\xXX Where XX is a hex number
@subchar=\DD Where DD is a decimal number
The substitution character attribute specifies
which character the conversion object should
use when there is no identical character for
a given code element while converting from
Unicode.
@subuni=\xXX\xXX Where XX is a hex number
@subuni=\xXXXX Where XXXX is a hex number
The substitution character attribute specifies
which character the conversion object should
use when there is no identical character for
a given code element while converting to
Unicode.
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 either UniUconvFromUcs or UniUconvToUcs.
Related Functions
Example
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 set */ /********************************************************************/ rc = UniCreateUconvObject((UniChar *)L"@path=yes", &uconv_object); if (rc != ULS_SUCCESS) { printf("UniCreateUconvObject error: return code = %u\n", rc); return 1; } return ULS_SUCCESS;
}
UniFreeUconvObject frees a conversion object.
Format
#include <uconv.h>
Returns
Remarks
UniFreeUconvObject closes the conversion object.
Related Functions
Example
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 set */ /********************************************************************/ rc = UniCreateUconvObject((UniChar *)L"@path=yes", &uconv_object); if (rc != ULS_SUCCESS) { printf("UniCreateUconvObject error: return code = %u\n", rc); return 1; } 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 code page represented as a UniChar string that is acceptable as input to UniCreateUconvObject.
Format
#include <uconv.h>
Parameters
UniMapCpToUcsCp returns one of the following values:
Related Functions
Example
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.
Format
#include <uconv.h>
Parameters
UniQueryUconvObject returns one of the following values:
Remarks
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 the uconv_attribute_t to see the conversion object attributes; the structure indicates which fields can be queried and which can be set through UniSetUconvObject.
Related Functions
Example
This example shows how to query a conversion object. #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; } return ULS_SUCCESS;
}
UniSetUconvObject sets the attributes of a conversion object.
Format
#include <uconv.h>
Parameters
UCONV_OPTION_SUBSTITUTION_FROM_UNICODE UCONV_OPTION_SUBSTITUTION_TO_UNICODE UCONV_OPTION_SUBSTITUTION_BOTH
Remarks
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.
Remarks
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.
Related Functions
Example
This example shows how to set a conversion object. #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 UCS characters to code page characters.
Format
#include <uconv.h>
Parameters
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.
Remarks
UniUconvFromUcs converts a sequence of code elements, in the array specified by ucsbuf, into a sequence of corresponding characters in another code page, in the array specified by outbuf. The code page of the 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 in the input buffer, and the UniCharsleft indicates the number of UniChar elements to the end of the buffer to be converted. 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 outbuf buffer is not large enough to hold the entire converted input, conversion stops just prior to the input UniChar that would cause the output buffer to overflow. The variable pointed to by ucsbuf is updated to point to the UniChar following the last UniChar successfully used in the conversion. 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 the ucsbuf that is legal, but for which an identical character does not exist in the target code page, UniUconvFromUcs replaces the character with a predefined substitution character, if the attributes of the conversion object allow this operation. If substitution is not selected, an error is returned and conversion stops after the previous successfully converted UniChar.
Related Functions
Example
This example shows how to convert a Unicode string to code page 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 code page string to a UCS string.
Format
#include <uconv.h>
Parameters
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 zero. If the input conversion is stopped due to any condition mentioned above, the value pointed to by inbytesleft will be non zero and a non zero value is returned to indicate the condition. If an error occurs, UniUconvToUcs returns a non zero value.
Remarks
UniUconvToUcs converts a sequence of characters encoded in one code page, in the array specified by inbuf, into a sequence of corresponding UCS code elements, in the array specified by ucsbuf. The code page 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 byte in the input buffer, and the inbytesleft indicates the number of bytes to the end of the buffer to be converted. The ucsbuf argument points to a variable that points to the first available UniChar in ucsbuf, and UniCharsleft indicates the number of UniChar 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 previous successfully converted character. If the input buffer ends with an incomplete character, conversion stops after the previous successfully converted bytes. If the ucsbuf buffer 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 UniChar elements still available in ucsbuf.
Related Functions
Example
This example shows how to convert code page 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 code page string.
Format
#include <uconv.h>
UniStrFromUcs always performs conversions with substitution on.
Remarks
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 code page 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 a variable that points to the first UniChar in the input bufer. The outbuf argument points to a variable that points to the first available character in outbuf, and size indicates the number of bytes available to the end of the buffer.
If the outbuf buffer is not large enough to hold the entire converted input, conversion stops just prior to the input UniChar that would cause the output buffer to overflow.
If UniStrFromUcs encounters a code element in the ucsstr that is legal, but for which an identical character does not exist in the target code page, UniStrFromUcs replaces the character with a predefined substitution character.
Related Functions
Example
This example shows how to convert a Unicode string to code page 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 code page string to a UCS string.
Format
#include <uconv.h>
Parameters
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 zero. If the input conversion is stopped due to any condition mentioned above, the value pointed to by inbytesleft will be non zero and a non zero value is returned to indicate the condition. If an error occurs, UniUconvToUcs returns a non zero value.
Remarks
UniUconvToUcs converts a sequence of characters encoded in one code page, in the array specified by inbuf, into a sequence of corresponding UCS code elements, in the array specified by ucsbuf. The code page 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 byte in the input buffer, and the inbytesleft indicates the number of bytes to the end of the buffer to be converted. The ucsbuf argument points to a variable that points to the first available UniChar in ucsbuf, and UniCharsleft indicates the number of UniChar 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 previous successfully converted character. If the input buffer ends with an incomplete character, conversion stops after the previous successfully converted bytes. If the ucsbuf buffer 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 UniChar elements still available in ucsbuf.
Related Functions
Example
This example shows how to convert code page 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;
}
The following data types are used by the Unicode functions.
AttrObject is used to determine character classifications.
typedef void *AttrObject;
conv_endian_t Information about the source and target endian.
typedef struct _conv_endian_rec {
unsigned short source;
unsigned short target;
} conv_endian_t;
Parameters
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;
UniChar *thousands_sep;
short *grouping;
UniChar *int_curr_symbol;
UniChar *currency_symbol;
UniChar *mon_decimal_point;
UniChar *mon_thousands_sep;
short *mon_grouping;
UniChar *positive_sign;
UniChar *negative_sign;
short int_frac_digits;
short frac_digits;
short p_cs_precedes;
short p_sep_by_space;
short n_cs_precedes;
short n_sep_by_space;
short p_sign_posn;
short n_sign_posn;
short os2_mondecpt;
UniChar *debit_sign;
UniChar *credit_sign;
UniChar *left_parenthesis;
UniChar *right_parenthesis;
};
Parameters
uconv_attribute_t 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;
char mb_min_len;
char mb_max_len;
char usc_min_len;
char usc_max_len;
unsigned short esid;
char options;
char state;
conv_endian_t endian;
unsigned long displaymask;
unsigned long converttype;
unsigned short subchar_len;
unsigned short subuni_len;
char subchar[16];
UniChar subuni[8];
} uconv_attribute_t;
typedef uconv_attribute_t *uconv_attribute_t;
Parameters
UconvObject is used by APIs that convert to and from UniCode.
typedef void *UconvObject;
The UNICTYPE structure provides a range of information regarding the type of a character.
typedef struct { USHORT itype; CHAR bidi; CHAR charset; USHORT extend; USHORT codepage; } UNICTYPE;
Parameters
udcrange_t provides a set of ranges of characters that make up the user-defined character range.
typedef struct {
unsigned short first;
unsigned short last;
} udcrange_t;
Parameters
ulsBool
typedef int ulsBool;
0 - FALSE
1 - TRUE
A unicode character. Unicode is code that is independent of language and culture, and supports multiple simultaneous character sets.
typedef unsigned short UniChar;
XformObject is used to perform string transformations.
typedef void *XformObject;
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.
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:
IBM
OS/2
The following terms are trademarks of other companies:
Microsoft, Windows, Windows NT®, and the Windows 95
logo
are trademarks or registered trademarks of Microsoft Corporation.
Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service marks of others.