[ACR-661] Added measure guides

PS2: Reviewed

Change-Id: Ie5b2b10134c0d451b6d9f0352bc2dbd007a6fa91
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 a95b050..8378052 100644 (file)
--- a/org.tizen.guides/html/native/internationalization/i18n_n.htm
+++ b/org.tizen.guides/html/native/internationalization/i18n_n.htm
@@ -45,6 +45,7 @@
                        <li><a href="#alpha_idx">Alphabetic Index Creation</a></li>
                        <li><a href="#field_pos">Field Identification in Formatted Output</a></li>
                        <li><a href="#format">String Format Management</a></li>
+                       <li><a href="#measure">Measurement Values with Units</a></li>
                        <li><a href="#utmscale">Time Scale Conversion with Utmscale</a></li>
                        <li><a href="#uchar_iter">String Iteration with UCharIter</a></li>
                        <li><a href="#prerequisites">Prerequisites</a></li>
@@ -59,6 +60,7 @@
                        <li><a href="#alpha_idx_example">Managing Alphabetic Indexes</a></li>
                        <li><a href="#field_pos_example">Managing the Field Position</a></li>
                        <li><a href="#format_examples">Managing String Formatting</a></li>
+                       <li><a href="#measure_examples">Managing Measure Objects</a></li>
                        <li><a href="#utmscale_examples">Converting Time Scales</a></li>
                        <li><a href="#manage_version">Retrieving the ICU Version</a></li>
                        <li><a href="#uchar_iter_examples">Iterating through Strings</a></li>
@@ -99,6 +101,8 @@
        <p>You can <a href="#field_pos">identify fields for formatting purposes</a> with FieldPosition.</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>Managing measurement values with units
+       <p>You can <a href="#measure">store numeric measurement values with various units.</a></p></li>
        <li>Converting time scales
        <p>You can <a href="#utmscale">convert datetimes between time scales</a> with Utmscale.</p></li>
        <li>Retrieving the ICU version
@@ -110,7 +114,7 @@
 
        <div class="note">
        <strong>Note</strong>
-       The Alphabetic Index, FieldPosition, Format, and Utmscale APIs are supported since Tizen 3.0. The Uversion and UCharIter APIs are supported since Tizen 4.0.
+       The Alphabetic Index, FieldPosition, Format, Measure, and Utmscale 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>
@@ -586,6 +590,11 @@
 <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="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>
+
+The measure objects can be formatted using the MeasureFormat API (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__BASE__UTILS__I18N__MEASURE__FORMAT__MODULE.html">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__BASE__UTILS__I18N__MEASURE__FORMAT__MODULE.html">wearable</a> applications).
+
 <h2 id="utmscale" name="utmscale">Time Scale Conversion with Utmscale</h2>
 <p>The Utmscale API (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__BASE__UTILS__I18N__UTMSCALE__MODULE.html">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__BASE__UTILS__I18N__UTMSCALE__MODULE.html">wearable</a> applications) allows you to <a href="#utmscale_examples">convert between time scales</a>.</p>
 <p>There are various conventions for binary datetime, depending on the platform and protocol. Some of these have severe drawbacks. For example, 32-bit Unix time (seconds since Jan 1, 1970) cannot support datetimes beyond the beginning of the year 2038. Arithmetic manipulations can also cause serious problems. For example, when calculating the average of 2 datetimes, if you calculate them with <code>average_time = (time1 + time2)/2</code>, there can be overflow even with dates around the present. Additionally, there is the issue of converting between different systems.</p>
@@ -720,7 +729,6 @@
 
 <p>ICU implements the .NET framework <code>System.DateTime</code> as the universal time scale 'pivot', and uses the full range allowed by the datatype, allowing for datetimes back to 29,000 BC and up to 29,000 AD. This time scale is very fine-grained, does not lose precision, and covers a range that meets most requirements. Using the Utmscale functions, datetimes can be converted to the pivot time scale, safely manipulated, and converted back to any other time scale.</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>
@@ -2068,6 +2076,52 @@ i18n_format_destroy(format);
 </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>
+
+  <div class="note">
+        <strong>Note</strong>
+        A measure object is immutable, so if you want to change its value, you must create a new object with the new value.
+  </div>
+
+<p>To manage measure objects:</p>
+<ol>
+<li>To create a measure object:
+<pre class="prettyprint">
+i18n_measure_h measure;
+i18n_formattable_h formattable;
+i18n_measure_unit_h unit;
+double value = 7;
+
+i18n_formattable_create_with_double(value, &amp;formattable);
+i18n_measure_unit_create_gigabit(&amp;unit);
+
+i18n_measure_create(formattable, unit, &amp;measure);
+/* Created object contains "7 Gigabits" */
+</pre></li>
+<li>To clone a measure object:
+<pre class="prettyprint">
+i18n_measure_h clone;
+i18n_measure_clone(measure, &amp;clone);
+</pre></li>
+<li>To get the numeric value:
+<pre class="prettyprint">
+i18n_formattable_h formattable;
+i18n_measure_get_number(measure, &amp;formattable);
+/* formattable contains 7 as double */
+</pre></li>
+<li>To get the measurement unit:
+<pre class="prettyprint">
+i18n_measure_unit_h unit;
+i18n_measure_get_unit(measure, &amp;unit);
+/* unit contains Gigabits value */
+</pre></li>
+<li>When no longer needed, destroy the measure object:
+<pre class="prettyprint">
+i18n_measure_destroy(measure);
+</pre></li>
+</ol>
+
 <h2 id="utmscale_examples" name="utmscale_examples">Converting Time Scales</h2>
 <p>Since Tizen 3.0, you can use the Utmscale API (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__BASE__UTILS__I18N__UTMSCALE__MODULE.html">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__BASE__UTILS__I18N__UTMSCALE__MODULE.html">wearable</a> applications) to convert binary datetimes between various platform-dependent time scales.</p>
 <p>To convert a datetime value:</p>