i18n: Managing Characters, Numbers, and Locales

This tutorial demonstrates how you can manage numbers, date, time and locale information.

Warm-up

Become familiar with the i18n API basics by learning about:

Managing Characters and Strings
Convert and manage characters and strings.
Managing Dates and Calendar
Manage dates and calendar.
Managing Locales
Manage locales, which represent a specific geographical, political, or cultural region.
Managing Numbers
Format and parse numbers for any locale.
Managing Iteration Using Ubrk
Iterate through strings using Ubrk.
Managing Enumerations
Create, acquire, and use enumerations.
Managing Time Zones
Get the time zone name, ID, DST savings, raw offset, and region code.
Managing Sets
Manage sets of characters and strings.

Managing Characters and Strings

Note
All source and destination buffers must be different. To use the functions and data types of the i18n API (in mobile and wearable applications), include the <utils_i18n.h> header file in your application: #include <utils_i18n.h>

Comparing Ustrings

To compare two Ustrings:

To compare 2 Ustrings for bitwise equality, use the i18n_ustring_compare() function. The obtained result is equal to 0 if the compared Ustrings are equal. The result is a negative value if the first Ustring is bitwise smaller than the second Ustring, and a positive value if the first Ustring is greater than the second one.
```
#define BUFLEN 400

i18n_uchar s1[BUFLEN];
i18n_ustring_copy_ua(s1, "Tizen");
i18n_uchar s2[BUFLEN];
i18n_ustring_copy_ua(s2, "Bada");
int32_t result = i18n_ustring_compare(s1, s2);
```

For a more complex, locale-sensitive comparison, use the Ucollator API (in mobile and wearable applications):

Create a Ucollator using the i18n_ucollator_create() function.
Specify the locale as the first parameter and a handle to the created Ucollator as the second parameter.
```
i18n_ucollator_h coll;
i18n_ucollator_create(I18N_ULOCALE_US, &coll);
```
Set the Ucollator strength.
The strength influences how strings are compared. There are a few available strength levels:
- Primary differences (I18N_UCOLLATOR_PRIMARY), such as different base letters ("a" vs "b")
- Secondary differences (I18N_UCOLLATOR_SECONDARY), such as different accented forms of the same base letter ("a" vs "ä")
- Tertiary differences (I18N_UCOLLATOR_TERTIARY), such as case differences ("a" vs "A")
For the default value of the Ucollator's strength, use I18N_UCOLLATOR_DEFAULT_STRENGTH.
```
i18n_ucollator_set_strength(coll, I18N_UCOLLATOR_DEFAULT_STRENGTH);
```
Compare 2 Ustrings.
To compare two Ustrings, use the i18n_ucollator_equal() or i18n_ucollator_str_collator() functions. The result of the first function shows whether the compared Ustrings are equal. The second function is more specific, and shows whether the first Ustring is equal to, smaller, or greater than the second Ustring (I18N_UCOLLATOR_EQUAL, I18N_UCOLLATOR_LESS, I18N_UCOLLATOR_GREATER).

Specify the following parameters:
- Ucollator handle
- First Ustring
- Length of the first Ustring (-1 if the string is null-terminated)
- Second Ustring
- Length of the second Ustring (-1 if the string is null-terminated)
- Variable to store the result
```
i18n_ubool equal;
i18n_ucollator_equal(coll, s1, -1, s2, -1, &equal);

i18n_ucollator_result_e result;
i18n_ucollator_str_collator(coll, s1, -1, s2, -1, &result);
```
Destroy the Ucollator.
When you finish using the Ucollator, destroy it using the i18n_ucollator_destroy() function.
```
i18n_ucollator_destroy(coll);
```

Converting Strings to Ustrings

To convert strings to Ustrings:

To convert a byte string to a Unicode string (Ustring), use the i18n_ustring_copy_ua() function.
```
const char *src = "Tizen";
i18n_uchar dest[BUFLEN];
i18n_ustring_copy_ua(dest, src);
```
The i18n_ustring_copy_ua_n() function works similarly but it copies n characters at most, where n is its third parameter.
```
const char *src = "Tizen";
i18n_uchar dest[BUFLEN];
i18n_ustring_copy_ua_n(dest, src, BUFLEN);
```
Another way to convert a string to a Ustring is using the i18n_ustring_from_UTF8() function. Its parameters are:
- Destination buffer
- Destination buffer capacity (limit)
- Length of the converted Ustring
- Source string buffer
- Length of the original string (can be -1 if the string is null-terminated)
- Error code variable
```
const char *src = "Tizen";
i18n_uchar dest[BUFLEN];
int dest_len;
i18n_uerror_code_e error_code = I18N_ERROR_NONE;
i18n_ustring_from_UTF8(dest, BUFLEN, &dest_len, src, -1, &error_code);
```

