Added format module guide

PS4: Reviewed
PS5: Rebase

Change-Id: I27e2a37e7a1c008704c7cb9fa866013af195de83
Signed-off-by: Lukasz Pik <lu.pik@samsung.com>

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 (file)
--- a/org.tizen.guides/html/native/internationalization/i18n_n.htm
+++ b/org.tizen.guides/html/native/internationalization/i18n_n.htm
@@ -43,6 +43,9 @@
                        <li><a href="#uset">Character and String Management with Uset</a></li>
                        <li><a href="#ustring">Unicode Strings with Ustring</a></li>
                        <li><a href="#alpha_idx">Alphabetic Index Creation</a></li>
+
+                       <li><a href="#format">String Format Management</a></li>
+
                        <li><a href="#uchar_iter">String Iteration with UCharIter</a></li>
                        <li><a href="#prerequisites">Prerequisites</a></li>
                        <li><a href="#characters">Managing Characters and Strings</a></li>
@@ -54,6 +57,9 @@
                        <li><a href="#tmz">Managing Time Zones</a></li>
                        <li><a href="#manage_uset">Managing Sets</a></li>
                        <li><a href="#alpha_idx_example">Managing Alphabetic Indexes</a></li>
+
+                       <li><a href="#format_examples">Managing String Formatting</a></li>
+
                        <li><a href="#manage_version">Retrieving the ICU Version</a></li>
                        <li><a href="#uchar_iter_examples">Iterating through Strings</a></li>
                </ul>
@@ -89,6 +95,10 @@
        </li>
        <li>Managing alphabetic indexes
        <p>You can use the Alphabetic Index functions to <a href="#alpha_idx">generate a list of labels</a> that can be used as an index.</p></li>
+
+       <li>Managing string formatting
+       <p>You can use the Format functions to <a href="#format">manage the string representations of objects or values</a>.</p></li>
+
        <li>Retrieving the ICU version
        <p>You can <a href="#manage_version">retrieve the currently-used version of the ICU library</a> with Uversion.</p></li>
        <li>Iterating through strings
@@ -98,7 +108,7 @@
 
        <div class="note">
        <strong>Note</strong>
-       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.
        </div>
 
 <h2 id="ubrk" name="ubrk">Location Boundaries with Ubrk</h2>
@@ -565,6 +575,12 @@
 <p>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.</p>
 
 
+<h2 id="format" name="format">String Format Management</h2>
+<p>The Format API (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__BASE__UTILS__I18N__FORMAT__MODULE.html">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__BASE__UTILS__I18N__FORMAT__MODULE.html">wearable</a> applications) allows you to <a href="#format_examples">manage formatting for displayed strings</a>.</p>
+<p>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.</p>
+<p>There is no function for creating an <code>i18n_format_h</code> object, as this module uses a mechanism similar to inheritance in object-oriented languages. All functions with the <code>i18n_format_h</code> handle as a parameter can instead take the handle to a more specific format object from the derived classes.</p>
+
+
 <h2 id="uchar_iter" name="uchar_iter">String Iteration with UCharIter</h2>
 <p>The UCharIter API (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__BASE__UTILS__I18N__UCHARITER__MODULE.html">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__BASE__UTILS__I18N__UCHARITER__MODULE.html">wearable</a> applications) allows you to <a href="#uchar_iter_examples">iterate through strings</a>.</p>
 <p>The <code>current()</code> and <code>next()</code> functions only check the current index against the limit, and the <code>previous()</code> 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.</p>
@@ -1771,6 +1787,85 @@ i18n_alpha_idx_destroy(alpha_idx);
 </ol>
 
 
+
+<h2 id="format_examples" name="format_examples">Managing String Formatting</h2>
+<p>Since Tizen 3.0, you can use the Format API (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__BASE__UTILS__I18N__FORMAT__MODULE.html">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__BASE__UTILS__I18N__FORMAT__MODULE.html">wearable</a> applications) to manage format objects, which derive from this module, and their string representations.</p>
+<ol>
+<li>To clone a format object:
+<pre class="prettyprint">
+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, &amp;clone);
+</pre></li>
+<li>To retrieve the locale from a format object:
+<pre class="prettyprint">
+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, &amp;language, &amp;country);
+/* For example, language is "en" and country is "US" */
+</pre></li>
+<li>To retrieve the string representation of a format object:
+<ul>
+<li>Without a field position:
+<pre class="prettyprint">
+double double_to_set = 13.0;
+i18n_formattable_h formattable = NULL;
+i18n_formattable_create_with_double(double_to_set, &amp;formattable);
+
+char *append_to = "Price: ";
+i18n_format_format(format, formattable, &amp;append_to);
+/* append_to buffer now contains "Price: $13.00" string */
+</pre></li>
+<li>With a field position:
+<pre class="prettyprint">
+double double_to_set = 13.0;
+i18n_formattable_h formattable = NULL;
+i18n_formattable_create_with_double(double_to_set, &amp;formattable);
+char *append_to = "Price: ";
+
+i18n_field_position_h field_position = NULL;
+i18n_field_position_create(&amp;field_position);
+i18n_format_format_with_field_position(format, formattable, &amp;append_to, field_position);
+/* Same result as example above */
+</pre></li>
+</ul></li>
+<li>To parse a string to a format object:
+<ul>
+<li>Without a parse position:
+<pre class="prettyprint">
+const char *source = "$1,234.56";
+i18n_formattable_h result = NULL;
+i18n_format_parse_object(format, source, &amp;result);
+
+double value = 0;
+i18n_formattable_get_double(result, &amp;value);
+/* value variable now contains 1234.56 as double */
+</pre></li>
+<li>With a parse position:
+<pre class="prettyprint">
+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, &amp;parse_position);
+
+/* Parses from 10th character to next space character */
+i18n_format_parse_object_with_parse_position(format, source, parse_position, &amp;result); 
+i18n_parse_position_destroy(parse_position);
+
+double value = 0;
+i18n_formattable_get_double(result, &amp;value);
+/* Value retrieved is 456.78. If index was 0, result is 1234.56 */
+</pre></li>
+</ul></li>
+<li>When no longer needed, destroy the format object pointer:
+<pre class="prettyprint">
+i18n_format_destroy(format);
+</pre></li>
+</ol>
+
+
 <h2 id="manage_version" name="manage_version">Retrieving the ICU Version</h2>
 
 <p>Since Tizen 4.0, you can retrieve the current ICU library version by using the Uversion API.</p>