src/include/wearable/utils_i18n_ucollator.h

   1 /*
   2  * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  *    Licensed under the Apache License, Version 2.0 (the "License");
   5  *    you may not use this file except in compliance with the License.
   6  *    You may obtain a copy of the License at
   7  *
   8  *        http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  *    Unless required by applicable law or agreed to in writing, software
  11  *    distributed under the License is distributed on an "AS IS" BASIS,
  12  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  *    See the License for the specific language governing permissions and
  14  *    limitations under the License.
  15  */
  16
  17 #ifndef __UTILS_I18N_UCOLLATOR_H__
  18 #define __UTILS_I18N_UCOLLATOR_H__
  19
  20 #include <utils_i18n_types.h>
  21
  22 /**
  23  * @file utils_i18n_ucollator.h
  24  * @version 0.1
  25  * @brief utils_i18n_ucollator
  26  */
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 # endif
  31
  32 /**
  33  * @ingroup CAPI_BASE_UTILS_I18N_MODULE
  34  * @defgroup CAPI_BASE_UTILS_I18N_UCOLLATOR_MODULE Ucollator
  35  * @brief The Ucollator module performs locale-sensitive string comparison.
  36  *
  37  * @section CAPI_BASE_UTILS_I18N_UCOLLATOR_MODULE_HEADER Required Header
  38  *  \#include <utils_i18n.h>
  39  *
  40  * @section CAPI_BASE_UTILS_I18N_UCOLLATOR_MODULE_OVERVIEW Overview
  41  * @details The Ucollator module performs locale-sensitive string comparison. It builds searching and sorting routines for natural language text and provides correct sorting orders for most locales supported.
  42  *
  43  * @section CAPI_BASE_UTILS_I18N_UCOLLATOR_MODULE_SAMPLE_CODE_1 Sample Code 1
  44  * @brief Converts two different byte strings to two different unicode strings and compares the unicode strings to check if the strings are equal to each other.
  45  * @code
  46     i18n_uchar uchar_src[64] = {0,};
  47     i18n_uchar uchar_target[64] = {0,};
  48     char *src = "tizen";
  49     char *target = "bada";
  50     int uchar_src_len = 0;
  51     int uchar_target_len = 0;
  52     i18n_ucollator_h coll = NULL;
  53     i18n_ubool result = NULL;
  54
  55     i18n_ustring_from_UTF8( uchar_src, 64, NULL, src, -1 );
  56     i18n_ustring_from_UTF8( uchar_target, 64, NULL, target, -1 );
  57
  58     // creates a collator
  59     i18n_ucollator_create( "en_US", &coll );
  60
  61     // sets strength for coll
  62     i18n_ucollator_set_strength( coll, I18N_UCOLLATOR_PRIMARY );
  63
  64     // compares uchar_src with uchar_target
  65     i18n_ustring_get_length( uchar_src, &uchar_src_len );
  66     i18n_ustring_get_length( uchar_target, &uchar_target_len );
  67     i18n_ucollator_equal( coll, uchar_src, uchar_src_len, uchar_target, uchar_target_len, &result );
  68     dlog_print(DLOG_INFO, LOG_TAG, "%s %s %s\n", src, result == 1 ? "is equal to" : "is not equal to", target );    // tizen is not equal to bada
  69
  70     // destroys the collator
  71     i18n_ucollator_destroy( coll );
  72  * @endcode
  73  * @section CAPI_BASE_UTILS_I18N_UCOLLATOR_MODULE_SAMPLE_CODE_2 Sample Code 2
  74  * @brief Sorts in ascending order on the given data using string_ucollator
  75  * @code
  76     i18n_ucollator_h coll = NULL;
  77     char *src[3] = { "cat", "banana", "airplane" };
  78     char *tmp = NULL;
  79     i18n_uchar buf_01[16] = {0,};
  80     i18n_uchar buf_02[16] = {0,};
  81     i18n_ucollator_result_e result = I18N_UCOLLATOR_EQUAL;
  82     int i = 0, j = 0;
  83     int ret = I18N_ERROR_NONE;
  84     int buf_01_len = 0, buf_02_len = 0;
  85
  86     for ( i = 0; i < sizeof( src ) / sizeof( src[0] ); i++ ) {
  87         dlog_print(DLOG_INFO, LOG_TAG, "%s\n", src[i] );
  88     }    // cat    banana    airplane
  89
  90     // creates a collator
  91     ret = i18n_ucollator_create( "en_US", &coll );
  92
  93     // compares and sorts in ascending order
  94     if ( ret == I18N_ERROR_NONE ) {
  95         i18n_ucollator_set_strength( coll, I18N_UCOLLATOR_TERTIARY );
  96         for ( i = 0; i < 2; i++ ) {
  97             for ( j = 0; j < 2 - i; j++ ) {
  98                 i18n_ustring_copy_ua( buf_01, src[j] );
  99                 i18n_ustring_copy_ua( buf_02, src[j+1] );
 100                 i18n_ustring_get_length( buf_01, &buf_01_len );
 101                 i18n_ustring_get_length( buf_02, &buf_02_len );
 102                 // compares buf_01 with buf_02
 103                 i18n_ucollator_str_collator( coll, buf_01, buf_01_len, buf_02, buf_02_len, &result );
 104                 if ( result == I18N_UCOLLATOR_GREATER ) {
 105                     tmp = src[j];
 106                     src[j] = src[j+1];
 107                     src[j+1] = tmp;
 108                 }
 109             }
 110         }
 111     }
 112     // destroys the collator
 113     i18n_ucollator_destroy( coll );    // deallocate memory for collator
 114
 115     for ( i = 0; i < sizeof( src ) / sizeof( src[0] ); i++ ) {
 116         dlog_print(DLOG_INFO, LOG_TAG, "%s\n", src[i] );
 117     }    // ariplane    banana    cat
 118  * @endcode
 119  */
 120
 121 /**
 122  * @addtogroup CAPI_BASE_UTILS_I18N_UCOLLATOR_MODULE
 123  * @{
 124  */
 125
 126 /**
 127  * @brief Creates a i18n_ucollator_h for comparing strings.
 128  * @details The i18n_ucollator_h is used in all the calls to the Collation service.\n
 129  * After finished, collator must be disposed off by calling {@link #i18n_ucollator_destroy()}.
 130  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 131  * @remarks Must release @a collator using i18n_ucollator_destroy().
 132  *
 133  * @param[in] locale The locale containing the required collation rules\n
 134  * Special values for locales can be passed in - if @c NULL is passed for the locale, the default locale collation rules will be used \n
 135  * If empty string ("") or "root" is passed, UCA rules will be used.
 136  * @param[out] collator i18n_ucollator_h, otherwise @c 0 if an error occurs
 137  *
 138  * @retval #I18N_ERROR_NONE Successful
 139  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 140  * @see i18n_ucollator_destroy()
 141  */
 142 int i18n_ucollator_create ( const char *locale, i18n_ucollator_h *collator );
 143
 144 /**
 145  * @brief Closes a i18n_ucollator_h.
 146  * @details Once closed, a string_ucollator_h should not be used. Every an open collator should be closed. Otherwise, a memory leak will result.
 147  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 148  *
 149  * @param[in] collator The i18n_ucollator_h to close
 150  *
 151  * @retval #I18N_ERROR_NONE Successful
 152  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 153  * @see i18n_ucollator_create()
 154  */
 155 int i18n_ucollator_destroy ( i18n_ucollator_h collator );
 156
 157 /**
 158  * @brief Compares two strings.
 159  * @details The strings will be compared using the options already specified.
 160  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 161  *
 162  * @param[in] collator The i18n_ucollator_h containing the comparison rules
 163  * @param[in] src The source string
 164  * @param[in] src_len The length of the source, otherwise @c -1 if null-terminated
 165  * @param[in] target The target string.
 166  * @param[in] target_len The length of the target, otherwise @c -1 if null-terminated
 167  * @param[out] result The result of comparing the strings \n
 168  * One of #I18N_UCOLLATOR_EQUAL, #I18N_UCOLLATOR_GREATER, or #I18N_UCOLLATOR_LESS
 169  *
 170  * @retval #I18N_ERROR_NONE Successful
 171  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 172  * @see i18n_ucollator_equal()
 173  */
 174 int i18n_ucollator_str_collator ( const i18n_ucollator_h collator, const i18n_uchar *src, int32_t src_len, const i18n_uchar *target, int32_t target_len, i18n_ucollator_result_e *result );
 175
 176 /**
 177  * @brief Compares two strings for equality.
 178  * @details This function is equivalent to {@link #i18n_ucollator_str_collator()}.
 179  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 180  *
 181  * @param[in] collator The i18n_ucollator_h containing the comparison rules
 182  * @param[in] src The source string
 183  * @param[in] src_len The length of the source, otherwise @c -1 if null-terminated
 184  * @param[in] target The target string
 185  * @param[in] target_len The length of the target, otherwise @c -1 if null-terminated
 186  * @param[out] equal If @c true source is equal to target, otherwise @c false
 187  *
 188  * @retval #I18N_ERROR_NONE Successful
 189  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 190  * @see i18n_ucollator_str_collator()
 191  */
 192 int i18n_ucollator_equal ( const i18n_ucollator_h collator, const i18n_uchar *src, int32_t src_len, const i18n_uchar *target, int32_t target_len, i18n_ubool *equal );
 193
 194 /**
 195  * @brief Sets the collation strength used in a collator.
 196  * @details The strength influences how strings are compared.
 197  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 198  *
 199  * @param[in] collator The i18n_collator_h to set.
 200  * @param[in] strength The desired collation strength.\n
 201  *     One of #i18n_ucollator_strength_e
 202  *
 203  * @retval #I18N_ERROR_NONE Successful
 204  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 205  */
 206 int i18n_ucollator_set_strength ( i18n_ucollator_h collator, i18n_ucollator_strength_e strength );
 207
 208 /**
 209  * @brief Sets a universal attribute setter.
 210  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 211  *
 212  * @param[in] collator The i18n_collator_h containing attributes to be changed
 213  * @param[in] attr The attribute type
 214  * @param[in] val The attribute value
 215  *
 216  * @retval #I18N_ERROR_NONE Successful
 217  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 218  */
 219 int i18n_ucollator_set_attribute ( i18n_ucollator_h collator, i18n_ucollator_attribute_e attr, i18n_ucollator_attribute_value_e val );
 220
 221 #ifdef __cplusplus
 222 }
 223 #endif
 224
 225 /**
 226  * @}
 227  * @}
 228  */
 229
 230 #endif  /* __UTILS_I18N_UCOLLATOR_H__*/