Converting Ustrings to Strings

To convert Ustrings to strings:

To convert a Ustring to a byte string, use the i18n_ustring_copy_au() function.

i18n_uchar src[BUFLEN];
i18n_ustring_copy_ua(src, "Tizen");
const char dest[BUFLEN];
i18n_ustring_copy_au(dest, src);

The i18n_ustring_copy_au_n() function works similarly but it copies n characters at most, where n is its third parameter.

i18n_uchar src[BUFLEN];
i18n_ustring_copy_ua(src, "Tizen");
const char dest[BUFLEN];
i18n_ustring_copy_au_n(dest, src, BUFLEN);

Another way to convert a Ustring to a string is using the i18n_ustring_to_UTF8() function. Its parameters are:
- Destination buffer
- Destination buffer capacity (limit)
- Length of the converted Ustring
- Source string buffer
- Length of the original string (can be -1 if the string is null-terminated)
- Error code variable
To get the length of a Ustring, use the i18n_ustring_get_length() function.
```
i18n_uchar src[BUFLEN];
i18n_ustring_copy_ua(src, "Tizen");
const char dest[BUFLEN];
int dest_len;
i18n_uerror_code_e error_code = I18N_ERROR_NONE;
i18n_ustring_to_UTF8(dest, BUFLEN, &dest_len, src, i18n_ustring_get_length(src), &error_code);
```

Getting Unicode Block of a Character

To get information about the location of a specified character:

To get information about which Unicode allocation block contains the specified character, use the i18n_uchar_get_ublock_code() function. The Unicode blocks are listed in the i18n_uchar_ublock_code_e enumeration (in mobile and wearable applications).
```
i18n_uchar character = 0xC131;
i18n_uchar_ublock_code_e ublock;
i18n_uchar_get_ublock_code(character, &ublock);
```

Getting Property Value of a Character

To get the value of a property of a specified character:

Properties of characters are listed in the i18n_uchar_uproperty_e enumeration (in mobile and wearable applications). To read the value of a property, use the i18n_uchar_get_int_property_value() function.

The following example shows how to read the East Asian width property:
```
i18n_uchar character = 0xC131;
int32_t property_value;
i18n_uchar_get_int_property_value(character, I18N_UCHAR_EAST_ASIAN_WIDTH, &property_value);
```

Normalizing Ustrings

To normalize a Ustring:

Get a Unormalizer instance.
To get a Unormalizer instance, use the i18n_unormalization_get_instance() function of the Unormalization API (in mobile and wearable applications). The first parameter is NULL to use the built-in normalizer, then specify the name of the normalizer (nfc or nfkc), normalization mode (compose or decompose), and a pointer to a normalizer.
```
i18n_unormalizer_h normalizer;
i18n_unormalization_get_instance(NULL, "nfc", I18N_UNORMALIZATION_DECOMPOSE, &normalizer);
```
Normalize a Ustring or Uchar.
To normalize a Ustring or Uchar using the obtained normalizer, use the i18n_unormalization_normalize() function. The parameters are:
- Normalizer handle
- Source Ustring
- Source Ustring length (-1 if the string is null-terminated)
- Destination buffer
- Size of the destination buffer
- Variable to store the actual length of the normalized Ustring
```
i18n_uchar src = 0xACE0;
i18n_uchar dest[4];
int dest_str_len;
i18n_unormalization_normalize(normalizer, &src, 1, dest, 4, &dest_str_len);
```

Searching Text in Ustring

To search a substring in a Ustring:

