From 80a602f3f82114270bfd781148977dec4f8da569 Mon Sep 17 00:00:00 2001
From: Lukasz Pik <lu.pik@samsung.com>
Date: Tue, 26 Sep 2017 11:40:05 +0200
Subject: [PATCH] [ACR-889] Update ucollator guides

PS2: Reviewed

Change-Id: I0c7edd00fa201e0077d9c058c0927a5d6a361890
Signed-off-by: Lukasz Pik <lu.pik@samsung.com>
---
 .../html/native/internationalization/i18n_n.htm    | 120 ++++++++++++++++++++-
 1 file changed, 119 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 fbb777f..b31c644 100644
--- a/org.tizen.guides/html/native/internationalization/i18n_n.htm
+++ b/org.tizen.guides/html/native/internationalization/i18n_n.htm
@@ -603,6 +603,11 @@ i18n_ucollator_create(I18N_ULOCALE_US, &amp;coll);
 
 <pre class="prettyprint">
 i18n_ucollator_set_strength(coll, I18N_UCOLLATOR_DEFAULT_STRENGTH);
+</pre>
+<p>Since Tizen 4.0, you can also retrieve the current Ucollator strength using the <code>i18n_ucollator_get_strength()</code> function:</p>
+<pre class="prettyprint">
+i18n_ucollator_strength_e strength;
+i18n_ucollator_get_strength(coll, &amp;strength);
 </pre></li>
 <li>Compare 2 Ustrings.
 <p>To compare 2 Ustrings, you have 2 options:</p>
@@ -617,11 +622,124 @@ i18n_ucollator_equal(coll, s1, -1, s2, -1, &amp;equal);
 
 i18n_ucollator_result_e result;
 i18n_ucollator_str_collator(coll, s1, -1, s2, -1, &amp;result);
+</pre>
+<p>Since Tizen 4.0, you can use the <code>i18n_ucollator_greater_or_equal()</code> function to check whether the first string is greater or equal to the second string:</p>
+<pre class="prettyprint">
+i18n_ubool result;
+i18n_ucollator_greater_or_equal(coll, s1, -1, s2, -1, &amp;result);
 </pre></li>
 <li>When no longer needed, destroy the Ucollator using the <code>i18n_ucollator_destroy()</code> function:
 <pre class="prettyprint">
 i18n_ucollator_destroy(coll);
-</pre></li></ol>
+</pre></li>
+</ol>
+
+<p>Since Tizen 4.0, you can also:</p>
+<ul><li>Check which locales the Ucollator API works with:
+<ul><li>Retrieve an enumeration with all supported locales with the <code>i18n_ucollator_create_available_locales()</code> function:
+<pre class="prettyprint">
+i18n_uenumeration_h locales;
+i18n_ucollator_create_available_locales(&amp;locales);
+</pre></li>
+<li>Retrieve the count of all supported locales with the <code>i18n_ucollator_count_available()</code> function:
+<pre class="prettyprint">
+int32_t n_available;
+i18n_ucollator_count_available(&amp;n_available);
+</pre></li>
+<li>Retrieve a locale with a specified index by using the <code>i18n_ucollator_get_available()</code> function:
+<pre class="prettyprint">
+const char *locale = NULL;
+int32_t locale_index = 0;
+i18n_ucollator_get_available(locale_index, &amp;locale);
+</pre></li></ul></li>
+<li>Clone a given collator in a thread-safe way:
+<pre class="prettyprint">
+i18n_ucollator_h collator;
+i18n_collator_create(I18N_ULOCALE_US, &amp;collator);
+i18n_ucollator_h clone;
+
+i18n_ucollator_safe_clone(collator, &amp;clone);
+</pre></li>
+<li>Retrieve version information:
+<ul><li>Ucollator version:
+<pre class="prettyprint">
+i18n_uversion_info info;
+i18n_ucollator_get_version(coll, info);
+</pre></li>
+<li>UCA version information for Ucollator:
+<pre class="prettyprint">
+i18n_uversion_info info;
+i18n_ucollator_get_uca_version(coll, info);
+</pre></li>
+</ul></li>
+<li>Manage keywords:
+<ul>
+<li>Retrieve an enumeration containing all possible keywords that are relevant to a collation:
+<pre class="prettyprint">
+i18n_uenumeration_h keywords;
+i18n_ucollator_get_keywords(&amp;keywords);
+</pre></li>
+<li>Retrieve all currently-used values of a keyword:
+<pre class="prettyprint">
+i18n_uenumeration_h keyword_values;
+i18n_ucollator_get_keyword_values("collation", &amp;keyword_values);
+</pre></li>
+<li>Retrieve an array of string values in a preferred order that can make a difference, based on the keyword and locale:
+<pre class="prettyprint">
+i18n_uenumeration_h keywords;
+i18n_ucollator_get_keyword_values_for_locale("collation", "en_US", false, &amp;keywords);
+</pre></li></ul></li>
+<li>Manage sort keys:
+<ul><li>Retrieve a sort key with the <code>i18n_ucollator_get_sort_key()</code> function:
+<pre class="prettyprint">
+i18n_uchar src[64];
+i18n_ustring_copy_ua(src, str1);
+uint8_t sort_key[64];
+int32_t result_length;
+i18n_ucollator_get_sort_key(g_coll, src, -1, 64, sort_key, &amp;result_length);
+</pre></li>
+<li>Retrieve the next count bytes of a sort key with the <code>i18n_ucollator_next_sort_key_part()</code> function:
+<pre class="prettyprint">
+uint32_t state[2];
+uint8_t dest[64];
+int32_t result_length;
+i18n_uchar_iter_h iter = NULL;
+
+i18n_uchar_iter_create(&amp;iter);
+i18n_uchar_iter_set_utf8(iter, str1, strlen(str1));
+i18n_ucollator_next_sort_key_part(g_coll, iter, state, dest, 1, &amp;result_length);
+</pre></li>
+<li>Retrieve a bound for a given sort key and a number of levels by using the <code>i18n_ucollator_get_bound()</code> function:
+<pre class="prettyprint">
+i18n_uchar src[64];
+i18n_ustring_copy_ua(src, str1);
+uint8_t sort_key[64];
+int32_t result_length;
+uint8_t bound[128];
+int32_t bound_length;
+
+i18n_ucollator_get_sort_key(g_coll, src, -1, 64, sort_key, &amp;result_length);
+i18n_ucollator_get_bound(sort_key, result_length, I18N_UCOLLATOR_BOUND_UPPER, 1, bound, 128, &amp;bound_length);
+</pre></li>
+<li>Merge 2 sort keys with the <code>i18n_ucollator_merge_sort_keys()</code> function:
+<pre class="prettyprint">
+i18n_uchar src1[64];
+i18n_uchar src2[64];
+i18n_ustring_copy_ua(src1, "First string");
+i18n_ustring_copy_ua(src2, "Second string");
+uint8_t sort_key1[64];
+uint8_t sort_key2[64];
+
+int32_t result_length1;
+int32_t result_length2;
+uint8_t merged[128];
+int32_t merged_length;
+
+i18n_ucollator_get_sort_key(g_coll, src1, -1, 64, sort_key1, &amp;result_length1);
+i18n_ucollator_get_sort_key(g_coll, src2, -1, 64, sort_key2, &amp;result_length2);
+i18n_ucollator_merge_sort_keys(sort_key1, result_length1, sort_key2, result_length2, 128, merged, &amp;merged_length);
+</pre></li></ul></li>
+</ul>
 
 <h3 id="strings" name="strings">Converting Strings to Ustrings</h3>
 <p>To convert strings to Ustrings:</p>
-- 
2.7.4