From 7ebb2dd6f5afab3cea80c981f89f1a70aec4713b Mon Sep 17 00:00:00 2001 From: Lukasz Pik Date: Thu, 5 Oct 2017 12:45:29 +0200 Subject: [PATCH] Added format module guide PS4: Reviewed PS5: Rebase Change-Id: I27e2a37e7a1c008704c7cb9fa866013af195de83 Signed-off-by: Lukasz Pik --- .../html/native/internationalization/i18n_n.htm | 97 +++++++++++++++++++++- 1 file changed, 96 insertions(+), 1 deletion(-) diff --git a/org.tizen.guides/html/native/internationalization/i18n_n.htm b/org.tizen.guides/html/native/internationalization/i18n_n.htm index b1fd132..ead13a1 100644 --- a/org.tizen.guides/html/native/internationalization/i18n_n.htm +++ b/org.tizen.guides/html/native/internationalization/i18n_n.htm @@ -43,6 +43,9 @@
  • Character and String Management with Uset
  • Unicode Strings with Ustring
  • Alphabetic Index Creation
    • + +
  • String Format Management
    • +
  • String Iteration with UCharIter
  • Prerequisites
  • Managing Characters and Strings
    • @@ -54,6 +57,9 @@
  • Managing Time Zones
  • Managing Sets
  • Managing Alphabetic Indexes
    • + +
  • Managing String Formatting
    • +
  • Retrieving the ICU Version
  • Iterating through Strings
    • @@ -89,6 +95,10 @@
  • Managing alphabetic indexes

    You can use the Alphabetic Index functions to generate a list of labels that can be used as an index.

    • + +
  • Managing string formatting +

    You can use the Format functions to manage the string representations of objects or values.

    • +
  • Retrieving the ICU version

    You can retrieve the currently-used version of the ICU library with Uversion.

  • Iterating through strings @@ -98,7 +108,7 @@
    Note - The Alphabetic Index API is supported since Tizen 3.0. The Uversion and UCharIter APIs are supported since Tizen 4.0. + The Alphabetic Index and Format APIs are supported since Tizen 3.0. The Uversion and UCharIter APIs are supported since Tizen 4.0.

    Location Boundaries with Ubrk

    @@ -565,6 +575,12 @@

    The Alphabetic Index API also supports creating buckets for strings that are sorted before the first label (underflow), after the last label (overflow), and between scripts (inflow). For example, if an index is constructed with labels for Russian and for English characters, Greek characters can be placed in an inflow bucket between the other 2 scripts.

    +

    String Format Management

    +

    The Format API (in mobile and wearable applications) allows you to manage formatting for displayed strings.

    +

    The Format API specifies the protocol for classes which convert between objects or values, such as numeric values and dates, and their string representations. These representations can be localized or contain localized characters or strings.

    +

    There is no function for creating an i18n_format_h object, as this module uses a mechanism similar to inheritance in object-oriented languages. All functions with the i18n_format_h handle as a parameter can instead take the handle to a more specific format object from the derived classes.

    + +

    String Iteration with UCharIter

    The UCharIter API (in mobile and wearable applications) allows you to iterate through strings.

    The current() and next() functions only check the current index against the limit, and the previous() function only checks the current index against the start, to see if the iterator has already reached the beginning of the iteration range. The assumption - in all iterators - is that the index is moved though the API, which means that it cannot go out of bounds, or that the index is modified though the application code by a developer who knows enough about the iterator implementation to set valid index values.

    @@ -1771,6 +1787,85 @@ i18n_alpha_idx_destroy(alpha_idx); + +

    Managing String Formatting

    +

    Since Tizen 3.0, you can use the Format API (in mobile and wearable applications) to manage format objects, which derive from this module, and their string representations.

    +
      +
    1. To clone a format object: +
      +i18n_format_h original; /* original can be pointer to any object whose class derives from the Format module */
+i18n_format_h clone;
+i18n_format_clone(original, &clone);
+
      2. +
    2. To retrieve the locale from a format object: +
      +i18n_ulocale_data_locale_type_e type = I18N_ULOCALE_DATA_LOCALE_TYPE_ACTUAL_LOCALE;
+char *language = NULL;
+char *country = NULL;
+i18n_format_get_locale(format, type, &language, &country);
+/* For example, language is "en" and country is "US" */
+
      3. +
    3. To retrieve the string representation of a format object: +
        +
      • Without a field position: +
        +double double_to_set = 13.0;
+i18n_formattable_h formattable = NULL;
+i18n_formattable_create_with_double(double_to_set, &formattable);
+
+char *append_to = "Price: ";
+i18n_format_format(format, formattable, &append_to);
+/* append_to buffer now contains "Price: $13.00" string */
+
        • +
      • With a field position: +
        +double double_to_set = 13.0;
+i18n_formattable_h formattable = NULL;
+i18n_formattable_create_with_double(double_to_set, &formattable);
+char *append_to = "Price: ";
+
+i18n_field_position_h field_position = NULL;
+i18n_field_position_create(&field_position);
+i18n_format_format_with_field_position(format, formattable, &append_to, field_position);
+/* Same result as example above */
+
        • +
      4. +
    4. To parse a string to a format object: +
        +
      • Without a parse position: +
        +const char *source = "$1,234.56";
+i18n_formattable_h result = NULL;
+i18n_format_parse_object(format, source, &result);
+
+double value = 0;
+i18n_formattable_get_double(result, &value);
+/* value variable now contains 1234.56 as double */
+
        • +
      • With a parse position: +
        +char *source = "$1,234.56 $456.78";
+i18n_formattable_h result = NULL;
+i18n_parse_position_h parse_position = NULL;
+int32_t index = 10; /* Index set after 10th character in source string */
+i18n_parse_position_create_with_index(index, &parse_position);
+
+/* Parses from 10th character to next space character */
+i18n_format_parse_object_with_parse_position(format, source, parse_position, &result); 
+i18n_parse_position_destroy(parse_position);
+
+double value = 0;
+i18n_formattable_get_double(result, &value);
+/* Value retrieved is 456.78. If index was 0, result is 1234.56 */
+
        • +
      5. +
    5. When no longer needed, destroy the format object pointer: +
      +i18n_format_destroy(format);
+
      6. +
    + +

    Retrieving the ICU Version

    Since Tizen 4.0, you can retrieve the current ICU library version by using the Uversion API.

    -- 2.7.4