Create a search iterator.
To create a search iterator, use the i18n_usearch_create_new() function of the Usearch API (in mobile and wearable applications). To create the iterator, specify the following:
- Search pattern
- Length of the search pattern (-1 if the string is null-terminated)
- Ustring in which to search
- Length of the Ustring
- Locale associated with the text language
- Optional break iterator structure
- Handle to created search iterator
```
i18n_uchar text[BUFLEN];
i18n_ustring_copy_ua(text, "TIZEN");
i18n_uchar pattern[BUFLEN];
i18n_ustring_copy_ua(pattern, "ZEN");
i18n_usearch_h usearch;
i18n_usearch_create_new(pattern, -1, text, -1, I18N_ULOCALE_US, NULL, &usearch);
```
Get the index of the first match.
To get the index of the first occurrence of the found pattern, use the i18n_usearch_first() function.
```
int index;
i18n_usearch_first(usearch, &index);
```
Destroy the search iterator.
When you finish using the search iterator, destroy it using the i18n_usearch_destroy() function.
```
i18n_usearch_destroy(usearch);
```

Changing Case in a Ustring

To change the case in a Ustring:

To change all characters' case in a Ustring, use the i18n_ustring_to_upper() and i18n_ustring_to_lower() functions. The parameters of both functions are:
- Result buffer
- Result buffer capacity
- Original Ustring
- Original Ustring length (-1 if the string is null-terminated)
- Locale that represents the string language
- Result length
- Error code variable
```
i18n_uchar src[BUFLEN];
i18n_ustring_copy_ua(src, "Tizen");
i18n_uchar dest[BUFLEN];
i18n_ustring_to_upper(dest, BUFLEN, src, -1, I18N_ULOCALE_US, &error_code);
i18n_ustring_to_lower(dest, BUFLEN, src, -1, I18N_ULOCALE_US, &error_code);
```
To change the string case to title case, use the i18n_ustring_to_title_new() function. The parameters are:
- Result buffer
- Result buffer capacity
- Original Ustring
- Original Ustring length (-1 if the string is null-terminated)
- Break iterator (to find first characters of words); if NULL, standard iterator is used
- Locale ("" for root locale, NULL for default locale
```
i18n_uchar src[BUFLEN];
i18n_ustring_copy_ua(src, "Tizen");
i18n_uchar dest[BUFLEN];
i18n_ustring_to_title_new(dest, BUFLEN, src, BUFLEN, NULL, NULL);
```

Concatenating Ustrings

To concatenate 2 Ustrings:

Use the 18n_ustring_cat_n() functions. The parameters are:
- Destination string
- String to be appended to the destination string
- Number of characters to append at most
Alternatively, you can use 18n_ustring_cat(), which does not take the last parameter.
```
i18n_uchar src[BUFLEN];
i18n_uchar dest[BUFLEN];
i18n_ustring_copy_ua(src, "Destination string");
i18n_ustring_copy_ua(src, "Appended string");
i18n_ustring_cat_n(dest, src, BUFLEN);
i18n_ustring_cat(dest, src);
```

Finding a Substring

To find a substring in a Ustring:

Use the 18n_ustring_string() functions. The parameters are:
- String
- Substring which the function searches for in the string
The result is a pointer to the first occurrence of the substring, or NULL if the substring is not found. You can use pointer arithmetic to find the index of the character at which the first occurrence begins.
```
i18n_uchar s[BUFLEN];
i18n_uchar substring[BUFLEN];

i18n_uchar *result = i18n_ustring_string(s, substr);

if (result == NULL)
{
   dlog_print(DLOG_DEBUG, LOG_TAG, "Substring not found");
}
else
{
   dlog_print(DLOG_DEBUG, LOG_TAG, "Substring index: %d", result - s);
}
```

Managing Dates and Calendar

To create and use the Ucalendar:

To use the functions and data types of the Ucalendar (in mobile and wearable applications), Udate (in mobile and wearable applications), and Udatepg (in mobile and wearable applications) APIs, include the <utils_i18n.h> header file in your application:
```
#include <utils_i18n.h>
```
- The Ucalendar API is used for converting between an i18n_udate object and a set of integer fields, such as I18N_UCALENDAR_YEAR, I18N_UCALENDAR_MONTH, I18N_UCALENDAR_DAY, and I18N_UCALENDAR_HOUR.
- The Udate API consists of functions that convert dates and times from their internal representations to a textual form and back again in a language-independent manner.
- The Udatepg API provides flexible generation of date format patterns, such as "yy-MM-dd".
Create a Ucalendar.
To create a Ucalendar, use the i18n_ucalendar_create() function.

Insert the following parameters:
- Time zone symbol (such as "Asia/Seoul", "UTC", "GMT+9") or NULL for the default time zone
- Length of time zone symbol (-1 if the symbol is null-terminated)
- Desired locale (cannot be associated with the chosen time zone)
- Calendar type (default, Gregorian)
- Handle to the created Ucalendar
```
i18n_uchar timezone[17];
i18n_ustring_copy_ua_n(timezone, "America/New_York", 17);
i18n_ucalendar_h ucalendar;
i18n_ucalendar_create(timezone, -1, I18N_ULOCALE_US, I18N_UCALENDAR_DEFAULT, &ucalendar);
```
Set a date.
To set a date in the Ucalendar, use the i18n_ucalendar_set_date_time() function.

Provide a handle to the Ucalendar, year, month reduced by 1 (0 for January, 1 for February, and so forth; use the values of the i18n_ucalendar_months_e enumeration, in mobile and wearable applications, to avoid mistakes), day, hour, minute, and second.
```
i18n_ucalendar_set_date_time(ucalendar, 2014, I18N_UCALENDAR_JULY, 1, 9, 0, 0);
```
To set a date using milliseconds from the epoch, use the i18n_ucalendar_set_milliseconds() function:
```
i18n_udate udate;
// udate must be set
i18n_ucalendar_set_milliseconds(ucalendar, udate);
```
To add a specified period to the Ucalendar, use the i18n_ucalendar_add() function. Specify a handle to the Ucalendar, a field of Ucalendar to add to (year, week, day; the value of the i18n_ucalendar_date_fields_e enumeration, in mobile and wearable applications) and the amount to add to field (use a negative value to subtract).
```
i18n_ucalendar_add(ucalendar, I18N_UCALENDAR_HOUR, 3);
```
Get a date.
To get a date from the Ucalendar, use the i18n_ucalendar_get() function. You can get one of the possible values (such as year, week of year, day of month, hour, or day of year from the ucalendar instance; for more information, see the i18n_ucalendar_date_fields_e enumeration) at once.
```
int uday;
i18n_ucalendar_get(ucalendar, I18N_UCALENDAR_DAY_OF_YEAR, &uday);
```
To get an actual current date from the system, use the i18n_ucalendar_get_now() function. The obtained date is represented as milliseconds from the epoch.
```
i18n_udate now;
i18n_ucalendar_get_now(&now);
```
To get a date in milliseconds from the epoch, use the i18n_ucalendar_get_milliseconds() function.
```
i18n_udate date;
i18n_ucalendar_get_milliseconds(ucalendar, &date);
```
To check whether the Ucalendar date is in daylight saving time, use the i18n_ucalendar_is_in_daylight_time() function.
```
bool dst;
i18n_ucalendar_is_in_daylight_time(ucalendar, &dst);
```
Format a date.
To format a date, first create a Udatepg (pattern generator) that helps with creating the date pattern. Use the i18n_udatepg_create() function, providing a desired locale and a handle to the created Udatepg.
```
i18n_udatepg_h udatepg;
i18n_udatepg_create(I18N_ULOCALE_UK, &udatepg);
```
To generate a date best pattern, use the i18n_udatepg_get_best_pattern() function. Prepare a draft format to define which kind of fields should be displayed (for example, E for the day of the week, M for month, y for year, d for the day of the month, and D for day of the year). As parameters, pass a handle to the date pattern generator, a format draft, the length of the draft (-1 if null-terminated), a buffer for the generated pattern, the size of the buffer, and a variable to store the actual size of the generated pattern.
```
int pattern_len;
i18n_uchar format[64];
i18n_ustring_copy_ua_n(format, "EEEdMMMyyyyHHmmssz", 64);
i18n_uchar best_pattern[64];
i18n_udatepg_get_best_pattern(udatepg, format, 64, best_pattern, 64, &pattern_len);
```
To create a date format, use the i18n_udate_create() function. Specify the style to format time, the style to format date (from the i18n_udate_format_style_e enumeration, in mobile and wearable applications), the desired locale, the desired time zone name, the length of the time zone name, a date pattern to use, the length of the pattern, and a handle to the created date format).
```
i18n_udate_format_h date_format;
i18n_ustring_copy_ua_n(timezone, "Asia/Seoul", 17);
i18n_udate_create(I18N_UDATE_FULL, I18N_UDATE_FULL, I18N_ULOCALE_UK, timezone, -1, best_pattern, -1, &date_format);
```
To obtain a well-formatted Ustring with a specified date, use the i18n_udate_format_date() function. The parameters are a handle to the date format, the date in milliseconds from the epoch, a buffer for a result, the size of the destination buffer, an optional handle to a UFieldPosition structure to get the positions of the fields, and a variable to store the actual size of the obtained Ustring.
```
i18n_uchar date_result[64];
int date_len;
i18n_udate_format_date(date_format, now, date_result, 64, NULL, &date_len);
```
Destroy the Ucalendar, Udatepg, and Udate.
When you finish using the created Ucalendar, Udatepg and Udate, destroy them using the i18n_ucalendar_destroy(), i18n_udatepg_destroy(), and i18n_udate_destroy() functions.
```
i18n_ucalendar_destroy(ucalendar);
i18n_udatepg_destroy(udatepg);
i18n_udate_destroy(date_format);
```

