src/include/wearable/utils_i18n_unumber.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_UNUMBER_H__
  18 #define __UTILS_I18N_UNUMBER_H__
  19
  20 #include <utils_i18n_types.h>
  21
  22 /**
  23  * @file utils_i18n_unumber.h
  24  * @version 0.1
  25  * @brief utils_i18n_unumber
  26  */
  27
  28 /**
  29  * @ingroup CAPI_BASE_UTILS_I18N_MODULE
  30  * @defgroup CAPI_BASE_UTILS_I18N_UNUMBER_MODULE Unumber
  31  * @brief The Unumber module helps you format and parse numbers for any locale.
  32  *
  33  * @section CAPI_BASE_UTILS_I18N_UNUMBER_MODULE_HEADER Required Header
  34  *  \#include <utils_i18n.h>
  35  *
  36  * @section CAPI_BASE_UTILS_I18N_UNUMBER_MODULE_OVERVIEW Overview
  37  * @details The Unumber module helps you format and parse numbers for any locale.
  38  * Your code can be completely independent of the locale conventions for decimal
  39  * points, thousands-separators, or even the particular decimal digits used,
  40  * or whether the number format is even decimal. There are different number format
  41  * styles like decimal, currency, percent and spellout.
  42  *
  43  * @section CAPI_BASE_UTILS_I18N_UNUMBER_MODULE_SAMPLE_CODE_1 Sample Code 1
  44  * @brief Gets a currency symbol according to a given locale.
  45  * @code
  46     int buf_len;
  47     i18n_uchar u_buffer[64];
  48     char a_buffer[64];
  49     i18n_unumber_format_h num_format;
  50
  51     // creates and returns a new unumber_format
  52     i18n_unumber_create(I18N_UNUMBER_CURRENCY, NULL, -1, "en_US", NULL, &num_format);
  53
  54     // gets a symbol associated with i18n_unumber_format
  55     i18n_unumber_get_symbol(num_format, I18N_UNUMBER_CURRENCY_SYMBOL, u_buffer, 64, &buf_len);
  56
  57     i18n_ustring_copy_au(a_buffer, u_buffer);
  58     // en_US currency symbol: $
  59     dlog_print(DLOG_INFO, LOG_TAG, "en_US currency symbol: %s \n", a_buffer);
  60
  61     // destroys i18n_unumber_format
  62     i18n_unumber_destroy(num_format);
  63  * @endcode
  64  */
  65
  66 /**
  67  * @addtogroup CAPI_BASE_UTILS_I18N_UNUMBER_MODULE
  68  * @{
  69  */
  70
  71 #ifdef __cplusplus
  72 extern "C" {
  73 #endif
  74
  75 /**
  76  * @brief Creates and returns a new unumber_format_h for formatting and parsing numbers.
  77  * @details A unumber_format_style_e may be used to format numbers by calling {@link i18n_unumber_create()}.
  78  * The caller must call {@link #i18n_unumber_destroy() } when done to release resources used by this object.
  79  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  80  * @remarks Must release @a num_format using i18n_unumber_destroy().
  81  *
  82  * @param[in] style The type of number format to create: one of
  83  * #I18N_UNUMBER_DECIMAL,
  84  * #I18N_UNUMBER_CURRENCY,
  85  * #I18N_UNUMBER_PERCENT,
  86  * #I18N_UNUMBER_SCIENTIFIC,
  87  * #I18N_UNUMBER_SPELLOUT,
  88  * #I18N_UNUMBER_ORDINAL,
  89  * #I18N_UNUMBER_DURATION,
  90  * #I18N_UNUMBER_NUMBERING_SYSTEM,
  91  * #I18N_UNUMBER_PATTERN_RULEBASED,
  92  * or #I18N_UNUMBER_DEFAULT \n
  93  * If #I18N_UNUMBER_PATTERN_DECIMAL or #I18N_UNUMBER_PATTERN_RULEBASED is passed then the number format is created using the given pattern, which must conform
  94  * to the syntax described in DecimalFormat or RuleBasedNumberFormat, respectively.
  95  * @param[in] pattern       A pattern specifying the format to use \n This parameter is ignored unless the style is #I18N_UNUMBER_PATTERN_DECIMAL or #I18N_UNUMBER_PATTERN_RULEBASED.
  96  * @param[in] pattern_len   The number of characters in the pattern, otherwise @c -1 if NULL-terminated\n
  97  *                          This parameter is ignored unless the style is I18N_UNUMBER_PATTERN_*.
  98  * @param[in] locale        A locale identifier to use to determine formatting
  99  *                          and parsing conventions, otherwise @c NULL to use the default locale.
 100  * @param[in] parse_err     A pointer to a #i18n_uparse_error_s structure to receive the
 101  *                          details of any parsing errors, otherwise @c NULL if no parsing error details are desired.
 102  * @param[out] num_format   A pointer to a newly created #i18n_unumber_format_h, otherwise @c NULL if an error occurs.
 103  *
 104  * @retval #I18N_ERROR_NONE Successful
 105  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 106  */
 107 int i18n_unumber_create ( i18n_unumber_format_style_e style, const i18n_uchar *pattern, int32_t pattern_len, const char *locale,
 108     i18n_uparse_error_s *parse_err, i18n_unumber_format_h *num_format );
 109
 110 /**
 111  * @brief Destroys an #i18n_unumber_format_h.
 112  * @details Once destroyed, an #i18n_unumber_format may no longer be used.
 113  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 114  *
 115  * @param[in] fmt The formatter to destroy
 116  *
 117  * @retval #I18N_ERROR_NONE Successful
 118  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 119  */
 120 int i18n_unumber_destroy ( i18n_unumber_format_h fmt );
 121
 122 /**
 123  * @brief Gets a symbol associated with an #i18n_unumber_format_h.
 124  * @details An #i18n_unumber_format_h uses symbols to represent the special locale-dependent characters in a number,
 125  * for example the percent sign. This API is not supported for rule-based formatters.
 126  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 127  *
 128  * @param[in] fmt The formatter to query.
 129  * @param[in] symbol The unumber_format_symbol_e constant for the symbol to get
 130  * @param[out] buffer The string buffer that will receive the symbol string\n
 131  * If it is @c NULL, then only the length of the symbol is returned.
 132  * @param[in] size The size of the string buffer
 133  * @param[out] len_symbol The length of the symbol\n
 134  * The buffer is not modified if <code>length &gt;= size</code>
 135  *
 136  * @retval #I18N_ERROR_NONE Successful.
 137  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 138  */
 139 int i18n_unumber_get_symbol ( const i18n_unumber_format_h fmt, i18n_unumber_format_symbol_e symbol, i18n_uchar *buffer, int32_t size, int32_t *len_symbol );
 140
 141
 142 // Newly Added APIs
 143
 144
 145 /**
 146  * @brief Creates a copy of an #i18n_unumber_format_h.
 147  * @details This function performs a deep copy.
 148  * @remarks Error codes are described in #i18n_error_code_e description.
 149  * @since_tizen 2.3.1
 150  *
 151  * @param[in] fmt   The format to copy.
 152  * @param[out] fmt_clone A pointer to clone of @a fmt.
 153  * @return The obtained error code.
 154  * @retval #I18N_ERROR_NONE Successful.
 155  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 156  */
 157 int i18n_unumber_clone (const i18n_unumber_format_h fmt, i18n_unumber_format_h *fmt_clone);
 158
 159 /**
 160 * @brief Formats an integer using a i18n_unumber_format_h.
 161 * @details The integer will be formatted according to the i18n_unumber_format_h's locale.
 162 * @since_tizen 2.3.1
 163 *
 164 * @param[in] fmt           The formatter to use.
 165 * @param[in] number        The number to format.
 166 * @param[out] result       A pointer to a buffer to receive the NULL-terminated formatted number.
 167 *                          If the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
 168 *                          then the error code is set to #I18N_WARNING_STRING_NOT_TERMINATED.
 169 *                          If the formatted number doesn't fit into result then the error code is set to #I18N_ERROR_BUFFER_OVERFLOW.
 170 * @param[in] result_length The maximum size of result.
 171 * @param[in] pos           A pointer to a i18n_ufield_position. On input, position->field is read.
 172 *                          On output, position->beginIndex and position->endIndex indicate the beginning and ending indices of field number position->field, if such a field exists.
 173 *                          This parameter may be NULL, in which case no field
 174 * @param[out] status       A pointer to an i18n_error_code_e to receive any errors
 175 *
 176 * @return The total buffer size needed; if greater than result_length, the output was truncated.
 177 */
 178 int32_t i18n_unumber_format (const i18n_unumber_format_h fmt, int32_t number, i18n_uchar *result, int32_t result_length, i18n_ufield_position_s *pos, i18n_error_code_e *status);
 179
 180 /**
 181  * @brief Formats an int64 using an #i18n_unumber_format_h.
 182  * @details The int64 will be formatted according to the #i18n_unumber_format_h's locale.
 183  * @remarks The specific error code can be obtained using the get_last_result() method.
 184  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 185  * @since_tizen 2.3.1
 186  *
 187  * @param[in] fmt               The formatter to use.
 188  * @param[in] number            The number to format.
 189  * @param[out] result           A pointer to a buffer to receive the NULL-terminated formatted number.
 190  *                              If the formatted number fits into @a result but cannot be NULL-terminated (<code>length == result_length</code>)
 191  *                              then the error code is set to #I18N_WARNING_STRING_NOT_TERMINATED.
 192  *                              If the formatted number doesn't fit into result then the error code is set to #I18N_ERROR_BUFFER_OVERFLOW.
 193  * @param[in] result_length     The maximum size of @a result.
 194  * @param[in,out] pos           An #i18n_ufield_position_h handle. On input, position->field is read.
 195  *                              On output, position->beginIndex and position->endIndex indicate the beginning and ending indices of field number position->field, if such a field exists.
 196  *                              This parameter may be NULL, in which case no field
 197  *
 198  * @return The total buffer size needed; if greater than @a result_length, the output was truncated.
 199  *
 200  * @exception #I18N_ERROR_NONE Successful
 201  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 202  * @exception #I18N_WARNING_STRING_NOT_TERMINATED If the formatted number fits into @a result but cannot be NULL-terminated (<code>length == result_length</code>)
 203  * @exception #I18N_ERROR_BUFFER_OVERFLOW If the formatted number doesn't fit into the @a result buffer
 204  */
 205 int32_t i18n_unumber_format_int64 (const i18n_unumber_format_h fmt, int64_t number, i18n_uchar *result, int32_t result_length, i18n_ufield_position_h pos);
 206
 207 /**
 208  * @brief Formats a double using an #i18n_unumber_format_h.
 209  * @details The double will be formatted according to the #i18n_unumber_format_h's locale.
 210  * @remarks The specific error code can be obtained using the get_last_result() method.
 211  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 212  * @since_tizen 2.3.1
 213  *
 214  * @param[in] fmt               The formatter to use.
 215  * @param[in] number            The number to format.
 216  * @param[out] result           A pointer to a buffer to receive the NULL-terminated formatted number.
 217  *                              If the formatted number fits into @a result but cannot be NULL-terminated (<code>length == result_length</code>)
 218  *                              then the error code is set to #I18N_WARNING_STRING_NOT_TERMINATED.
 219  *                              If the formatted number doesn't fit into result then the error code is set to #I18N_ERROR_BUFFER_OVERFLOW.
 220  * @param[in] result_length     The maximum size of @a result.
 221  * @param[in,out] pos           An #i18n_ufield_position_h handle. On input, position->field is read.
 222  *                              On output, position->beginIndex and position->endIndex indicate the beginning
 223  *                              and ending indices of field number position->field, if such a field exists.
 224  *                              This parameter may be NULL, in which case no field
 225  *
 226  * @return The total buffer size needed; if greater than @a result_length, the output was truncated.
 227  *
 228  * @exception #I18N_ERROR_NONE Successful
 229  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 230  * @exception #I18N_WARNING_STRING_NOT_TERMINATED If the formatted number fits into @a result but cannot be NULL-terminated (<code>length == result_length</code>)
 231  * @exception #I18N_ERROR_BUFFER_OVERFLOW If the formatted number doesn't fit into the @a result buffer
 232  */
 233 int32_t i18n_unumber_format_double (const i18n_unumber_format_h fmt, double number, i18n_uchar *result, int32_t result_length, i18n_ufield_position_h pos);
 234
 235 /**
 236  * @brief Formats a decimal number using an #i18n_unumber_format_h.
 237  * @details The number will be formatted according to the #i18n_unumber_format_h's locale. The syntax of the input number
 238  *      is a "numeric string" as defined in the Decimal Arithmetic Specification, available at http://speleotrove.com/decimal
 239  * @remarks The specific error code can be obtained using the get_last_result() method.
 240  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 241  * @since_tizen 2.3.1
 242  *
 243  * @param[in] fmt               The formatter to use.
 244  * @param[in] number            The number to format.
 245  * @param[in] length            The length of the input @a number, or -1 if the input is NULL-terminated.
 246  * @param[out] result           A pointer to a buffer to receive the NULL-terminated formatted number.
 247  *                              If the formatted number fits into @a result but cannot be NULL-terminated (<code>length == result_length</code>) then
 248  *                              the error code is set to #I18N_WARNING_STRING_NOT_TERMINATED.
 249  *                              If the formatted number doesn't fit into result then the error code is set to
 250  *                              #I18N_ERROR_BUFFER_OVERFLOW.
 251  * @param[in] result_length     The maximum size of @a result.
 252  * @param[in,out] pos           An #i18n_ufield_position_h handle. On input, position->field is read.
 253  *                              On output, position->beginIndex and position->endIndex indicate the beginning and ending
 254  *                              indices of field number position->field, if such a field exists.
 255  *                              This parameter may be NULL, in which case it is ignored.
 256  *
 257  * @return The total buffer size needed; if greater than @a result_length, the output was truncated.
 258  *
 259  * @exception #I18N_ERROR_NONE Successful
 260  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 261  * @exception #I18N_WARNING_STRING_NOT_TERMINATED If the formatted number fits into @a result but cannot be NULL-terminated (<code>length == result_length</code>)
 262  * @exception #I18N_ERROR_BUFFER_OVERFLOW If the formatted number doesn't fit into the @a result buffer
 263  */
 264 int32_t i18n_unumber_format_decimal (const i18n_unumber_format_h fmt, const char *number, int32_t length, i18n_uchar *result, int32_t result_length, i18n_ufield_position_h pos);
 265
 266 /**
 267  * @brief Formats a double currency amount using an #i18n_unumber_format_h.
 268  * @details The double will be formatted according to the #i18n_unumber_format_h's locale.
 269  * @remarks The specific error code can be obtained using the get_last_result() method.
 270  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 271  * @since_tizen 2.3.1
 272  *
 273  * @param[in] fmt               The formatter to use.
 274  * @param[in] number            The number to format.
 275  * @param[in] currency          The 3-letter NULL-terminated ISO 4217 currency code.
 276  * @param[out] result           A pointer to a buffer to receive the NULL-terminated formatted number.
 277  *                              If the formatted number fits into @a result but cannot be NULL-terminated (<code>length == result_length</code>)
 278  *                              then the error code is set to #I18N_WARNING_STRING_NOT_TERMINATED.
 279  *                              If the formatted number doesn't fit into result then the error code is set to
 280  *                              #I18N_ERROR_BUFFER_OVERFLOW.
 281  * @param[in] result_length     The maximum size of @a result.
 282  * @param[in,out] pos           An #i18n_ufield_position_h handle. On input, position->field is read.
 283  *                              On output, position->beginIndex and position->endIndex indicate the beginning and ending indices
 284  *                              of field number position->field, if such a field exists.
 285  *                              This parameter may be NULL, in which case it is ignored.
 286  *
 287  * @return The total buffer size needed; if greater than @a result_length, the output was truncated.
 288  *
 289  * @exception #I18N_ERROR_NONE Successful
 290  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 291  * @exception #I18N_WARNING_STRING_NOT_TERMINATED If the formatted number fits into @a result but cannot be NULL-terminated (<code>length == result_length</code>)
 292  * @exception #I18N_ERROR_BUFFER_OVERFLOW If the formatted number doesn't fit into the @a result buffer
 293  */
 294 int32_t i18n_unumber_format_double_currency (const i18n_unumber_format_h fmt, double number, i18n_uchar *currency, i18n_uchar *result, int32_t result_length, i18n_ufield_position_h pos);
 295
 296 /**
 297  * @brief Parses a string into an integer using an #i18n_unumber_format_h.
 298  * @details The string will be parsed according to the #i18n_unumber_format_h's locale.
 299  * @remarks The specific error code can be obtained using the get_last_result() method.
 300  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 301  * @since_tizen 2.3.1
 302  *
 303  * @param[in] fmt            The formatter to use.
 304  * @param[in] text           The text to parse.
 305  * @param[in] text_length    The length of @a text, or -1 if NULL-terminated.
 306  * @param[in,out] parse_pos  If not NULL, on input a pointer to an integer specifying the offset at which to begin parsing.
 307  *                           If not NULL, on output the offset at which parsing ended.
 308  *
 309  * @return The value of the parsed integer
 310  *
 311  * @exception #I18N_ERROR_NONE Successful
 312  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 313  */
 314 int32_t i18n_unumber_parse (const i18n_unumber_format_h fmt, const i18n_uchar *text, int32_t text_length, int32_t *parse_pos);
 315
 316 /**
 317  * @brief Parses a string into an int64 using an #i18n_unumber_format_h.
 318  * @details The string will be parsed according to the #i18n_unumber_format_h's locale.
 319  * @remarks The specific error code can be obtained using the get_last_result() method.
 320  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 321  * @since_tizen 2.3.1
 322  *
 323  * @param[in] fmt            The formatter to use.
 324  * @param[in] text           The text to parse.
 325  * @param[in] text_length    The length of @a text, or -1 if NULL-terminated.
 326  * @param[in,out] parse_pos  If not NULL, on input a pointer to an integer specifying the offset at which to begin parsing.
 327  *                           If not NULL, on output the offset at which parsing ended.
 328  *
 329  * @return The value of the parsed integer
 330  *
 331  * @exception #I18N_ERROR_NONE Successful
 332  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 333  */
 334 int64_t i18n_unumber_parse_int64 (const i18n_unumber_format_h fmt, const i18n_uchar *text, int32_t text_length, int32_t *parse_pos);
 335
 336 /**
 337  * @brief Parses a string into a double using an #i18n_unumber_format_h.
 338  * @details The string will be parsed according to the #i18n_unumber_format_h's locale.
 339  * @remarks The specific error code can be obtained using the get_last_result() method.
 340  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 341  * @since_tizen 2.3.1
 342  *
 343  * @param[in] fmt            The formatter to use.
 344  * @param[in] text           The text to parse.
 345  * @param[out] text_length   The length of @a text, or -1 if NULL-terminated.
 346  * @param[in,out] parse_pos  If not NULL, on input a pointer to an integer specifying the offset at which to begin parsing.
 347  *                           If not NULL, on output the offset at which parsing ended.
 348  *
 349  * @return The value of the parsed double
 350  *
 351  * @exception #I18N_ERROR_NONE Successful
 352  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 353  */
 354 double i18n_unumber_parse_double (const i18n_unumber_format_h fmt, const i18n_uchar *text, int32_t text_length, int32_t *parse_pos);
 355
 356 /**
 357  * @brief Parses a number from a string into an unformatted numeric string using an #i18n_unumber_format_h.
 358  * @details The input string will be parsed according to the #i18n_unumber_format_h's locale.
 359  *          The syntax of the output is a "numeric string" as defined in the Decimal Arithmetic Specification, available at
 360  *          http://speleotrove.com/decimal
 361  * @remarks The specific error code can be obtained using the get_last_result() method.
 362  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 363  * @since_tizen 2.3.1
 364  *
 365  * @param[in] fmt                The formatter to use.
 366  * @param[in] text               The text to parse.
 367  * @param[in] text_length        The length of @a text, or -1 if NULL-terminated.
 368  * @param[in,out] parse_pos      If not NULL, on input a pointer to an integer specifying the offset at which to begin parsing.
 369  *                               If not NULL, on output the offset at which parsing ended.
 370  * @param[out] out_buf           A (char *) buffer to receive the parsed number as a string.
 371  *                               The output string will be NULL-terminated if there is sufficient space.
 372  * @param[out] out_buf_length    The size of the output buffer. May be zero, in which case the @a out_buf pointer may be NULL,
 373  *                               and the function will return the size of the output string.
 374  *
 375  * @return The length of the output string, not including any terminating NULL.
 376  *
 377  * @exception #I18N_ERROR_NONE Successful
 378  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 379  */
 380 int32_t i18n_unumber_parse_decimal (const i18n_unumber_format_h fmt, const i18n_uchar *text, int32_t text_length, int32_t *parse_pos, char *out_buf, int32_t out_buf_length);
 381
 382 /**
 383  * @brief Parses a string into a double and a currency using an #i18n_unumber_format_h.
 384  * @details The string will be parsed according to the #i18n_unumber_format_h's locale.
 385  * @remarks The specific error code can be obtained using the get_last_result() method.
 386  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 387  * @since_tizen 2.3.1
 388  *
 389  * @param[in] fmt            The formatter to use.
 390  * @param[in] text           The text to parse.
 391  * @param[in] text_length    The length of @a text, or -1 if NULL-terminated.
 392  * @param[in,out] parse_pos  A pointer to an offset index into text at which to begin parsing. On output, @a parse_pos will
 393  *                           point after the last parsed character. This parameter may be NULL, in which case parsing begins
 394  *                           at offset 0.
 395  *                           If not NULL, on output the offset at which parsing ended.
 396  * @param[out] currency      A pointer to the buffer to receive the parsed NULL- terminated currency.
 397  *                           This buffer must have a capacity of at least 4 #i18n_uchar characters.
 398  *
 399  * @return The parsed double
 400  *
 401  * @exception #I18N_ERROR_NONE Successful
 402  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 403  */
 404 double i18n_unumber_parse_double_currency (const i18n_unumber_format_h fmt, const i18n_uchar *text, int32_t text_length, int32_t *parse_pos, i18n_uchar *currency);
 405
 406 /**
 407  * @brief Sets the pattern used by an #i18n_unumber_format_h.
 408  * @details This can only be used on a DecimalFormat, other formats return #I18N_ERROR_NOT_SUPPORTED in the status.
 409  * @remarks Error codes are described in #i18n_error_code_e description.
 410  * @since_tizen 2.3.1
 411  *
 412  * @param[in] format            The formatter to set.
 413  * @param[in] localized         true if the pattern is localized, false otherwise.
 414  * @param[in] pattern           The new pattern
 415  * @param[in] pattern_length    The length of @a pattern, or -1 if NULL-terminated.
 416  * @param[out] parse_error       A pointer to #i18n_uparse_error_s to receive information about errors occurred during parsing,
 417  *                               or NULL if no parse error information is desired.
 418  *
 419  * @return The obtained error code.
 420  * @retval #I18N_ERROR_NONE Successful.
 421  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 422  */
 423 int i18n_unumber_apply_pattern (i18n_unumber_format_h format, i18n_ubool localized, const i18n_uchar *pattern, int32_t pattern_length, i18n_uparse_error_s* parse_error);
 424
 425 /**
 426  * @brief Gets a locale for which decimal formatting patterns are available.
 427  * @details An #i18n_unumber_format_h in a locale returned by this function will perform the correct formatting and parsing for the locale.
 428  *          The results of this call are not valid for rule-based number formats.
 429  * @remarks The specific error code can be obtained using the get_last_result() method.
 430  *          Error codes are described in Exceptions section.
 431  * @since_tizen 2.3.1
 432  *
 433  * @param[in] locale_index  The index of the desired locale.
 434  *
 435  * @return A locale for which number formatting patterns are available, or 0 if none.
 436  *
 437  * @exception #I18N_ERROR_NONE Successful
 438  */
 439 const char *i18n_unumber_get_available (int32_t locale_index);
 440
 441 /**
 442  * @brief Determines how many locales have decimal formatting patterns available.
 443  * @details The results of this call are not valid for rule-based number formats.
 444  *          This function is useful for determining the loop ending condition for calls to i18n_unumber_get_available().
 445  * @remarks The specific error code can be obtained using the get_last_result() method.
 446  *          Error codes are described in Exceptions section.
 447  * @since_tizen 2.3.1
 448  *
 449  * @return The number of locales for which decimal formatting patterns are available.
 450  *
 451  * @exception #I18N_ERROR_NONE Successful
 452  */
 453 int32_t i18n_unumber_count_available (void);
 454
 455 /**
 456  * @brief Gets a numeric attribute associated with an #i18n_unumber_format_h.
 457  * @details An example of a numeric attribute is the number of integer digits a formatter will produce.
 458  * @remarks The specific error code can be obtained using the get_last_result() method.
 459  *          Error codes are described in Exceptions section.
 460  * @since_tizen 2.3.1
 461  *
 462  * @param[in] fmt       The formatter to query.
 463  * @param[in] attr      The attribute to query; one of #I18N_UNUMBER_PARSE_INT_ONLY, #I18N_UNUMBER_GROUPING_USED,
 464  *                      #I18N_UNUMBER_DECIMAL_ALWAYS_SHOWN, #I18N_UNUMBER_MAX_INTEGER_DIGITS, #I18N_UNUMBER_MIN_INTEGER_DIGITS,
 465  *                      #I18N_UNUMBER_INTEGER_DIGITS, #I18N_UNUMBER_MAX_FRACTION_DIGITS, #I18N_UNUMBER_MIN_FRACTION_DIGITS,
 466  *                      #I18N_UNUMBER_FRACTION_DIGITS, #I18N_UNUMBER_MULTIPLIER, #I18N_UNUMBER_GROUPING_SIZE,
 467  *                      #I18N_UNUMBER_ROUNDING_MODE, #I18N_UNUMBER_FORMAT_WIDTH, #I18N_UNUMBER_PADDING_POSITION,
 468  *                      #I18N_UNUMBER_SECONDARY_GROUPING_SIZE, #I18N_UNUM_SCALE.
 469  *
 470  * @return The value of @a attr or @c -1 if the given attribute is not supported.
 471  *
 472  * @exception #I18N_ERROR_NONE Successful
 473  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 474  */
 475 int32_t i18n_unumber_get_attribute (const i18n_unumber_format_h fmt, i18n_unumber_format_attribute_e attr);
 476
 477 /**
 478  * @brief Sets a numeric attribute associated with an #i18n_unumber_format_h.
 479  * @details An example of a numeric attribute is the number of integer digits a formatter will produce.
 480  *          If the formatter does not understand the attribute, the call is ignored. Rule-based formatters only understand
 481  *          the lenient-parse attribute. The #I18N_UNUMBER_ROUNDING_INCREMENT attribute is not supported.
 482  * @remarks Error codes are described in #i18n_error_code_e description.
 483  * @since_tizen 2.3.1
 484  *
 485  * @param[in] fmt        The formatter to set.
 486  * @param[in] attr       The attribute to query; one of #I18N_UNUMBER_PARSE_INT_ONLY, #I18N_UNUMBER_GROUPING_USED,
 487  *                       #I18N_UNUMBER_DECIMAL_ALWAYS_SHOWN, #I18N_UNUMBER_MAX_INTEGER_DIGITS, #I18N_UNUMBER_MIN_INTEGER_DIGITS,
 488  *                       #I18N_UNUMBER_INTEGER_DIGITS, #I18N_UNUMBER_MAX_FRACTION_DIGITS, #I18N_UNUMBER_MIN_FRACTION_DIGITS,
 489  *                       #I18N_UNUMBER_FRACTION_DIGITS, #I18N_UNUMBER_MULTIPLIER, #I18N_UNUMBER_GROUPING_SIZE,
 490  *                       #I18N_UNUMBER_ROUNDING_MODE, #I18N_UNUMBER_FORMAT_WIDTH, #I18N_UNUMBER_PADDING_POSITION,
 491  *                       #I18N_UNUMBER_SECONDARY_GROUPING_SIZE, #I18N_UNUMBER_SIGNIFICANT_DIGITS_USED, #I18N_UNUMBER_MIN_SIGNIFICANT_DIGITS,
 492  *                       #I18N_UNUMBER_MAX_SIGNIFICANT_DIGITS, #I18N_UNUMBER_LENIENT_PARSE, #I18N_UNUM_SCALE,
 493  *                       #I18N_UNUM_FORMAT_FAIL_IF_MORE_THAN_MAX_DIGITS, #I18N_UNUM_PARSE_NO_EXPONENT.
 494  * @param[in] new_value  The new value of @a attr.
 495  *
 496  * @return The obtained error code.
 497  * @retval #I18N_ERROR_NONE Successful.
 498  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 499  */
 500 int i18n_unumber_set_attribute (i18n_unumber_format_h fmt, i18n_unumber_format_attribute_e attr, int32_t new_value);
 501
 502 /**
 503  * @brief Gets a numeric attribute associated with an #i18n_unumber_format_h.
 504  * @details An example of a numeric attribute is the number of integer digits a formatter will produce.
 505  *          If the formatter does not understand the attribute, -1 is returned.
 506  * @remarks The specific error code can be obtained using the get_last_result() method.
 507  *          Error codes are described in Exceptions section.
 508  * @since_tizen 2.3.1
 509  *
 510  * @param[in] fmt    The formatter to query.
 511  * @param[in] attr   The attribute to query; only #I18N_UNUMBER_ROUNDING_INCREMENT is supported.
 512  *
 513  * @return The value of @a attr.
 514  *
 515  * @exception #I18N_ERROR_NONE Successful
 516  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 517  */
 518 double i18n_unumber_get_double_attribute (const i18n_unumber_format_h fmt, i18n_unumber_format_attribute_e attr);
 519
 520 /**
 521  * @brief Sets a numeric attribute associated with an #i18n_unumber_format_h.
 522  * @details An example of a numeric attribute is the number of integer digits a formatter will produce.
 523  *          If the formatter does not understand the attribute, this call is ignored.
 524  * @remarks Error codes are described in #i18n_error_code_e description.
 525  * @since_tizen 2.3.1
 526  *
 527  * @param[in] fmt        The formatter to set.
 528  * @param[in] attr       The attribute to query; Only #I18N_UNUMBER_ROUNDING_INCREMENT is supported.
 529  * @param[in] new_value  The new value of @a attr.
 530  *
 531  * @return The obtained error code.
 532  * @retval #I18N_ERROR_NONE Successful.
 533  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 534  */
 535 int i18n_unumber_set_double_attribute (i18n_unumber_format_h fmt, i18n_unumber_format_attribute_e attr, double new_value);
 536
 537 /**
 538  * @brief Gets a text attribute associated with an #i18n_unumber_format_h.
 539  * @details An example of a text attribute is the suffix for positive numbers. If the formatter does not understand the attribute,
 540  *          #I18N_ERROR_NOT_SUPPORTED error code is set.
 541  *          Rule-based formatters only understand #I18N_UNUMBER_DEFAULT_RULESET and #I18N_UNUMBER_PUBLIC_RULESETS.
 542  * @remarks The specific error code can be obtained using the get_last_result() method.
 543  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 544  * @since_tizen 2.3.1
 545  *
 546  * @param[in] fmt               The formatter to query.
 547  * @param[in] tag               The attribute to query; one of #I18N_UNUMBER_POSITIVE_PREFIX, #I18N_UNUMBER_POSITIVE_SUFFIX,
 548  *                              #I18N_UNUMBER_NEGATIVE_PREFIX, #I18N_UNUMBER_NEGATIVE_SUFFIX, #I18N_UNUMBER_PADDING_CHARACTER,
 549  *                              #I18N_UNUMBER_CURRENCY_CODE, #I18N_UNUMBER_DEFAULT_RULESET, or #I18N_UNUMBER_PUBLIC_RULESETS.
 550  * @param[out] result           A pointer to a buffer to receive the attribute.
 551  * @param[in] result_length     The maximum size of @a result.
 552  *
 553  * @return The total buffer size needed; if greater than @a result_length, the output was truncated.
 554  *
 555  * @exception #I18N_ERROR_NONE Successful
 556  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 557  */
 558 int32_t i18n_unumber_get_text_attribute (const i18n_unumber_format_h fmt, i18n_unumber_format_text_attribute_e tag, i18n_uchar *result, int32_t result_length);
 559
 560 /**
 561  * @brief Sets a text attribute associated with an #i18n_unumber_format_h.
 562  * @details An example of a text attribute is the suffix for positive numbers. Rule-based formatters only understand
 563  *          #I18N_UNUMBER_DEFAULT_RULESET. The #I18N_UNUMBER_PUBLIC_RULESETS tag is not supported.
 564  * @remarks Error codes are described in #i18n_error_code_e description.
 565  * @since_tizen 2.3.1
 566  *
 567  * @param[in] fmt                The formatter to set.
 568  * @param[in] tag                The attribute to set; one of #I18N_UNUMBER_POSITIVE_PREFIX, #I18N_UNUMBER_POSITIVE_SUFFIX,
 569  *                               #I18N_UNUMBER_NEGATIVE_PREFIX, #I18N_UNUMBER_NEGATIVE_SUFFIX, #I18N_UNUMBER_PADDING_CHARACTER,
 570  *                               #I18N_UNUMBER_CURRENCY_CODE, #I18N_UNUMBER_DEFAULT_RULESET.
 571  * @param[in] new_value          The new value of @a tag.
 572  * @param[in] new_value_length   The length of new_value, or -1 if NULL-terminated.
 573  *
 574  * @return The obtained error code.
 575  * @retval #I18N_ERROR_NONE Successful.
 576  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 577  */
 578 int i18n_unumber_set_text_attribute (const i18n_unumber_format_h fmt, i18n_unumber_format_text_attribute_e tag, const i18n_uchar *new_value, int32_t new_value_length);
 579
 580 /**
 581  * @brief Extracts the pattern from an #i18n_unumber_format_h.
 582  * @details The pattern will follow the DecimalFormat pattern syntax.
 583  * @remarks The specific error code can be obtained using the get_last_result() method.
 584  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 585  * @since_tizen 2.3.1
 586  *
 587  * @param[in] fmt                    The formatter to query.
 588  * @param[in] is_pattern_localized   true if the pattern should be localized, false otherwise.
 589  *                                   This is ignored if the formatter is a rule-based formatter.
 590  * @param[out] result                A pointer to a buffer to receive the pattern.
 591  * @param[in] result_length          The maximum size of @a result.
 592  *
 593  * @return The total buffer size needed; if greater than @a result_length, the output was truncated.
 594  *
 595  * @exception #I18N_ERROR_NONE Successful
 596  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 597  */
 598 int32_t i18n_unumber_to_pattern (const i18n_unumber_format_h fmt, i18n_ubool is_pattern_localized, i18n_uchar *result, int32_t result_length);
 599
 600 /**
 601  * @brief Sets a symbol associated with an #i18n_unumber_format_h.
 602  * @details An #i18n_unumber_format_h uses symbols to represent the special locale-dependent characters in a number, for example the percent sign.
 603  *          This API is not supported for rule-based formatters.
 604  * @remarks Error codes are described in #i18n_error_code_e description.
 605  * @since_tizen 2.3.1
 606  *
 607  * @param[in] fmt        The formatter to set.
 608  * @param[in] symbol     The #i18n_unumber_format_symbol_e constant for the symbol to set
 609  * @param[in] value      The string to set the symbol to
 610  * @param[in] length     The length of the input string, or -1 for a zero-terminated string
 611  *
 612  * @return The obtained error code.
 613  * @retval #I18N_ERROR_NONE Successful.
 614  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 615  */
 616 int i18n_unumber_set_symbol (i18n_unumber_format_h fmt, i18n_unumber_format_symbol_e symbol, const i18n_uchar *value, int32_t length);
 617
 618 /**
 619  * @brief Gets the locale for this number format object.
 620  * @details You can choose between valid and actual locale.
 621  * @remarks The specific error code can be obtained using the get_last_result() method.
 622  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 623  * @since_tizen 2.3.1
 624  *
 625  * @param[in] fmt        The formatter to get the locale from.
 626  * @param[in] type       Type of the locale we're looking for (valid or actual)
 627  *
 628  * @return The locale name
 629  *
 630  * @exception #I18N_ERROR_NONE Successful
 631  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 632  */
 633 const char *i18n_unumber_get_locale_by_type (const i18n_unumber_format_h fmt, i18n_ulocale_data_locale_type_e type);
 634
 635
 636 #ifdef __cplusplus
 637 }
 638 #endif
 639
 640 /**
 641  * @}
 642  * @}
 643  */
 644
 645 #endif  /* __UTILS_I18N_UNUMBER_H__*/