Added formattable guide

PS2: Reviewed
PS3: Rebase

Change-Id: Ifc0d194bd4bbd6d2799010afd632904d790b835a
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 8378052..ae02bac 100644 (file)
--- a/org.tizen.guides/html/native/internationalization/i18n_n.htm
+++ b/org.tizen.guides/html/native/internationalization/i18n_n.htm
@@ -590,6 +590,10 @@
 <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>
 
+<p>The Formattable API (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__BASE__UTILS__I18N__FORMATTABLE__MODULE.html">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__BASE__UTILS__I18N__FORMATTABLE__MODULE.html">wearable</a> applications) allows you to <a href="#formattable_examples">interconvert between Udate, char string, and primitive numeric types</a>, such as double and long.</p>
+<p>Internally, an <code>i18n_formattable_h</code> handle holds an object that is a union of primitive types. As such, it can only store 1 flavor of data at a time. To determine what flavor of data it contains, use the <code>i18n_formattable_get_type()</code> function.</p>
+<p>The Formattable API is a helping object for the Format API and its derived format objects. The formattable object holds the value to be formatted or the formatting result.</p>
+
 <h2 id="measure" name="measure">Measurement Values with Units</h2>
 <p>The Measure API (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__BASE__UTILS__I18N__MEASURE__MODULE.html">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__BASE__UTILS__I18N__MEASURE__MODULE.html">wearable</a> applications) allows you to <a href="#measure_examples">create measure objects containing a numerical value and a measurement unit</a>. You can, for example, store a length value in feet or meters.</p>
 
@@ -2076,6 +2080,77 @@ i18n_format_destroy(format);
 </pre></li>
 </ol>
 
+<h3 id="formattable_examples" name="formattable_examples">Converting Between Types</h3>
+You can use the Formattable API (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__BASE__UTILS__I18N__FORMATTABLE__MODULE.html">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__BASE__UTILS__I18N__FORMATTABLE__MODULE.html">wearable</a> applications) to convert between data types.
+
+<p>To manage formattable objects:</p>
+<ol>
+<li>To create a formattable handler:
+<ul>
+<li>Without a specified data type:
+<pre class="prettyprint">
+i18n_formattable_h formattable;
+i18n_formattable_create_default(&amp;formattable);
+</pre></li>
+<li>With a specified data type, for example, <code>double</code>:
+<pre class="prettyprint">
+double value = 20;
+i18n_formattable_create_double(value, &amp;formattable);
+</pre>
+<p>You can also create handles for <code>udate</code>, <code>long</code>, <code>int64</code>, <code>char</code> pointer, and formattable array.</p></li>
+</ul></li>
+<li>To clone a formattable object:
+<pre class="prettyprint">
+i18n_formattable_h clone;
+i18n_formattable_clone(formattable, &amp;clone);
+</pre></li>
+<li>To retrieve formattable object information:
+    <ul>
+        <li>To check whether the value in the formattable object is numeric:
+<pre class="prettyprint">
+bool is_numeric;
+i18n_formattable_is_numeric(formattable, &amp;is_numeric);
+</pre></li>
+        <li>To get the data type of the value in a formattable object:
+<pre class="prettyprint">
+i18n_formattable_type_e type;
+i18n_formattable_get_type(formattable, &amp;type);
+</pre></li>
+        <li>To retrieve the value of the formattable object, use the <code>i18n_formattable_get_xxx()</code> function corresponding to the value's data type:
+        <pre class="prettyprint">
+double value;
+i18n_formattable_get_double(formattable, &amp;value);
+</pre>
+</li>
+<li>To compare whether 2 formattable objects are equal:
+<pre class="prettyprint">
+bool equal;
+i18n_formattable_equal(formattable, clone, &amp;equal);
+</pre>
+<p>You can also compare whether 2 objects are not equal, using the <code>i18n_formattable_not_equal()</code> function.</p></li>
+</ul></li>
+<li>To set a formattable object in a formattable array:
+<pre class="prettyprint">
+i18n_formattable_h array[3] = {NULL};
+i18n_formattable_h element;
+
+i18n_formattable_create_with_formattable_array(array, 3, &amp;formattable);
+i18n_formattable_create_double(30, &amp;element);
+
+i18n_formattable_element_at(formattable, 0, &amp;element);
+</pre></li>
+<li>To set the type of a formattable object, for example, to <code>int64_t</code>:
+<pre class="prettyprint">
+int64_t value = 15;
+i18n_formattable_set_int64(formattable, value);
+</pre>
+<p>You can also set the type to <code>double</code>, <code>array</code>, <code>udate</code>, <code>long</code>, or <code>string</code>, using the corresponding <code>i18n_formattable_set_xxx()</code> function.</p></li>
+<li>When no longer needed, destroy the formattable object pointer:
+<pre class="prettyprint">
+i18n_formattable_destroy(formattable);
+</pre></li>
+</ol>
+
 <h2 id="measure_examples" name="measure_examples">Managing Measure Objects</h2>
 <p>Since Tizen 3.0, you can use the Measure API (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__BASE__UTILS__I18N__MEASURE__MODULE.html">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__BASE__UTILS__I18N__MEASURE__MODULE.html">wearable</a> applications) to create measure objects, containing a numerical value and a measurement unit.</p>