Managing Locales

To manage the features of a specific geographical, political, or cultural region:

To use the functions and data types of the Ulocale API (in mobile and wearable applications), include the <utils_i18n.h> header file in your application:
```
#include <utils_i18n.h>
```
To manage locale information:
- To get the language code associated with a locale, use the i18n_ulocale_get_language() function. The parameters are:
  - Locale symbol (such as "en_US" or "ko_KR" - the supported locales are defined in the API as I18N_ULOCALE_*)
  - Buffer for the language code
  - Size of the buffer
  - Variable to store the actual length of the language code
```
char language[BUFLEN];
int lang_len;
i18n_ulocale_get_language(I18N_ULOCALE_GERMANY, language, BUFLEN, &lang_len);
```
- To get the language ISO-3 code for the specified locale, use the i18n_ulocale_get_language() function. The parameter is the locale.
```
const char *language_iso = i18n_ulocale_get_iso3_language(I18N_ULOCALE_GERMANY);
```
- To get the full name of the language for the specified locale, use the i18n_ulocale_get_display_language() function. The parameters are:
  - Locale to get the full language name of
  - Locale to localize the language name (specifies the language of the obtained name)
  - Buffer for the name
  - Size of the buffer
  - Variable to store the actual size of the language name
```
char *locale = I18N_ULOCALE_CANADA_FRENCH;
i18n_uchar language_name[BUFLEN];
int lang_len;
i18n_ulocale_get_display_language(locale, I18N_ULOCALE_GERMANY, language_name, BUFLEN, &lang_len);
```
  In this example, the name of the "fr_CA" locale is obtained in German.
