src/include/wearable/utils_i18n_uset.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  * Copyright (C) 1999-2013, International Business Machines Corporation
  17  * and others. All Rights Reserved.
  18  */
  19
  20 #ifndef __UTILS_I18N_USET_PRODUCT_H__
  21 #define __UTILS_I18N_USET_PRODUCT_H__
  22
  23 #include <utils_i18n_types.h>
  24
  25 /**
  26  * @file utils_i18n_uset.h
  27  * @version 0.1
  28  * @brief utils_i18n_uset
  29  */
  30
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /**
  37  * @ingroup CAPI_BASE_UTILS_I18N_MODULE
  38  * @defgroup CAPI_BASE_UTILS_I18N_USET_MODULE Uset
  39  * @brief Uset module allows to specify a subset of character used in strings.
  40  *
  41  * @section CAPI_BASE_UTILS_I18N_USET_MODULE_HEADER Required Header
  42  *  \#include <utils_i18n.h>
  43  *
  44  * @section CAPI_BASE_UTILS_I18N_USET_MODULE_OVERVIEW Overview
  45  * @details Uset module allows to specify a subset of character used in strings.
  46  */
  47
  48 /**
  49  * @addtogroup CAPI_BASE_UTILS_I18N_USET_MODULE
  50  * @{
  51  */
  52
  53 /**
  54  * @brief Creates an empty #i18n_uset_h object.
  55  * @details Equivalent to i18n_uset_create(1, 0).
  56  *
  57  * @since_tizen 2.3.1
  58  * @param[out] set A pointer to the newly created #i18n_uset_h. The caller must call i18n_uset_destroy() on
  59  * it when done.
  60  *
  61  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
  62  * @retval #I18N_ERROR_NONE Successful
  63  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
  64  * @see i18n_uset_destroy()
  65  */
  66 int i18n_uset_create_empty (i18n_uset_h *set);
  67
  68 /**
  69  * @brief Creates an #i18n_uset_h object that contains the range of characters
  70  * start..end, inclusive.
  71  * @details If <code>start > end</code>
  72  * then an empty set is created (same as using i18n_uset_empty_create()).
  73  *
  74  * @since_tizen 2.3.1
  75  * @param[in] start First character of the range, inclusive
  76  * @param[in] end Last character of the range, inclusive
  77  * @param[out] set A pointer to the newly created #i18n_uset_h object. The caller must call i18n_uset_destroy() on
  78  * it when done.
  79  * * @return Error code. Error codes not listed below are described in #i18n_error_code_e
  80  * @retval #I18N_ERROR_NONE Successful
  81  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
  82  * @see i18n_uset_destroy()
  83  */
  84 int i18n_uset_create (i18n_uchar32 start, i18n_uchar32 end, i18n_uset_h *set);
  85
  86 /**
  87  * @brief Creates a set based on a given pattern.
  88  * @details See the UnicodeSet class description for the syntax
  89  * of the pattern language.
  90  *
  91  * @since_tizen 2.3.1
  92  * @param[in] pattern A string specifying what characters are in the set
  93  * @param[in] pattern_length The length of the pattern, >= 0, or -1 if NULL-terminated.
  94  * @param[out] set A pointer to the newly created #i18n_uset_h object. The caller must call i18n_uset_destroy() on
  95  * it when done.
  96  * * @return Error code. Error codes not listed below are described in #i18n_error_code_e
  97  * @retval #I18N_ERROR_NONE Successful
  98  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
  99  * @see i18n_uset_destroy()
 100  */
 101 int i18n_uset_create_pattern (const i18n_uchar *pattern, int32_t pattern_length, i18n_uset_h *set);
 102
 103 /**
 104  * @brief Creates a set based on a given pattern.
 105  * @details See the UnicodeSet class description for the syntax of the pattern language.
 106  *
 107  * @since_tizen 2.3.1
 108  * @param[in] pattern A string specifying what characters are in the set
 109  * @param[in] pattern_length The length of the pattern, >= 0, or -1 if NULL-terminated
 110  * @param[in] options Bitmask for options to apply to the pattern.
 111  * Valid options are #I18N_USET_IGNORE_SPACE and #I18N_USET_CASE_INSENSITIVE.
 112  * @param[out] set A pointer to the newly created #i18n_uset_h object.  The caller must call i18n_uset_destroy() on
 113  * it when done.
 114  *
 115  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 116  * @retval #I18N_ERROR_NONE Successful
 117  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 118  * @see i18n_uset_destroy()
 119  */
 120 int i18n_uset_create_pattern_options (const i18n_uchar *pattern, int32_t pattern_length, uint32_t options, i18n_uset_h *set);
 121
 122 /**
 123  * @brief Disposes of the storage used by a #i18n_uset_h object.
 124  * @details This function should be called exactly once for objects returned by i18n_uset_create().
 125  * @since_tizen 2.3.1
 126  *
 127  * @param[in] set The object to dispose of
 128  *
 129  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 130  * @retval #I18N_ERROR_NONE Successful
 131  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 132  */
 133 int i18n_uset_destroy (i18n_uset_h set);
 134
 135 /**
 136  * @brief Returns a copy of this object.
 137  * @details If this set is frozen, then the clone will be frozen as well.
 138  * Uses i18n_uset_clone_as_thawed() for a mutable clone of a frozen set.
 139  *
 140  * @since_tizen 2.3.1
 141  * @param[in] set The original set. Must not be @c NULL.
 142  * @param[out] set_clone The newly allocated copy of the set
 143  *
 144  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 145  * @retval #I18N_ERROR_NONE Successful
 146  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 147  * @see i18n_uset_clone_as_thawed()
 148  */
 149 int i18n_uset_clone (const i18n_uset_h set, i18n_uset_h *set_clone);
 150
 151 /**
 152  * @brief Determines whether the set has been frozen (made immutable) or not.
 153  * @details See the ICU4J Freezable interface for details.
 154  *
 155  * @remarks The specific error code can be obtained using the get_last_result() method.
 156  *          Error codes are described in Exceptions section.
 157  *
 158  * @since_tizen 2.3.1
 159  * @param[in] set The set. Must not be @c NULL.
 160  * @return true/false for whether the set has been frozen
 161  *
 162  * @exception #I18N_ERROR_NONE Successful
 163  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 164  * @see i18n_uset_freeze()
 165  * @see i18n_uset_clone_as_thawed()
 166  */
 167 i18n_ubool i18n_uset_is_frozen (const i18n_uset_h set);
 168
 169 /**
 170  * @brief Freezes the set (make it immutable).
 171  * @details Once frozen, it cannot be unfrozen and is therefore thread-safe
 172  * until it is deleted.
 173  * See the ICU4J Freezable interface for details.
 174  * Freezing the set may also make some operations faster, for example
 175  * i18n_uset_contains() and i18n_uset_span().
 176  * A frozen set will not be modified. (It remains frozen.)
 177  *
 178  * @since_tizen 2.3.1
 179  * @param[in] set The set. Must not be @c NULL.
 180  * @return the same set, now frozen
 181  *
 182  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 183  * @retval #I18N_ERROR_NONE Successful
 184  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 185  * @see i18n_uset_is_frozen()
 186  * @see i18n_uset_clone_as_thawed()
 187  */
 188 int i18n_uset_freeze (i18n_uset_h set);
 189
 190 /**
 191  * @brief Clones the set and make the clone mutable.
 192  * @details See the ICU4J Freezable interface for details.
 193  * @since_tizen 2.3.1
 194  *
 195  * @param[in] set The set. Must not be @c NULL.
 196  * @param[out] set_copy The mutable clone
 197  *
 198  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 199  * @retval #I18N_ERROR_NONE Successful
 200  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 201  * @see i18n_uset_freeze()
 202  * @see i18n_uset_is_frozen()
 203  * @see i18n_uset_clone()
 204  */
 205 int i18n_uset_clone_as_thawed (const i18n_uset_h set, i18n_uset_h *set_copy);
 206
 207 /**
 208  * @brief Causes the #i18n_uset_h object to represent the range <code>start - end</code>.
 209  * @details If <code>start > end</code> then this #i18n_uset_h is set to an empty range.
 210  * A frozen set will not be modified.
 211  *
 212  * @since_tizen 2.3.1
 213  * @param[in] set The object to set to the given range. Must not be @c NULL.
 214  * @param[in] start First character in the set, inclusive
 215  * @param[in] end Last character in the set, inclusive
 216  *
 217  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 218  * @retval #I18N_ERROR_NONE Successful
 219  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 220  */
 221 int i18n_uset_set (i18n_uset_h set, i18n_uchar32 start, i18n_uchar32 end);
 222
 223 /**
 224  * @brief Modifies the set to represent the set specified by the given
 225  * pattern.
 226  * @details See the UnicodeSet class description for the syntax of
 227  * the pattern language. See also the User Guide chapter about UnicodeSet.
 228  * <em>Empties the set passed before applying the pattern.</em>
 229  * A frozen set will not be modified.
 230  *
 231  * @remarks The specific error code can be obtained using the get_last_result() method.
 232  *          Error codes are described in Exceptions section and in #i18n_error_code_e description.
 233  *
 234  * @since_tizen 2.3.1
 235  * @param[in] set            The set to which the pattern is to be applied. Must not be @c NULL.
 236  * @param[in] pattern        A pointer to #i18n_uchar string specifying what characters are in the set.
 237  *                           The character at pattern[0] must be a '['.
 238  * @param[in] pattern_length The length of the #i18n_uchar string, >= 0, or -1 if NULL terminated.
 239  * @param[in] options        A bitmask for options to apply to the pattern.
 240  *                           Valid options are #I18N_USET_IGNORE_SPACE and #I18N_USET_CASE_INSENSITIVE.
 241  * @return                   Upon successful parse, the value is either
 242  *                           the index of the character after the closing ']'
 243  *                           of the parsed pattern.
 244  *                           If the status code indicates failure, then the return value
 245  *                           is the index of the error in the source.
 246  *                           If @a set is NULL, 0 is returned.
 247  *
 248  * @exception #I18N_ERROR_NONE Successful
 249  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 250  */
 251 int32_t i18n_uset_apply_pattern (i18n_uset_h set, const i18n_uchar *pattern, int32_t pattern_length, uint32_t options);
 252
 253 /**
 254  * @brief Modifies the set to contain those code points which have the given value
 255  *      for the given binary or enumerated property, as returned by
 256  *      i18n_uchar_get_int_property_value().
 257  * @details Prior contents of this set are lost.
 258  *      A frozen set will not be modified.
 259  *
 260  * @since_tizen 2.3.1
 261  * @param[in] set The object to contain the code points defined by the property. Must not be @c NULL.
 262  * @param[in] prop A property in the range #I18N_UCHAR_INT_START..#I18N_UCHAR_INT_LIMIT-1
 263  *      or #I18N_UCHAR_MASK_START..#I18N_UCHAR_MASK_LIMIT-1.
 264  * @param[in] value A value in the range i18n_uchar_get_int_property_min_value(prop)..
 265  *      i18n_uchar_get_int_property_max_value(prop), with one exception. If prop is
 266  *      #I18N_UCHAR_GENERAL_CATEGORY_MASK, then value should not be a #i18n_uchar_category_e, but
 267  *      rather a mask value produced by I18N_U_GET_GC_MASK(). This allows grouped
 268  *      categories such as [:L:] to be represented.
 269  *
 270  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 271  * @retval #I18N_ERROR_NONE Successful
 272  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 273  */
 274 int i18n_uset_apply_int_property_value (i18n_uset_h set, i18n_uchar_uproperty_e prop, int32_t value);
 275
 276 /**
 277  * @brief Modifies the set to contain those code points which have the
 278  *      given value for the given property.
 279  * @details Prior contents of this set are lost. A frozen set will not be modified.
 280  * @since_tizen 2.3.1
 281  *
 282  * @param[in] set The object to contain the code points defined by the given
 283  *      property and value alias. Must not be @c NULL.
 284  * @param[in] prop A string specifying a property alias, either short or long.
 285  *      The name is matched loosely. See PropertyAliases.txt for names and a
 286  *      description of loose matching. If the value string is empty, then this
 287  *      string is interpreted as either a General_Category value alias, a Script
 288  *      value alias, a binary property alias, or a special ID. Special IDs are
 289  *      matched loosely and correspond to the following sets:
 290  *
 291  * "ANY" = [\\u0000-\\U0010FFFF],
 292  * "ASCII" = [\\u0000-\\u007F],
 293  * "Assigned" = [:^Cn:].
 294  *
 295  * @param[in] prop_length The length of the @a prop, >= 0, or @c -1 if @c NULL.
 296  * @param[in] value A string specifying a value alias, either short or long.
 297  *      The name is matched loosely. See PropertyValueAliases.txt for names
 298  *      and a description of loose matching. In addition to aliases listed,
 299  *      numeric values and canonical combining classes may be expressed
 300  *      numerically, e.g., ("nv", "0.5") or ("ccc", "220"). The value string
 301  *      may also be empty.
 302  * @param[in] value_length The length of the value, >= 0, or -1 if NULL.
 303  *
 304  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 305  * @retval #I18N_ERROR_NONE Successful
 306  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 307  */
 308 int i18n_uset_apply_property_alias (i18n_uset_h set, const i18n_uchar *prop, int32_t prop_length, const i18n_uchar *value, int32_t value_length);
 309
 310 /**
 311  * @brief Return true if the given position, in the given pattern, appears
 312  *      to be the start of a UnicodeSet pattern.
 313  * @since_tizen 2.3.1
 314  *
 315  * @remarks The specific error code can be obtained using the get_last_result() method.
 316  *          Error codes are described in Exceptions section.
 317  *
 318  * @param[in] pattern A string specifying the pattern.
 319  * @param[in] pattern_length The length of the pattern, >= 0, or @c -1 if @c NULL.
 320  * @param[in] pos The given position, >= 0.
 321  *
 322  * @return @c true if the given position, in the given pattern, appears to be the start of a UnicodeSet pattern.
 323  *
 324  * @exception #I18N_ERROR_NONE Successful
 325  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 326  */
 327 i18n_ubool i18n_uset_resembles_pattern (const i18n_uchar *pattern, int32_t pattern_length, int32_t pos);
 328
 329 /**
 330  * @brief Returns a string representation of the given @a set.
 331  * @details If the result of calling this function is passed to an i18n_uset_pattern_create(),
 332  *          it will produce another set that is equal to this one.
 333  * @remarks The specific error code can be obtained using the get_last_result() method.
 334  *          Error codes are described in Exceptions section and in #i18n_error_code_e description.
 335  * @since_tizen 2.3.1
 336  *
 337  * @param[in] set                   The set. Must not be @c NULL.
 338  * @param[in,out] result            The string to receive the rules, may be @c NULL.
 339  * @param[in] result_capacity       The capacity of @a result, >= 0, may be @c 0 if result is @c NULL.
 340  * @param[in] escape_unprintable    If true then convert unprintable character to their hex escape representations,
 341  *                                  \\uxxxx or \\Uxxxxxxxx. Unprintable characters are those other than U+000A, U+0020..U+007E.
 342  *
 343  * @return Length of string, >= 0, possibly larger than @a result_capacity. If @a set is NULL, 0 is returned.
 344  *
 345  * @exception #I18N_ERROR_NONE Successful
 346  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 347  *
 348  * @see i18n_uset_pattern_create()
 349  */
 350 int32_t i18n_uset_to_pattern (const i18n_uset_h set, i18n_uchar *result, int32_t result_capacity, i18n_ubool escape_unprintable);
 351
 352 /**
 353  * @brief Adds the given character to the given #i18n_uset_h.
 354  * @details After this call, i18n_uset_contains(set, character) will return true.
 355  *          A frozen set will not be modified.
 356  * @since_tizen 2.3.1
 357  *
 358  * @param[in] set           The object to which to add the @a character. Must not be @c NULL.
 359  * @param[in] character     The character to add.
 360  *
 361  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 362  * @retval #I18N_ERROR_NONE Successful
 363  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 364  *
 365  * @see i18n_uset_contains()
 366  */
 367 int i18n_uset_add (i18n_uset_h set, i18n_uchar32 character);
 368
 369
 370 /**
 371  * @brief Adds all of the elements in the specified set to this set if
 372  *      they are not already present.
 373  * @details This operation effectively modifies this set so that its value is the <i>union</i> of the two
 374  *      sets. The behavior of this operation is unspecified if the specified
 375  *      collection is modified while the operation is in progress.
 376  *      A frozen set will not be modified.
 377  *
 378  * @since_tizen 2.3.1
 379  * @param[in] set The object to which to add the set. Must not be @c NULL.
 380  * @param[in] additional_set The source set whose elements are to be added to this set.
 381  *
 382  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 383  * @retval #I18N_ERROR_NONE Successful
 384  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 385  */
 386 int i18n_uset_add_all (i18n_uset_h set, const i18n_uset_h additional_set);
 387
 388 /**
 389  * @brief Adds the given range of characters to the given #i18n_uset_h. After this call,
 390  * i18n_uset_contains(set, start, end) will return true.
 391  * A frozen set will not be modified.
 392  *
 393  * @since_tizen 2.3.1
 394  * @param[in] set The object to which to add the character. Must not be @c NULL.
 395  * @param[in] start The first character of the range to add, inclusive
 396  * @param[in] end The last character of the range to add, inclusive
 397  *
 398  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 399  * @retval #I18N_ERROR_NONE Successful
 400  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 401  * @see i18n_uset_contains()
 402  */
 403 int i18n_uset_add_range (i18n_uset_h set, i18n_uchar32 start, i18n_uchar32 end);
 404
 405 /**
 406  * @brief Adds the given string to the given #i18n_uset_h.
 407  * @details After this call, i18n_uset_contains_string(set, str, str_len) will return true.
 408  * A frozen set will not be modified.
 409  *
 410  * @since_tizen 2.3.1
 411  * @param[in] set The object to which to add the character. Must not be @c NULL.
 412  * @param[in] str The string to add.
 413  * @param[in] str_len The length of the string, >= 0, or -1 if NULL terminated.
 414  *
 415  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 416  * @retval #I18N_ERROR_NONE Successful
 417  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 418  * @see i18n_uset_contains_string()
 419  */
 420 int i18n_uset_add_string (i18n_uset_h set, const i18n_uchar *str, int32_t str_len);
 421
 422 /**
 423  * @brief Adds each of the characters in this string to the set. Thus "ch" => {"c", "h"}
 424  * @details If this set already any particular character, it has no effect on that character.
 425  * A frozen set will not be modified.
 426  *
 427  * @since_tizen 2.3.1
 428  * @param[in] set The object to which to add the character. Must not be @c NULL.
 429  * @param[in] str The source string.
 430  * @param[in] str_len The length of the string, >= 0, or -1 if NULL terminated.
 431  *
 432  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 433  * @retval #I18N_ERROR_NONE Successful
 434  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 435  */
 436 int i18n_uset_add_all_code_points (i18n_uset_h set, const i18n_uchar *str, int32_t str_len);
 437
 438 /**
 439  * @brief Removes the given @a character from the given #i18n_uset_h.
 440  * @details After this call, i18n_uset_contains(set, character) will return @c false.
 441  *          A frozen set will not be modified.
 442  * @since_tizen 2.3.1
 443  *
 444  * @param[in] set           the object from which to remove the @a character. Must not be @c NULL.
 445  * @param[in] character     the character to remove
 446  *
 447  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 448  * @retval #I18N_ERROR_NONE Successful
 449  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 450  *
 451  * @see i18n_uset_contains()
 452  */
 453 int i18n_uset_remove (i18n_uset_h set, i18n_uchar32 character);
 454
 455 /**
 456  * @brief Removes the given range of characters from the given #i18n_uset_h.
 457  * @details After this call, i18n_uset_contains(set, start, end) will return false.
 458  * A frozen set will not be modified.
 459  *
 460  * @since_tizen 2.3.1
 461  * @param[in] set The object to which to add the character. Must not be @c NULL.
 462  * @param[in] start The first character of the range to remove, inclusive
 463  * @param[in] end The last character of the range to remove, inclusive
 464  *
 465  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 466  * @retval #I18N_ERROR_NONE Successful
 467  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 468  * @see i18n_uset_contains()
 469  */
 470 int i18n_uset_remove_range (i18n_uset_h set, i18n_uchar32 start, i18n_uchar32 end);
 471
 472 /**
 473  * @brief Removes the given string to the given #i18n_uset_h.
 474  * @details After this call, i18n_uset_contains_string(set, str, str_len) will return false.
 475  * A frozen set will not be modified.
 476  *
 477  * @since_tizen 2.3.1
 478  * @param[in] set The object to which to add the character. Must not be @c NULL.
 479  * @param[in] str The string to remove.
 480  * @param[in] str_len The length of the string, >= 0, or -1 if NULL terminated.
 481  *
 482  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 483  * @retval #I18N_ERROR_NONE Successful
 484  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 485  * @see i18n_uset_contains_string()
 486  */
 487 int i18n_uset_remove_string (i18n_uset_h set, const i18n_uchar *str, int32_t str_len);
 488
 489 /**
 490  * @brief Removes from this set all of its elements that are contained in the specified set.
 491  * @details This operation effectively modifies this set so that its value is the <i>asymmetric set difference</i> of
 492  * the two sets.
 493  * A frozen set will not be modified.
 494  *
 495  * @since_tizen 2.3.1
 496  * @param[in] set The object from which the elements are to be removed. Must not be @c NULL.
 497  * @param[in] remove_set The object that defines which elements will be
 498  * removed from this set. Must not be @c NULL.
 499  *
 500  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 501  * @retval #I18N_ERROR_NONE Successful
 502  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 503  */
 504 int i18n_uset_remove_all (i18n_uset_h set, const i18n_uset_h remove_set);
 505
 506 /**
 507  * @brief Retains only the elements in this set that are contained in the specified range.
 508  * @details If <code>start > end</code> then an empty range is  retained, leaving the set empty.  This is equivalent to
 509  * a boolean logic AND, or a set INTERSECTION.
 510  * A frozen set will not be modified.
 511  *
 512  * @since_tizen 2.3.1
 513  * @param[in] set The object for which to retain only the specified range. Must not be @c NULL.
 514  * @param[in] start First character, inclusive, of range to be retained
 515  * to this set.
 516  * @param[in] end Last character, inclusive, of range to be retained
 517  * to this set.
 518  *
 519  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 520  * @retval #I18N_ERROR_NONE Successful
 521  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 522  */
 523 int i18n_uset_retain (i18n_uset_h set, i18n_uchar32 start, i18n_uchar32 end);
 524
 525 /**
 526  * @brief Retains only the elements in this set that are contained in the
 527  * specified set.
 528  * @details In other words, removes from this set all of
 529  * its elements that are not contained in the specified set.  This
 530  * operation effectively modifies this set so that its value is
 531  * the <i>intersection</i> of the two sets.
 532  * A frozen set will not be modified.
 533  *
 534  * @since_tizen 2.3.1
 535  * @param[in] set The object on which to perform the retain. Must not be @c NULL.
 536  * @param[in] retain Set that defines which elements this set will retain. Must not be @c NULL.
 537  *
 538  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 539  * @retval #I18N_ERROR_NONE Successful
 540  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 541  */
 542 int i18n_uset_retain_all (i18n_uset_h set, const i18n_uset_h retain);
 543
 544 /**
 545  * @brief Reallocates this objects internal structures to take up the least
 546  * possible space, without changing this object's value.
 547  *
 548  * @details A frozen set will not be modified.
 549  * @since_tizen 2.3.1
 550  * @param[in] set The object on which to perfrom the compact. Must not be @c NULL.
 551  *
 552  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 553  * @retval #I18N_ERROR_NONE Successful
 554  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 555  */
 556 int i18n_uset_compact (i18n_uset_h set);
 557
 558 /**
 559  * @brief Inverts this set.  This operation modifies this set so that
 560  * its value is its complement.
 561  * @details This operation does not affect
 562  * the multicharacter strings, if any.
 563  * A frozen set will not be modified.
 564  *
 565  * @since_tizen 2.3.1
 566  * @param[in] set The set. Must not be @c NULL.
 567  *
 568  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 569  * @retval #I18N_ERROR_NONE Successful
 570  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 571  */
 572 int i18n_uset_complement (i18n_uset_h set);
 573
 574 /**
 575  * @brief Complements in this set all elements contained in the specified set.
 576  * @details Any character in the other set will be removed if it is
 577  * in this set, or will be added if it is not in this set.
 578  * A frozen set will not be modified.
 579  *
 580  * @since_tizen 2.3.1
 581  * @param[in] set The set with which to complement. Must not be @c NULL.
 582  * @param[in] complement Set that defines which elements will be xor'ed
 583  * from this set. Must not be @c NULL.
 584  *
 585  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 586  * @retval #I18N_ERROR_NONE Successful
 587  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 588  */
 589 int i18n_uset_complement_all (i18n_uset_h set, const i18n_uset_h complement);
 590
 591 /**
 592  * @brief Removes all of the elements from this set.
 593  * @details This set will be empty after this call returns.
 594  * A frozen set will not be modified.
 595  *
 596  * @since_tizen 2.3.1
 597  * @param[in] set The set. Must not be @c NULL.
 598  *
 599  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 600  * @retval #I18N_ERROR_NONE Successful
 601  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 602  */
 603 int i18n_uset_clear (i18n_uset_h set);
 604
 605 /**
 606  * @brief Closes this set over the given attribute.
 607  * @details For the attribute
 608  * #I18N_USET_CASE_INSENSITIVE, the result is to modify this set so that:
 609  *
 610  * 1. For each character or string 'a' in this set, all strings or
 611  * characters 'b' such that foldCase(a) == foldCase(b) are added
 612  * to this set.
 613  *
 614  * 2. For each string 'e' in the resulting set, if e !=
 615  * foldCase(e), 'e' will be removed.
 616  *
 617  * Example: [aq\\u00DF{Bc}{bC}{Fi}] => [aAqQ\\u00DF\\uFB01{ss}{bc}{fi}]
 618  *
 619  * (Here foldCase(x) refers to the operation i18n_ustring_fold_case(), and a
 620  * == b denotes that the contents are the same, not pointer
 621  * comparison.)
 622  *
 623  * A frozen set will not be modified.
 624  *
 625  * @since_tizen 2.3.1
 626  * @param[in] set The set. Must not be @c NULL.
 627  * @param[in]  attributes Bitmask for attributes to close over.
 628  * Currently only the #I18N_USET_CASE_INSENSITIVE bit is supported. Any undefined bits
 629  * are ignored.
 630  *
 631  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 632  * @retval #I18N_ERROR_NONE Successful
 633  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 634  * @see i18n_ustring_fold_case()
 635  */
 636 int i18n_uset_destroy_over (i18n_uset_h set, int32_t attributes);
 637
 638 /**
 639  * @brief Removes all strings from this set.
 640  *
 641  * @since_tizen 2.3.1
 642  * @param[in] set The set. Must not be @c NULL.
 643  *
 644  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 645  * @retval #I18N_ERROR_NONE Successful
 646  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 647  */
 648 int i18n_uset_remove_all_strings (i18n_uset_h set);
 649
 650 /**
 651  * @brief Returns true if the given #i18n_uset_h contains no characters and no
 652  * strings.
 653  *
 654  * @remarks The specific error code can be obtained using the get_last_result() method.
 655  *          Error codes are described in Exceptions section.
 656  *
 657  * @since_tizen 2.3.1
 658  * @param[in] set The set. Must not be @c NULL.
 659  * @return true if set is empty
 660  *
 661  * @exception #I18N_ERROR_NONE Successful
 662  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 663  */
 664 i18n_ubool i18n_uset_is_empty (const i18n_uset_h set);
 665
 666 /**
 667  * @brief Returns @c true if the given #i18n_uset_h contains the given @a character.
 668  * @details This function works faster with a frozen set.
 669  * @remarks The specific error code can be obtained using the get_last_result() method.
 670  *          Error codes are described in Exceptions section.
 671  * @since_tizen 2.3.1
 672  *
 673  * @param[in] set           the set. Must not be @c NULL.
 674  * @param[in] character     the codepoint to check for within the @a set
 675  *
 676  * @return @c true if @a set contains the given @a character
 677  *
 678  * @exception #I18N_ERROR_NONE Successful
 679  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 680  */
 681 i18n_ubool i18n_uset_contains (const i18n_uset_h set, i18n_uchar32 character);
 682
 683 /**
 684  * @brief Returns true if the given #i18n_uset_h contains all characters c
 685  * where start <= c && c <= end.
 686  *
 687  * @remarks The specific error code can be obtained using the get_last_result() method.
 688  *          Error codes are described in Exceptions section.
 689  *
 690  * @since_tizen 2.3.1
 691  * @param[in] set The set. Must not be @c NULL.
 692  * @param[in] start The first character of the range to test, inclusive
 693  * @param[in] end The last character of the range to test, inclusive
 694  * @return true if set contains the range
 695  *
 696  * @exception #I18N_ERROR_NONE Successful
 697  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 698  */
 699 i18n_ubool i18n_uset_contains_range (const i18n_uset_h set, i18n_uchar32 start, i18n_uchar32 end);
 700
 701 /**
 702  * @brief Returns true if the given #i18n_uset_h contains the given string.
 703  * @since_tizen 2.3.1
 704  *
 705  * @remarks The specific error code can be obtained using the get_last_result() method.
 706  *          Error codes are described in Exceptions section.
 707  *
 708  * @param[in] set The set. Must not be @c NULL.
 709  * @param[in] str The string.
 710  * @param[in] str_len The length of the string, >= 0, or -1 if NULL terminated
 711  * @return true if set contains str
 712  *
 713  * @exception #I18N_ERROR_NONE Successful
 714  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 715  */
 716 i18n_ubool i18n_uset_contains_string (const i18n_uset_h set, const i18n_uchar *str, int32_t str_len);
 717
 718 /**
 719  * @brief Returns the index of the given @a character within this @a set, where
 720  *        the @a set is ordered by ascending code point.
 721  * @details If the @a character is not in this @a set, return @c -1.
 722  *          The inverse of this function is <code>i18n_uset_char_at()</code>.
 723  * @remarks The specific error code can be obtained using the get_last_result() method.
 724  *          Error codes are described in Exceptions section.
 725  * @since_tizen 2.3.1
 726  *
 727  * @param[in] set           the set. Must not be @c NULL.
 728  * @param[in] character     the character to obtain the index for
 729  *
 730  * @return An index from 0..size()-1, or @c -1
 731  *
 732  * @exception #I18N_ERROR_NONE Successful
 733  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 734  */
 735 int32_t i18n_uset_index_of (const i18n_uset_h set, i18n_uchar32 character);
 736
 737 /**
 738  * @brief Returns the character at the given index within this set, where
 739  * the set is ordered by ascending code point.
 740  * @details If the index is out of range, return (i18n_uchar32)-1.  The inverse of this function is
 741  * <code>i18n_uset_index_of()</code>.
 742  *
 743  * @remarks The specific error code can be obtained using the get_last_result() method.
 744  *          Error codes are described in Exceptions section.
 745  *
 746  * @since_tizen 2.3.1
 747  * @param[in] set The set. Must not be @c NULL.
 748  * @param[in] char_index An index from 0..size()-1 to obtain the char for
 749  * @return The character at the given index, or (i18n_uchar32)-1.
 750  *
 751  * @exception #I18N_ERROR_NONE Successful
 752  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 753  */
 754 i18n_uchar32 i18n_uset_char_at (const i18n_uset_h set, int32_t char_index);
 755
 756 /**
 757  * @brief Returns the number of characters and strings contained in the given #i18n_uset_h.
 758  *
 759  * @remarks The specific error code can be obtained using the get_last_result() method.
 760  *          Error codes are described in Exceptions section.
 761  *
 762  * @since_tizen 2.3.1
 763  * @param[in] set The set. Must not be @c NULL.
 764  * @return A non-negative integer counting the characters and strings
 765  * contained in set.
 766  *
 767  * @exception #I18N_ERROR_NONE Successful
 768  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 769  */
 770 int32_t i18n_uset_size (const i18n_uset_h set);
 771
 772 /**
 773  * @brief Returns the number of items in this set.
 774  * @details An item is either a range of characters or a single multicharacter string.
 775  *
 776  * @remarks The specific error code can be obtained using the get_last_result() method.
 777  *          Error codes are described in Exceptions section.
 778  *
 779  * @since_tizen 2.3.1
 780  * @param[in] set The set. Must not be @c NULL.
 781  * @return A non-negative integer counting the character ranges
 782  * and/or strings contained in set.
 783  *
 784  * @exception #I18N_ERROR_NONE Successful
 785  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 786  */
 787 int32_t i18n_uset_get_item_count (const i18n_uset_h set);
 788
 789 /**
 790  * @brief Returns an item of this set.
 791  * @details An item is either a range of characters or a single multicharacter string.
 792  *
 793  * @remarks The specific error code can be obtained using the get_last_result() method.
 794  *          Error codes are described in Exceptions section.
 795  *
 796  * @since_tizen 2.3.1
 797  * @param[in] set The set. Must not be @c NULL.
 798  * @param[in] item_index A non-negative integer in the range [0; i18n_uset_get_item_count(set)-1].
 799  * @param[in] start Pointer to variable to receive first character
 800  * in range, inclusive
 801  * @param[in] end Pointer to variable to receive last character in range,
 802  * inclusive
 803  * @param[out] str Buffer to receive the string, may be NULL
 804  * @param[in] str_capacity Capacity of @a str, or 0 if str is NULL
 805  * @return The length of the string (>= 2), or 0 if the item is a
 806  * range, in which case it is the range *start..*end, or -1 if
 807  * item_index is out of range
 808  *
 809  * @exception #I18N_ERROR_NONE Successful
 810  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 811  */
 812 int32_t i18n_uset_get_item (const i18n_uset_h set, int32_t item_index, i18n_uchar32 *start, i18n_uchar32 *end, i18n_uchar *str, int32_t str_capacity);
 813
 814 /**
 815  * @brief Returns true if set1 contains all the characters and strings of set2. It answers the question, 'Is set1 a superset of set2?'
 816  *
 817  * @remarks The specific error code can be obtained using the get_last_result() method.
 818  *          Error codes are described in Exceptions section.
 819  *
 820  * @since_tizen 2.3.1
 821  * @param[in] set1 Set to be checked for containment. Must not be @c NULL.
 822  * @param[in] set2 Set to be checked for containment. Must not be @c NULL.
 823  * @return true if the test condition is met
 824  *
 825  * @exception #I18N_ERROR_NONE Successful
 826  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 827  */
 828 i18n_ubool i18n_uset_contains_all (const i18n_uset_h set1, const i18n_uset_h set2);
 829
 830 /**
 831  * @brief Returns true if this set contains all the characters of the given string.
 832  * @details This is does not check containment of grapheme
 833  * clusters, like i18n_uset_contains_string().
 834  *
 835  * @remarks The specific error code can be obtained using the get_last_result() method.
 836  *          Error codes are described in Exceptions section.
 837  *
 838  * @since_tizen 2.3.1
 839  * @param[in] set Set of characters to be checked for containment. Must not be @c NULL.
 840  * @param[in] str String containing codepoints to be checked for containment
 841  * @param[in] str_len The length of the string, >= 0, or -1 if NULL terminated.
 842  * @return true if the test condition is met.
 843  *
 844  * @exception #I18N_ERROR_NONE Successful
 845  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 846  */
 847 i18n_ubool i18n_uset_contains_all_code_points (const i18n_uset_h set, const i18n_uchar *str, int32_t str_len);
 848
 849 /**
 850  * @brief Returns true if set1 contains none of the characters and strings of set2.
 851  * @details It answers the question, 'Is set1 a disjoint set of set2?'
 852  *
 853  * @remarks The specific error code can be obtained using the get_last_result() method.
 854  *          Error codes are described in Exceptions section.
 855  *
 856  * @since_tizen 2.3.1
 857  * @param[in] set1 Set to be checked for containment. Must not be @c NULL.
 858  * @param[in] set2 Set to be checked for containment. Must not be @c NULL.
 859  * @return true if the test condition is met
 860  *
 861  * @exception #I18N_ERROR_NONE Successful
 862  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 863  */
 864 i18n_ubool i18n_uset_contains_none (const i18n_uset_h set1, const i18n_uset_h set2);
 865
 866 /**
 867  * @brief Returns true if set1 contains some of the characters and strings of set2.
 868  * @details It answers the question, 'Does set1 and set2 have an intersection?'
 869  *
 870  * @remarks The specific error code can be obtained using the get_last_result() method.
 871  *          Error codes are described in Exceptions section.
 872  *
 873  * @since_tizen 2.3.1
 874  * @param[in] set1 Set to be checked for containment. Must not be @c NULL.
 875  * @param[in] set2 Set to be checked for containment. Must not be @c NULL.
 876  * @return true if the test condition is met
 877  *
 878  * @exception #I18N_ERROR_NONE Successful
 879  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 880  */
 881 i18n_ubool i18n_uset_contains_some (const i18n_uset_h set1, const i18n_uset_h set2);
 882
 883 /**
 884  * @brief Returns the length of the initial substring of the input string which
 885  *        consists only of characters and strings that are contained in this set
 886  *        (#I18N_USET_SPAN_CONTAINED, #I18N_USET_SPAN_SIMPLE),
 887  *        or only of characters and strings that are not contained
 888  *        in this set (#I18N_USET_SPAN_NOT_CONTAINED).
 889  * @details See #i18n_uset_span_condition_e for details.
 890  *          Similar to the strspn() C library function.
 891  *          Unpaired surrogates are treated according to contains() of their surrogate code points.
 892  *          This function works faster with a frozen set and with a non-negative string length argument.
 893  * @remarks The specific error code can be obtained using the get_last_result() method.
 894  *          Error codes are described in Exceptions section.
 895  * @since_tizen 2.3.1
 896  *
 897  * @param[in] set               the set. Must not be @c NULL.
 898  * @param[in] str               start of the input string.
 899  * @param[in] length            length of the @a string; >= 0, can be @c -1 for NULL-terminated
 900  * @param[in] span_condition    specifies the containment condition
 901  *
 902  * @return The length of the initial substring according to the @a span_condition;
 903  *         @c 0 if the start of the string does not fit the @a span_condition
 904  *
 905  * @exception #I18N_ERROR_NONE Successful
 906  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 907  *
 908  * @see #i18n_uset_span_condition_e
 909  */
 910 int32_t i18n_uset_span (const i18n_uset_h set, const i18n_uchar *str, int32_t length, i18n_uset_span_condition_e span_condition);
 911
 912 /**
 913  * @brief Returns the start of the trailing substring of the input string which
 914  *        consists only of characters and strings that are contained in this set
 915  *        (#I18N_USET_SPAN_CONTAINED, #I18N_USET_SPAN_SIMPLE),
 916  *        or only of characters and strings that are not contained
 917  *        in this set (#I18N_USET_SPAN_NOT_CONTAINED).
 918  * @details See #i18n_uset_span_condition_e for details.
 919  *          Unpaired surrogates are treated according to contains() of their surrogate code points.
 920  *          This function works faster with a frozen set and with a non-negative string length argument.
 921  * @remarks The specific error code can be obtained using the get_last_result() method.
 922  *          Error codes are described in Exceptions section.
 923  * @since_tizen 2.3.1
 924  *
 925  * @param[in] set               the set. Must not be @c NULL.
 926  * @param[in] str               start of the input string
 927  * @param[in] length            length of the @ string; >= 0, can be @c -1 for NULL-terminated
 928  * @param[in] span_condition    specifies the containment condition
 929  *
 930  * @return the start of the trailing substring according to the @a span_condition;
 931  *         the string length if the end of the string does not fit the @a span_condition
 932  *
 933  * @exception #I18N_ERROR_NONE Successful
 934  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 935  *
 936  * @see #i18n_uset_span_condition_e
 937  */
 938 int32_t i18n_uset_span_back (const i18n_uset_h set, const i18n_uchar *str, int32_t length, i18n_uset_span_condition_e span_condition);
 939
 940 /**
 941  * @brief Returns the length of the initial substring of the input string which
 942  *        consists only of characters and strings that are contained in this set
 943  *        (#I18N_USET_SPAN_CONTAINED, #I18N_USET_SPAN_SIMPLE),
 944  *        or only of characters and strings that are not contained
 945  *        in this set (#I18N_USET_SPAN_NOT_CONTAINED).
 946  * @details See #i18n_uset_span_condition_e for details.
 947  *          Similar to the strspn() C library function.
 948  *          Malformed byte sequences are treated according to contains(0xfffd).
 949  *          This function works faster with a frozen set and with a non-negative string length argument.
 950  * @remarks The specific error code can be obtained using the get_last_result() method.
 951  *          Error codes are described in Exceptions section.
 952  * @since_tizen 2.3.1
 953  *
 954  * @param[in] set               the set. Must not be @c NULL.
 955  * @param[in] str               start of the string (UTF-8)
 956  * @param[in] length            length of the string; >= 0, can be @c -1 for NULL-terminated
 957  * @param[in] span_condition    specifies the containment condition
 958  *
 959  * @return the length of the initial substring according to the @a span_condition;
 960  *         @c 0 if the start of the string does not fit the @a span_condition
 961  *
 962  * @exception #I18N_ERROR_NONE Successful
 963  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 964  *
 965  * @see #i18n_uset_span_condition_e
 966  */
 967 int32_t i18n_uset_span_utf8 (const i18n_uset_h set, const char *str, int32_t length, i18n_uset_span_condition_e span_condition);
 968
 969 /**
 970  * @brief Returns the start of the trailing substring of the input string which
 971  *        consists only of characters and strings that are contained in this set
 972  *        (#I18N_USET_SPAN_CONTAINED, #I18N_USET_SPAN_SIMPLE),
 973  *        or only of characters and strings that are not contained
 974  *        in this set (#I18N_USET_SPAN_NOT_CONTAINED).
 975  * @details See #i18n_uset_span_condition_e for details.
 976  *          Malformed byte sequences are treated according to contains(0xfffd).
 977  *          This function works faster with a frozen set and with a non-negative string length argument.
 978  * @remarks The specific error code can be obtained using the get_last_result() method.
 979  *          Error codes are described in Exceptions section.
 980  * @since_tizen 2.3.1
 981  *
 982  * @param[in] set               the set. Must not be @c NULL.
 983  * @param[in] str               start of the string (UTF-8)
 984  * @param[in] length            length of the string; >= 0, can be @c -1 for NULL-terminated
 985  * @param[in] span_condition    specifies the containment condition
 986  *
 987  * @return the start of the trailing substring according to the @a span_condition;
 988  *         the string length if the end of the string does not fit the @a span_condition
 989  *
 990  * @exception #I18N_ERROR_NONE Successful
 991  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 992  *
 993  * @see #i18n_uset_span_condition_e
 994  */
 995 int32_t i18n_uset_span_back_utf8 (const i18n_uset_h set, const char *str, int32_t length, i18n_uset_span_condition_e span_condition);
 996
 997 /**
 998  * @brief Returns true if set1 contains all of the characters and strings
 999  * of set2, and vice versa. It answers the question, 'Is set1 equal to set2?'
1000  *
1001  * @remarks The specific error code can be obtained using the get_last_result() method.
1002  *          Error codes are described in Exceptions section.
1003  *
1004  * @since_tizen 2.3.1
1005  * @param[in] set1 Set to be checked for containment. Must not be @c NULL.
1006  * @param[in] set2 Set to be checked for containment. Must not be @c NULL.
1007  * @return true if the test condition is met
1008  *
1009  * @exception #I18N_ERROR_NONE Successful
1010  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1011  */
1012 i18n_ubool i18n_uset_equals (const i18n_uset_h set1, const i18n_uset_h set2);
1013
1014 /*********************************************************************
1015  * Serialized set API
1016  *********************************************************************/
1017
1018 /**
1019  * @brief Serializes this @a set into an array of 16-bit integers.
1020  * @details Serialization (currently) only records the characters in the set;
1021  *          multicharacter strings are ignored.
1022  *
1023  *          The array has following format (each line is one 16-bit integer):
1024  *
1025  *          length     = (n+2*m) | (m!=0?0x8000:0)
1026  *          bmpLength  = n;
1027  *          present if m!=0
1028  *          bmp[0]
1029  *          bmp[1]
1030  *          ...
1031  *          bmp[n-1]
1032  *          supp-high[0]
1033  *          supp-low[0]
1034  *          supp-high[1]
1035  *          supp-low[1]
1036  *          ...
1037  *          supp-high[m-1]
1038  *          supp-low[m-1]
1039  *
1040  *          The array starts with a header. After the header are n bmp
1041  *          code points, then m supplementary code points. Either n or m
1042  *          or both may be zero. n+2*m is always <= 0x7FFF.
1043  *
1044  *          If there are no supplementary characters (if m==0) then the
1045  *          header is one 16-bit integer, 'length', with value n.
1046  *
1047  *          If there are supplementary characters (if m!=0) then the header
1048  *          is two 16-bit integers. The first, 'length', has value
1049  *          (n+2*m)|0x8000.  The second, 'bmpLength', has value n.
1050  *
1051  *          After the header the code points are stored in ascending order.
1052  *          Supplementary code points are stored as most significant 16
1053  *          bits followed by least significant 16 bits.
1054  * @remarks The specific error code can be obtained using the get_last_result() method.
1055  *          Error codes are described in Exceptions section and in #i18n_error_code_e description.
1056  * @since_tizen 2.3.1
1057  *
1058  * @param[in] set               the set. Must not be @c NULL.
1059  * @param[out] dest             pointer to buffer of @a dest_capacity 16-bit integers
1060  *                              May be NULL only if @a dest_capacity is zero.
1061  * @param[in] dest_capacity     size of @a dest, or zero
1062  *                              Must not be negative.
1063  *
1064  * @return the total length of the serialized format, including
1065  *         the header, that is, <code>n+2*m+(m != 0 ? 2 : 1)</code>,
1066  *         or @c 0 on error other than #I18N_ERROR_BUFFER_OVERFLOW.
1067  *
1068  * @exception #I18N_ERROR_NONE Successful
1069  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1070  * @exception #I18N_ERROR_INDEX_OUTOFBOUNDS If <code>n+2*m > 0x7FFF</code>
1071  * @exception #I18N_ERROR_BUFFER_OVERFLOW If <code>n+2*m+(m != 0 ? 2 : 1) > dest_capacity</code>.
1072  */
1073 int32_t i18n_uset_serialize (const i18n_uset_h set, uint16_t *dest, int32_t dest_capacity);
1074
1075 /**
1076  * @brief Given a serialized array, fill in the given serialized set object.
1077  * @remarks The specific error code can be obtained using the get_last_result() method.
1078  *          Error codes are described in Exceptions section.
1079  * @since_tizen 2.3.1
1080  *
1081  * @param[in] src           pointer to start of array. Must not be @c NULL.
1082  * @param[in] src_length    length of @a src array, >= 0.
1083  * @param[out] fill_set     the serialized set to be filled
1084  *
1085  * @return @c true if the given array is valid, otherwise @c false
1086  *
1087  * @exception #I18N_ERROR_NONE Successful
1088  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1089  *
1090  * @see #i18n_userialized_set_s
1091  */
1092 i18n_ubool i18n_uset_get_serialized_set (const uint16_t *src, int32_t src_length, i18n_userialized_set_s* fill_set);
1093
1094 /**
1095  * @brief Sets the #i18n_userialized_set_s to contain the given @a character (and nothing else).
1096  * @since_tizen 2.3.1
1097  *
1098  * @param[in] character     the code point to set
1099  * @param[out] fill_set     the serialized set to be filled
1100  *
1101  * @return Error code.
1102  * @retval #I18N_ERROR_NONE Successful
1103  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1104  *
1105  * @see #i18n_userialized_set_s
1106  */
1107 int i18n_uset_set_serialized_to_one (i18n_uchar32 character, i18n_userialized_set_s* fill_set);
1108
1109 /**
1110  * @brief Returns @c true if the given #i18n_userialized_set_s contains the given @a character.
1111  * @remarks The specific error code can be obtained using the get_last_result() method.
1112  *          Error codes are described in Exceptions section.
1113  * @since_tizen 2.3.1
1114  *
1115  * @param[in] set           the serialized set. Must not be @c NULL.
1116  * @param[in] character     the code point to check for within the @a set
1117  *
1118  * @return @c true if @a set contains @a character
1119  *
1120  * @exception #I18N_ERROR_NONE Successful
1121  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1122  * @see #i18n_userialized_set_s
1123  */
1124 i18n_ubool i18n_uset_serialized_contains (const i18n_userialized_set_s* set, i18n_uchar32 character);
1125
1126 /**
1127  * @brief Returns the number of disjoint ranges of characters contained in
1128  * the given serialized set.
1129  * @details Ignores any strings contained in the set.
1130  *
1131  * @remarks The specific error code can be obtained using the get_last_result() method.
1132  *          Error codes are described in Exceptions section.
1133  *
1134  * @since_tizen 2.3.1
1135  * @param[in] set The serialized set. Must not be @c NULL.
1136  * @return A non-negative integer counting the character ranges contained in set
1137  *
1138  * @exception #I18N_ERROR_NONE Successful
1139  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1140  * @see #i18n_userialized_set_s
1141  */
1142 int32_t i18n_uset_get_serialized_range_count (const i18n_userialized_set_s* set);
1143
1144 /**
1145  * @brief Returns a range of characters contained in the given serialized set.
1146  *
1147  * @remarks The specific error code can be obtained using the get_last_result() method.
1148  *          Error codes are described in Exceptions section.
1149  *
1150  * @since_tizen 2.3.1
1151  * @param[in] set The serialized set. Must not be @c NULL.
1152  * @param[in] range_index A non-negative integer in the range 0..
1153  * i18n_uset_get_serialized_range_count(set)-1
1154  * @param[out] p_start Pointer to variable to receive first character
1155  * in range, inclusive
1156  * @param[out] p_end Pointer to variable to receive last character in range,
1157  * inclusive
1158  * @return true if range_index is valid, otherwise false
1159  *
1160  * @exception #I18N_ERROR_NONE Successful
1161  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1162  * @see #i18n_userialized_set_s
1163  */
1164 i18n_ubool i18n_uset_get_serialized_range (const i18n_userialized_set_s* set, int32_t range_index, i18n_uchar32 *p_start, i18n_uchar32 *p_end);
1165
1166 /**
1167  * @}
1168  * @}
1169  */
1170
1171 #ifdef __cplusplus
1172 }
1173 #endif
1174
1175 #endif