<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="#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>
<li><a href="#characters">Managing Characters and Strings</a></li>
<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="#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>
</ul>
<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>Converting time scales
+ <p>You can <a href="#utmscale">convert datetimes between time scales</a> with Utmscale.</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
<div class="note">
<strong>Note</strong>
- The Alphabetic Index, FieldPosition, and Format APIs are supported since Tizen 3.0. The Uversion and UCharIter APIs are supported since Tizen 4.0.
+ 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.
</div>
<h2 id="ubrk" name="ubrk">Location Boundaries with Ubrk</h2>
<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="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>
+
+<p>The <code>i18n_utmscale_scale_e</code> enumeration (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__BASE__UTILS__I18N__UTMSCALE__MODULE.html#ga1422c14e213019536188c0db3286e438">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__BASE__UTILS__I18N__UTMSCALE__MODULE.html#ga1422c14e213019536188c0db3286e438">wearable</a> applications) defines the supported time scales. Their details are listed in the following table.</p>
+
+
+<p align="center" class="Table"><strong>Table: Time scales</strong></p>
+<table>
+ <tbody>
+ <tr>
+ <th>Enumeration value</th>
+ <th>Usage</th>
+ <th>Datatype</th>
+ <th>Unit</th>
+ <th>Epoch</th>
+ </tr>
+ <tr>
+ <td><code>I18N_UTMSCALE_JAVA_TIME</code></td>
+ <td>Java Development Kit</td>
+ <td><code>int64_t</code></td>
+ <td>milliseconds</td>
+ <td>January 1, 1970</td>
+ </tr>
+ <tr>
+ <td><code>I18N_UTMSCALE_UNIX_TIME</code></td>
+ <td>Unix systems</td>
+ <td><code>int32_t or int64_t</code></td>
+ <td>seconds</td>
+ <td>January 1, 1970</td>
+ </tr>
+ <tr>
+ <td><code>I18N_UTMSCALE_ICU4C_TIME</code></td>
+ <td>ICU4C</td>
+ <td><code>double</code></td>
+ <td>milliseconds</td>
+ <td>January 1, 1970</td>
+ </tr>
+ <tr>
+ <td><code>I18N_UTMSCALE_WINDOWS_FILE_TIME</code></td>
+ <td>Windows file times</td>
+ <td><code>int64_t</code></td>
+ <td>ticks (1 tick = 100 nanoseconds)</td>
+ <td>January 1, 1601</td>
+ </tr>
+ <tr>
+ <td><code>I18N_UTMSCALE_DOTNET_DATE_TIME</code></td>
+ <td>.NET framework <code>System.DataTime</code> structure</td>
+ <td><code>int64_t</code></td>
+ <td>ticks (1 tick = 100 nanosecods)</td>
+ <td>January 1, 0001</td>
+ </tr>
+ <tr>
+ <td><code>I18N_UTMSCALE_MAC_OLD_TIME</code></td>
+ <td>Older Macintosh systems</td>
+ <td><code>int32_t or int64_t</code></td>
+ <td>seconds</td>
+ <td>January 1, 1904</td>
+ </tr>
+ <tr>
+ <td><code>I18N_UTMSCALE_MAC_TIME</code></td>
+ <td>Newer Macintosh systems</td>
+ <td><code>double</code></td>
+ <td>seconds</td>
+ <td>January 1, 2001</td>
+ </tr>
+ <tr>
+ <td><code>I18N_UTMSCALE_EXCEL_TIME</code></td>
+ <td>Excel</td>
+ <td>?</td>
+ <td>days</td>
+ <td>December 31, 1899</td>
+ </tr>
+ <tr>
+ <td><code>I18N_UTMSCALE_DB2_TIME</code></td>
+ <td>DB2</td>
+ <td>?</td>
+ <td>days</td>
+ <td>December 31, 1899</td>
+ </tr>
+ <tr>
+ <td><code>I18N_UTMSCALE_UNIX_MICROSECONDS_TIME</code></td>
+ <td>Unix systems</td>
+ <td><code>long</code></td>
+ <td>microseconds</td>
+ <td>January 1, 1970</td>
+ </tr>
+ </tbody>
+</table>
+<p>All the epochs start at 00:00 AM (the earliest possible time on the day in question), and are assumed to be UTC.</p>
+<p>The ranges for different datatypes are given in the following table, with all values in years. The range of years includes the entire range expressible with positive and negative values of the datatype. The range of years for <code>double</code> is the range that does not lose precision to the corresponding unit.</p>
+
+<p align="center" class="Table"><strong>Table: Datatype ranges</strong></p>
+<table>
+ <tr>
+ <th>Unit</th>
+ <th><code>int64_t</code></th>
+ <th><code>double</code></th>
+ <th><code>int32_t</code></th>
+ </tr>
+ <tr>
+ <td>1 second</td>
+ <td>5.84542×10<sup>11</sup></td>
+ <td>285,420,920.94</td>
+ <td>136.10</td>
+ </tr>
+ <tr>
+ <td>1 millisecond</td>
+ <td>584,542,046.09</td>
+ <td>285,420.92</td>
+ <td>0.14</td>
+ </tr>
+ <tr>
+ <td>1 microsecond</td>
+ <td>584,542.05</td>
+ <td>285.42</td>
+ <td>0.00</td>
+ </tr>
+ <tr>
+ <td>100 nanoseconds (tick)</td>
+ <td>58,454.20</td>
+ <td>28.54</td>
+ <td>0.00</td>
+ </tr>
+ <tr>
+ <td>1 nanosecond</td>
+ <td>584.5420461</td>
+ <td>0.2854</td>
+ <td>0.00</td>
+ </tr>
+</table>
+
+<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>
</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>
+<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">
</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>
+<ol>
+<li>To retrieve conversion constants for a specific time scale, use the <code>i18n_utmscale_get_time_scale_value()</code> function with the values of the <code>i18n_utmscale_value_e</code> enumeration (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__BASE__UTILS__I18N__UTMSCALE__MODULE.html#ga34893d20b446359e32767b57e6cdde29">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__BASE__UTILS__I18N__UTMSCALE__MODULE.html#ga34893d20b446359e32767b57e6cdde29">wearable</a> applications):
+<pre class="prettyprint">
+int64_t value = NULL;
+i18n_utmscale_get_time_scale_value(I18N_UTMSCALE_JAVA_TIME, I18N_UTMSCALE_VALUE_UNITS, &value);
+/* Returns 10000, the number of universal time units (ticks) in each Java time unit (milliseconds) */
+</pre>
+</li>
+<li>To convert the retrieved <code>int64_t</code> Java time to universal time scale:
+<pre class="prettyprint">
+int64_t universal_time = NULL;
+i18n_utmscale_from_int64(value, I18N_UTMSCALE_ICU4C_TIME, &universal_time);
+</pre></li>
+<li>To convert the universal time value back to Java time:
+<pre class="prettyprint">
+i18n_utmscale_to_int64(universal_time, I18N_UTMSCALE_JAVA_TIME, &value);
+</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>
+<p>Since Tizen 4.0, you can retrieve the current ICU library version by using the Uversion API (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__BASE__UTILS__I18N__UVERSION__MODULE.html">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__BASE__UTILS__I18N__UVERSION__MODULE.html">wearable</a> applications).</p>
<p>To retrieve the current version:</p>
<ol>
<li>To get the current ICU version, use the <code>i18n_uversion_get_version()</code> function, which returns the version number in a <code>uversion</code> array, in hexadecimal format:
projects / sdk / online-doc.git / commitdiff