- To get the line orientation for the specified locale, use the i18n_ulocale_get_line_orientation() function. The parameters are:
  - Locale to get the line orientation of
  - Variable to store the returned orientation
```
char *locale = I18N_ULOCALE_ENGLISH;
i18n_ulocale_layout_type_e type;
i18n_ulocale_get_line_orientation(locale, &type);
```
- To get the character orientation for the specified locale, use the i18n_ulocale_get_character_orientation() function. The parameters are:
  - Locale to get the character orientation of
  - Variable to store the returned orientation
```
char *locale = I18N_ULOCALE_ENGLISH;
i18n_ulocale_layout_type_e type;
i18n_ulocale_get_character_orientation(locale, &type);
```
- To get the variant code for the specified locale, use the i18n_ulocale_get_variant() function. The parameters are:
  - Locale to get the variant code of
  - Buffer for the variant
  - Size of the buffer
```
char *locale = I18N_ULOCALE_ENGLISH;
char *variant = malloc(sizeof(char) * BUFLEN);
int32_t variant_len = i18n_ulocale_get_variant(locale, variant, BUFLEN);
```
  The function returns the actual size of the variant.
- To get a full name for the specified locale, use the i18n_ulocale_get_display_name() function. The parameters are:
  - Locale to get the full name of
  - Locale to localize the name (specify the language of the obtained name)
  - Buffer for the name
  - Size of the buffer
  - Variable to store the actual size of the name
```
i18n_uchar name[BUFLEN];
int name_len;
i18n_ulocale_get_display_name(I18N_ULOCALE_CANADA_FRENCH, I18N_ULOCALE_GERMANY, name, BUFLEN, &name_len);
```
  In this example, the name of the "fr_CA" locale is obtained in German.
- To get the default locale, use the i18n_ulocale_get_default() function:
```
char *locale;
i18n_ulocale_get_default(&locale);
```
- To set the default locale, use the i18n_ulocale_set_default() function:
```
i18n_ulocale_set_default(I18N_ULOCALE_KOREA);
```

Managing Numbers

To format and parse numbers for a locale:

To use the functions and data types of the Unumber API (in mobile and wearable applications), include the <utils_i18n.h> header file in your application:
```
#include <utils_i18n.h>
```
Create a number format.
To start using the Unumber module, create a number format using the i18n_unumber_create() function. The parameters are:
- Number format style (such as I18N_UNUMBER_CURRENCY; see the i18n_unumber_format_style_e enumeration, in mobile and wearable applications)
- Format pattern (only for decimal and rule-based types)
- Length of the format pattern
- Locale identifier (NULL for default)
  Some identifiers (string shortcuts for specific locales) are defined in the utils_i18n_types.h header file. For example, I18N_ULOCALE_US is equal to "en_US".
- Optional pointer to an i18n_uparse_error_s struct
- Handle to the created number format
```
i18n_unumber_format_h num_format;
i18n_unumber_format_style_e format_style = I18N_UNUMBER_CURRENCY;
const char* locale = I18N_ULOCALE_US;
i18n_unumber_create(format_style, NULL, -1, locale, NULL, &num_format);
```
After creating the number format, you can use it to format a given number based on the rules of a specified locale:
```
#define BUFLEN 64
i18n_uchar myString[BUFLEN];
double myNumber = 4.5;
i18n_unumber_format_double(num_format, myNumber, myString, BUFLEN, NULL);
```
The result set in the myString variable is equal to:
```
$4.50
```
Get a symbol associated with the number format.
To get a symbol associated with the created number format, use the i18n_unumber_get_symbol() function. The parameters are:
- Number format
- Symbol to get (see the i18n_unumber_format_symbol_e enumeration, in mobile and wearable applications)
- Destination buffer
- Size of the buffer
- Variable to store the length of the symbol
```
i18n_uchar buffer[BUFLEN];
int buf_len;
i18n_unumber_format_symbol_e symbol = I18N_UNUMBER_CURRENCY_SYMBOL;
i18n_unumber_get_symbol(num_format, symbol, buffer, BUFLEN, &buf_len);
```
The function returns only the symbol used in the given locale, in this example, the currency $ sign.
Destroy the number format.
When you finish using the number format, destroy it with the i18n_unumber_destroy() function:
```
i18n_unumber_destroy(num_format);
```

Managing Iteration Using Ubrk

To manipulate or iterate through strings you can use the Ubrk library. It helps you to treat strings as a set of characters, words or sentences:

To use the functions and data types of the Ubrk API (in mobile and wearable applications), include the <utils_i18n.h> header file in your application:
```
#include <utils_i18n.h>
```
Create a boundary to iterate through a string by words.

To start using the Ubrk library, create an iterator using the i18n_ubrk_create() function. Specify its parameters, which are the type of the iterator (use the I18N_UBRK_WORD word, I18N_UBRK_CHARACTER character, I18N_UBRK_LINE line, or I18N_UBRK_SENTENCE sentence iteration), the locale, string to iterate through, length of the string, and a handle to the created iterator.
```
i18n_ubreak_iterator_h boundary;
const char *str = "Twinkle, twinkle little star"
i18n_uchar* stringToExamine = malloc(sizeof(i18n_uchar)*28);
i18n_ustring_copy_ua(stringToExamine, str);
i18n_ubrk_create(I18N_UBRK_WORD, "en_US", stringToExamine, i18n_ustring_get_length(stringToExamine), &boundary);
```
Change the position of the iterator.

To change the iterator position, you can use several functions (such as i18n_ubrk_first(), i18n_ubrk_last(), i18n_ubrk_next(), and i18n_ubrk_previous()). The parameter is the previously created iterator. For example, to get boundaries of the first word in the string (stringToExamine), use:
```
int32_t start = i18n_ubrk_first(boundary);
int32_t end = i18n_ubrk_next(boundary);
```
The start and end represent the boundaries of the first word, in this example 0 and 7.
Retrieve the string.

To retrieve the string delimited with the start and end, use the i18n_ustring_copy_n() function. Its parameters are the output string, source string, and the maximum number of characters to copy.
```
i18n_ustring_copy_n(result, &str[start], end-start);
```
Destroy the ubreak iterator.

When you finish using the ubreak iterator, destroy it with the i18n_ubrk_destroy() function. Remember to free all allocated memory with the free() function.
```
i18n_ubrk_destroy(boundary);
```

Managing Enumerations

The Uenumeration module allows you to create collections of strings and iterate through them.

To use the functions and data types of the Uenumeration API (in mobile and wearable applications), include the <utils_i18n.h> header file in your application:

#include <utils_i18n.h>

Creating an Enumeration

To create an enumeration based on existing strings:

Define an array of strings (pointers to char):

const char * strings[] = {"First", "Second", "Third", "Fourth"};

// Length of the pointers array (the number of strings)
int32_t size = sizeof(strings) / sizeof(strings[0]);

Create an enumeration:
```
i18n_uenumeration_h strings_enum;

i18n_uenumeration_char_strings_enumeration_create(strings, size, &strings_enum);
```
In case of char strings, use the i18n_uenumeration_char_strings_enumeration_create() function. For i18n_uchar strings, use the i18n_uenumeration_uchar_strings_enumeration_create() function.
Get the number of elements:
```
int32_t count = i18n_uenumeration_count(strings_enum);
```
If everything is OK, the value is equal to the size variable above.
Iterate through the elements.
To iterate through the elements, call the i18n_uenumeration_next() function until it returns NULL. For i18n_uchar strings, call the i18n_uenumeration_unext() function.
```
const char *element = NULL;
int len;

element = i18n_uenumeration_next(strings_enum, &len);
while (element != NULL)
{
   // Use the returned string

   element = i18n_uenumeration_next(strings_enum, &len);
}
```
The string is null-terminated. len is the length of the string.

The returned string must not be freed. The returned pointer is valid until any function is called for the enumeration.
Destroy the enumeration.
When you no longer need the enumeration, destroy it with the 18n_uenumeration_destroy() function.
```
18n_uenumeration_destroy(strings_enum);
```

Obtaining an Enumeration

Certain functions in the i18n module provide enumerations of values related to them. This section describes how to use some of those functions. After the enumeration is obtained, it can be used as described above.

To get an enumeration of available time zones, use the i18n_ucalendar_timezones_create() function:

i18n_uenumeration_h timezones;
i18n_ucalendar_timezones_create(&timezones);

int32_t count = i18n_uenumeration_count(timezones);

const char *tz = NULL;
int len;

tz = i18n_uenumeration_next(timezones, &len);
while (tz != NULL)
{
   // Use the time zone string

   tz = i18n_uenumeration_next(timezones, &len);
}

i18n_uenumeration_destroy(timezones);

After creating a date pattern generator for a given locale, you can obtain an enumeration of all skeletons in canonical form. To get the enumeration, use the i18n_udatepg_skeletons_create() function:

i18n_udatepg_h udatepg;
i18n_udatepg_create(I18N_ULOCALE_UK, &udatepg);

i18n_uenumeration_h skeletons;
i18n_udatepg_skeletons_create(udatepg, &skeletons);

i18n_udatepg_destroy(udatepg);

int32_t count = i18n_uenumeration_count(skeletons);

const char *sk = NULL;
int len;

sk = i18n_uenumeration_next(skeletons, &len);
while (sk != NULL)
{
   // Use the skeleton string

   sk = i18n_uenumeration_next(skeletons, &len);
}

i18n_uenumeration_destroy(skeletons);

For a given locale string, you can obtain an enumeration of keywords with the i18n_ulocale_keywords_create() function:

const char *loc_string = "en_US@collation=PHONEBOOK;calendar=GREGORIAN;currency=USD";

i18n_uenumeration_h keywords;
i18n_ulocale_keywords_create(loc_string, &keywords);

int32_t count = i18n_uenumeration_count(keywords);

const char *keyword = NULL;
int len;

keyword = i18n_uenumeration_next(keywords, &len);
while (keyword != NULL) 
{
   // Use the keyword string

   keyword = i18n_uenumeration_next(keywords, &len);
}

i18n_uenumeration_destroy(keywords);

Managing Time Zones

The Timezone module represents a time zone offset, and also figures out daylight savings.

To use the functions and data types of the Timezone API (in mobile and wearable applications), include the <utils_i18n.h> header file in your application:
```
#include <utils_i18n.h>
```
Retrieve time zone information:
- To get the default time zone based on the time zone where the program is running:
```
i18n_timezone_h tmz;
i18n_timezone_create_default(&tmz);
```
- To get the display name of the time zone:
```
char *display_name;
i18n_timezone_get_display_name(tmz, &display_name);
```
- To get the time zone ID:
```
char *timezone_id;
i18n_timezone_get_id(tmz, &timezone_id);
```
- To check whether a given time zone uses daylight savings time (DST):
```
int32_t dst_savings;
i18n_timezone_get_dst_savings(tmz, &dst_savings);
```
- To get the daylight savings (the amount of time to be added to the local standard time to get the local wall clock time):
```
#define MS_TO_MIN 60000
int32_t dst_savings;
i18n_timezone_get_dst_savings(tmz, &dst_savings/MS_TO_MIN);
```
  The result is returned in milliseconds (3600000 ms = 1 hour). In this tutorial, milliseconds are changed to minutes (1 min = 60000 ms).
- To get the raw GMT offset:
```
#define MS_TO_MIN 60000
int32_t offset_milliseconds;
i18n_timezone_get_raw_offset(tmz, &offset_milliseconds/MS_TO_MIN);
```
  The result is returned in milliseconds. It is the number of milliseconds to add to GMT to get the local time, before taking DST into account. In this tutorial, milliseconds are changed to minutes (1 min = 60000 ms).
- To get the region code associated with the time zone ID:
```
char region[6];
int32_t region_len = -1;
i18n_timezone_get_region(timezone_id, region, &region_len, 20);
```
Destroy the time zone when it is no longer needed:
```
i18n_timezone_destroy(tmz);
```

Managing Sets

The Uset module allows you to create sets which can contain characters and strings. You can iterate through elements of the given set and carry out various operations on the set.

To manage sets:

To use the functions and data types of the Uset API (in mobile and wearable applications), include the <utils_i18n.h> header file in your application:
```
#include <utils_i18n.h>
```
Create a set.
The following example creates an empty set:
```
i18n_uset_h set;
i18n_uset_create_empty(&set);
```

Managing Characters

The set can contain characters as its elements. It is also possible to check whether a set contains specified characters.

Add characters from a string to the set:

const char *text = "Example string";
i18n_uchar u_input_text[BUFLEN];
i18n_ustring_copy_ua(u_input_text, text);

i18n_uset_add_all_code_points(set, u_input_text, -1);

Get the list of characters in the set:

int chars_count = i18n_uset_size(set);
int i;

// Get all characters in the set
for (i = 0; i < chars_count; i++) 
{
   i18n_uchar32 uchar = i18n_uset_char_at(set, i);
}

Check whether the set contains the given character:

i18n_ubool contains_character = i18n_uset_contains(set, 'a');

Check whether the set contains characters from the a - c range:

i18n_ubool contains_character = i18n_uset_contains_range(set, 'a', 'c');

Check whether the set contains characters from another set:

i18n_uset_h compare_set = NULL;

// Fill the second set
i18n_ubool contains_character = i18n_uset_contains_all(set, compare_set);

Managing Strings

The set can contain strings as its elements. To manage strings:

Add a string to the set:

const char *text = "Example string";
i18n_uchar u_input_text[BUFLEN];
i18n_ustring_copy_ua(u_input_text, text);
 
i18n_uset_add_string(set, u_input_text, -1);

The entire string is a single element.

List all strings in the set:

int strings_count = i18n_uset_get_item_count(set);
int32_t len = 0;
int32_t i;
for (i = 0; i < strings_count; ++i) 
{
   i18n_uchar32 start, end;
   i18n_uchar string[100];
   let = i18n_uset_get_item(set, i, &start, &end, string, 100);
   if (len != 0) 
   {
      // String was found, use the 'string' variable
   }
}

Note that the i18n_uset_get_item() function also returns ranges (an item is a string or a range). The return value is 0 if the current item is a range. For more information, see the API documentation.

Check whether the set contains a string:

i18n_ubool contains = i18n_uset_contains_string(set, input_ustring, -1);