src/include/wearable/utils_i18n_udatepg.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_UDATEPG_H__
  18 #define __UTILS_I18N_UDATEPG_H__
  19
  20 #include <utils_i18n_types.h>
  21
  22 /**
  23  * @file utils_i18n_udatepg.h
  24  * @version 0.1
  25  * @brief utils_i18n_udatepg
  26  */
  27
  28 /**
  29  * @ingroup CAPI_BASE_UTILS_I18N_MODULE
  30  * @defgroup CAPI_BASE_UTILS_I18N_UDATEPG_MODULE Udatepg
  31  * @brief The Udatepg module provides flexible generation of date format patterns, like "yy-MM-dd". The user can build up the generator by adding successive patterns.
  32  *
  33  * @section CAPI_BASE_UTILS_I18N_UDATEPG_MODULE_HEADER Required Header
  34  *  \#include <utils_i18n.h>
  35  *
  36  * @section CAPI_BASE_UTILS_I18N_UDATEPG_MODULE_OVERVIEW Overview
  37  * @details The Udatepg module provides flexible generation of date format patterns,
  38  * like "yy-MM-dd". The user can build up the generator by adding successive patterns.
  39  * Once that is done, a query can be made using a "skeleton", which is a pattern that
  40  * just includes the desired fields and lengths. The generator will return the
  41  * "best fit" pattern corresponding to that skeleton.\n
  42  * The main method people will use is i18n_udatepg_get_best_pattern(), since normally
  43  * #i18n_udatepg_h is pre-built with data from a particular locale.
  44  * However, generators can be built directly from other data as well.
  45  *
  46  * All input handlers must not be @c NULL.
  47  *
  48  * @section CAPI_BASE_UTILS_I18N_UDATEPG_MODULE_SAMPLE_CODE_1 Sample Code 1
  49  * @brief Gets the best pattern according to a given locale and formats a current date and time using an i18n_udate_format_h
  50  * @code
  51     i18n_udatepg_h pattern_generator = NULL;
  52     char *locale = I18N_ULOCALE_US;
  53
  54     dlog_print(DLOG_INFO, LOG_TAG, "pattern_generator\n");
  55
  56     if(!pattern_generator) {
  57         // create a pattern generator according to a given locale
  58         i18n_udatepg_create(locale, &pattern_generator);
  59     }
  60
  61     if(!pattern_generator) {
  62         dlog_print(DLOG_INFO, LOG_TAG, "i18n_udatepg_create fail");
  63         return ;
  64     }
  65
  66     i18n_uchar bestPattern[64] = {0,};
  67     char bestPatternString[64] = {0,};
  68     int bestPatternLength, len;
  69     const char *custom_format = "yyyy.MM.dd G 'at' HH:mm:ss zzz";
  70     i18n_uchar uch_custom_format[64];
  71     int ret = I18N_ERROR_NONE;
  72
  73     dlog_print(DLOG_INFO, LOG_TAG, "getBestPattern\n");
  74
  75     i18n_ustring_copy_ua(uch_custom_format, custom_format);
  76     len = i18n_ustring_get_length(uch_custom_format);
  77
  78     // gets the best pattern that matches the given custom_format
  79     i18n_udatepg_get_best_pattern(pattern_generator, uch_custom_format, len, bestPattern, 64, &bestPatternLength);
  80
  81     i18n_ustring_copy_au_n(bestPatternString, bestPattern, 64);
  82     // gets "MM/dd/yyyy G h:mm:ss a zzz" as the best pattern
  83     dlog_print(DLOG_INFO, LOG_TAG, "getBestPattern(char[]) : %s \n", bestPatternString);
  84
  85     // closes a generator
  86     i18n_udatepg_destroy(pattern_generator);
  87
  88     i18n_udate_format_h formatter_KR = NULL;
  89     i18n_udate_format_h formatter_LA = NULL;
  90     i18n_udate_format_h formatter_SaoPaulo = NULL;
  91     i18n_uchar formatted[64] = {0,};
  92     char result[64] = {0,};
  93     int formattedLength;
  94     i18n_udate date;
  95     const char *timezone_KR = "GMT+9:00";   // TimeZone for Korea/Seoul
  96     const char *timezone_LA = "America/Los_Angeles";
  97     const char *timezone_SaoPaulo = "America/Sao_Paulo";    // Brazil/East
  98     i18n_uchar utf16_timezone_KR[64] = {0,};
  99     i18n_uchar utf16_timezone_LA[64] = {0,};
 100     i18n_uchar utf16_timezone_SaoPaulo[64] = {0,};
 101
 102     i18n_ustring_copy_ua_n(utf16_timezone_KR, timezone_KR, strlen(timezone_KR));
 103     i18n_ustring_copy_ua_n(utf16_timezone_LA, timezone_LA, strlen(timezone_LA));
 104     i18n_ustring_copy_ua_n(utf16_timezone_SaoPaulo, timezone_SaoPaulo, strlen(timezone_SaoPaulo));
 105
 106     // creates new i18n_udate_format to format dates and times
 107     ret = i18n_udate_create(I18N_UDATE_FULL , I18N_UDATE_FULL , locale, utf16_timezone_KR, -1, bestPattern, -1, &formatter_KR);
 108     if ( ret != I18N_ERROR_NONE ) {
 109         dlog_print(DLOG_INFO, LOG_TAG, "i18n_udate_create failed !!! \n");
 110     }
 111     if (!formatter_KR) {
 112         dlog_print(DLOG_INFO, LOG_TAG, "formatter is NULL\n");
 113     }
 114     ret = i18n_udate_create(I18N_UDATE_FULL , I18N_UDATE_FULL , locale, utf16_timezone_LA, -1, bestPattern, -1, &formatter_LA);
 115     if ( ret != I18N_ERROR_NONE ) {
 116         dlog_print(DLOG_INFO, LOG_TAG, "i18n_udate_create failed !!! \n");
 117     }
 118     if (!formatter_LA) {
 119         dlog_print(DLOG_INFO, LOG_TAG, "formatter is NULL\n");
 120     }
 121     ret = i18n_udate_create(I18N_UDATE_PATTERN , I18N_UDATE_PATTERN , locale, utf16_timezone_SaoPaulo, -1, bestPattern, -1, &formatter_SaoPaulo);
 122     if ( ret != I18N_ERROR_NONE ) {
 123         dlog_print(DLOG_INFO, LOG_TAG, "i18n_udate_create failed !!! \n");
 124     }
 125     if (!formatter_LA) {
 126         dlog_print(DLOG_INFO, LOG_TAG, "formatter is NULL\n");
 127     }
 128
 129     dlog_print(DLOG_INFO, LOG_TAG, "i18n_udate_format_date\n");
 130
 131     // gets the current date and time
 132     i18n_ucalendar_get_now(&date);
 133
 134     // formats a date using i18n_udate_format
 135     i18n_udate_format_date(formatter_KR, date, formatted, 64, NULL, &formattedLength);
 136     i18n_ustring_copy_au_n(result, formatted, 64);
 137     //ex) KOREA/Seoul - Current date : Wednesday, June 18, 2014 1:34:54 PM GMT+09:00
 138     dlog_print(DLOG_INFO, LOG_TAG, "KOREA/Seoul - Current date : %s\n",result);
 139
 140     // formats a date using i18n_udate_format
 141     i18n_udate_format_date(formatter_LA, date, formatted, 64, NULL, &formattedLength);
 142     i18n_ustring_copy_au_n(result, formatted, 64);
 143     //ex) America/LOS Angeles - Current date : Tuesday, June 17, 2014 9:34:54 PM Pacific Daylight Time
 144     dlog_print(DLOG_INFO, LOG_TAG, "America/LOS Angeles - Current date : %s\n",result);
 145
 146     // formats a date using i18n_udate_format
 147     i18n_udate_format_date(formatter_SaoPaulo, date, formatted, 64, NULL, &formattedLength);
 148     i18n_ustring_copy_au_n(result, formatted, 64);
 149     //ex) Brazil/Sao Paulo - Current date : 6 18, 2014 AD, 1:34:54 PM GMT-2
 150     dlog_print(DLOG_INFO, LOG_TAG, "Brazil/Sao Paulo - Current date : %s\n",result);
 151
 152     dlog_print(DLOG_INFO, LOG_TAG, "i18n_udate_destroy\n");
 153     // destroy an #i18n_udate_format_h
 154     i18n_udate_destroy(formatter_KR);
 155     i18n_udate_destroy(formatter_LA);
 156     i18n_udate_destroy(formatter_SaoPaulo);
 157  * @endcode
 158  */
 159
 160 /**
 161  * @addtogroup CAPI_BASE_UTILS_I18N_UDATEPG_MODULE
 162  * @{
 163  */
 164
 165 #ifdef __cplusplus
 166 extern "C" {
 167 #endif
 168
 169 /**
 170  * @brief Opens a generator according to a given locale.
 171  * @remarks Must release @a dtpg using i18n_udatepg_destroy().
 172  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 173  *
 174  * @param[in] locale    If @c NULL - default locale will be used.
 175  * @param[out] dtpg     A pointer to #i18n_udatepg_h. Must not be @c NULL.
 176  *
 177  * @retval #I18N_ERROR_NONE Successful
 178  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 179  */
 180 int i18n_udatepg_create ( const char *locale, i18n_udatepg_h *dtpg );
 181
 182 /**
 183  * @brief Destroys a generator.
 184  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 185  *
 186  * @param[in] dtpg     A pointer to #i18n_udatepg_h. Must not be @c NULL.
 187  *
 188  * @retval #I18N_ERROR_NONE Successful
 189  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 190  */
 191 int i18n_udatepg_destroy ( i18n_udatepg_h dtpg );
 192
 193 /**
 194  * @brief Gets the best pattern matching the input skeleton.
 195  * @details It is guaranteed to have all of the fields in the skeleton.
 196  * @remarks This function uses a non-const #i18n_udatepg_h:
 197  *          It uses a stateful pattern parser which is set up for each generator object,
 198  *          rather than creating one for each function call.
 199  *          Consecutive calls to this function do not affect each other,
 200  *          but this function cannot be used concurrently on a single generator object.
 201  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 202  *
 203  * @param[in] dtpg                  A pointer to #i18n_udatepg_h. Must not be @c NULL.
 204  * @param[in] skeleton              The skeleton is a pattern containing only the variable fields.\n
 205  *                                  For example, "MMMdd" and "mmhh" are skeletons. Must not be @c NULL.
 206  * @param[in] len                   The length of the @a skeleton, >= 0.
 207  * @param[out] best_pattern         The best pattern found from the given @a skeleton.
 208  * @param[in] capacity              The capacity of @a best_pattern, >= 0
 209  * @param[out] best_pattern_len     The length of @a best_pattern.
 210  *
 211  * @retval #I18N_ERROR_NONE Successful
 212  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 213  * @retval #I18N_ERROR_BUFFER_OVERFLOW A result would not fit in the supplied buffer
 214  */
 215 int i18n_udatepg_get_best_pattern ( i18n_udatepg_h dtpg, const i18n_uchar *skeleton, int32_t len, i18n_uchar *best_pattern, int32_t capacity, int32_t *best_pattern_len );
 216
 217
 218 // Newly Added APIs
 219
 220
 221 /**
 222  * @brief Creates an empty generator, to be constructed with i18n_udatepg_add_pattern() etc.
 223  * @since_tizen 2.3.1
 224  *
 225  * @param[out] dtpg     A pointer to the #i18n_udatepg_h handle.
 226  *
 227  * @return The obtained error code.
 228  * @retval #I18N_ERROR_NONE Successful
 229  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 230  */
 231 int i18n_udatepg_create_empty (i18n_udatepg_h *dtpg);
 232
 233 /**
 234  * @brief Creates a copy of a generator.
 235  * @since_tizen 2.3.1
 236  *
 237  * @param[in] dtpg          An #i18n_udatepg_h handle to be copied. Must not be @c NULL.
 238  * @param[out] dtpg_clone   A pointer to clone of @c dtpg handle.
 239  *
 240  * @return The obtained error code.
 241  * @retval #I18N_ERROR_NONE Successful
 242  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 243  */
 244 int i18n_udatepg_clone ( const i18n_udatepg_h dtpg, i18n_udatepg_h * dtpg_clone);
 245
 246 /**
 247  * @brief Gets the best pattern matching the input @a skeleton.
 248  * @details It is guaranteed to have all of the fields in the @a skeleton.
 249  *
 250  *          Note that this function uses a non-const #i18n_udatepg_h:
 251  *          It uses a stateful pattern parser which is set up for each generator object,
 252  *          rather than creating one for each function call.
 253  *          Consecutive calls to this function do not affect each other,
 254  *          but this function cannot be used concurrently on a single generator object.
 255  * @remarks The specific error code can be obtained using the get_last_result() method.
 256  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 257  * @since_tizen 2.3.1
 258  *
 259  * @param[in] dtpg              An #i18n_udatepg_h handle. Must not be @c NULL.
 260  * @param[in] skeleton          The @c skeleton is a pattern containing only the variable fields;
 261  *                              for example, "MMMdd" and "mmhh" are skeletons. Must not be @c NULL.
 262  * @param[in] length            The length of @c skeleton, >= 0.
 263  * @param[in] options           Options for forcing the length of specified fields in the
 264  *                              returned pattern to match those in the @c skeleton (when this
 265  *                              would not happen otherwise). For default behavior, use
 266  *                              #I18N_UDATEPG_MATCH_NO_OPTIONS.
 267  * @param[out] best_pattern     The best pattern found from the given @c skeleton.
 268  * @param[in] capacity          The capacity of @c best_pattern, >= 0.
 269  *
 270  * @return The length of @c best_pattern.
 271  *
 272  * @exception #I18N_ERROR_NONE Successful
 273  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 274  */
 275 int32_t i18n_udatepg_get_best_pattern_with_options ( i18n_udatepg_h dtpg, const i18n_uchar *skeleton, int32_t length,
 276         i18n_udatepg_date_time_pattern_match_options_e options, i18n_uchar *best_pattern, int32_t capacity );
 277
 278 /**
 279  * @brief Gets a unique skeleton from a given pattern. For example, both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd".
 280  * @details Note that this function uses a non-const #i18n_udatepg_h:
 281  *          It uses a stateful pattern parser which is set up for each generator object,
 282  *          rather than creating one for each function call.
 283  *          Consecutive calls to this function do not affect each other,
 284  *          but this function cannot be used concurrently on a single generator object.
 285  * @remarks The specific error code can be obtained using the get_last_result() method.
 286  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 287  * @since_tizen 2.3.1
 288  *
 289  * @param[in] dtpg        An #i18n_udatepg_h handle. Must not be @c NULL.
 290  * @param[in] pattern     Input pattern, such as "dd/MMM". Must not be @c NULL.
 291  * @param[in] length      The length of @c pattern, >= 0.
 292  * @param[out] skeleton   Such as "MMMdd".
 293  * @param[in] capacity    The capacity of @c skeleton, >= 0.
 294  *
 295  * @return The length of @c skeleton.
 296  *
 297  * @exception #I18N_ERROR_NONE Successful
 298  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 299  */
 300 int32_t i18n_udatepg_get_skeleton ( i18n_udatepg_h dtpg, const i18n_uchar *pattern, int32_t length, i18n_uchar *skeleton, int32_t capacity );
 301
 302 /**
 303  * @brief Gets a unique base skeleton from a given pattern.
 304  * @details This is the same as the skeleton, except that differences in length are minimized so
 305  *          as to only preserve the difference between string and numeric form. So
 306  *          for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd"(notice the single d).<br>
 307  *          Note that this function uses a non-const #i18n_udatepg_h :
 308  *          It uses a stateful pattern parser which is set up for each generator object,
 309  *          rather than creating one for each function call.
 310  *          Consecutive calls to this function do not affect each other,
 311  *          but this function cannot be used concurrently on a single generator object.
 312  * @remarks The specific error code can be obtained using the get_last_result() method.
 313  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 314  * @since_tizen 2.3.1
 315  *
 316  * @param[in] dtpg              An #i18n_udatepg_h handle. Must not be @c NULL.
 317  * @param[in] pattern           Input pattern, such as "dd/MMM". Must not be @c NULL.
 318  * @param[in] length            The length of @c pattern, >= 0.
 319  * @param[out] base_skeleton    Such as "Md".
 320  * @param[in] capacity          The capacity of base @c skeleton, >= 0.
 321  *
 322  * @return The length of @c base_skeleton.
 323  *
 324  * @exception #I18N_ERROR_NONE Successful
 325  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 326  */
 327 int32_t i18n_udatepg_get_base_skeleton ( i18n_udatepg_h dtpg, const i18n_uchar *pattern, int32_t length, i18n_uchar *base_skeleton, int32_t capacity );
 328
 329 /**
 330  * @brief Adds a pattern to the generator.
 331  * @details If the pattern has the same skeleton as an existing pattern,
 332  *          and the override parameter is set, then the previous
 333  *          value is overridden. Otherwise, the previous value is retained.
 334  *          In either case, the conflicting status is set and previous value is stored in conflicting pattern. <br>
 335  *          Note that single-field patterns (like "MMM") are automatically added, and don't need to be added explicitly!
 336  * @remarks The specific error code can be obtained using the get_last_result() method.
 337  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 338  * @since_tizen 2.3.1
 339  *
 340  * @param[in] dtpg                          An #i18n_udatepg_h handle. Must not be @c NULL.
 341  * @param[in] pattern                       Input pattern, such as "dd/MMM". Must not be @c NULL.
 342  * @param[in] pattern_length                The length of @c pattern, >= 0.
 343  * @param[in] override                      when existing values are to be overridden use true,
 344  *                                          otherwise use false.
 345  * @param[out] conflicting_pattern          Previous pattern with the same skeleton.
 346  * @param[in]  capacity                     The capacity of @c conflicting_pattern.
 347  * @param[out] conflict_status A pointer to the conflicting status
 348  *         The value could be #I18N_UDATEPG_NO_CONFLICT, #I18N_UDATEPG_BASE_CONFLICT or #I18N_UDATEPG_CONFLICT.
 349  *
 350  * @return  Length of @c conflicting_pattern. -1 if @c conflict_status is #I18N_UDATEPG_NO_CONFLICT
 351  *
 352  * @exception #I18N_ERROR_NONE Successful
 353  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 354  */
 355 int32_t  i18n_udatepg_add_pattern ( i18n_udatepg_h dtpg, const i18n_uchar *pattern, int32_t pattern_length, i18n_ubool override, i18n_uchar *conflicting_pattern, int32_t capacity, i18n_udatepg_date_time_pattern_conflict_e * conflict_status );
 356
 357 /**
 358  * @brief An append_item_format is a pattern used to append a field if there is no good match.
 359  * @details For example, suppose that the input skeleton is "GyyyyMMMd",
 360  *          and there is no matching pattern internally, but there is a pattern
 361  *          matching "yyyyMMMd", say "d-MM-yyyy". Then that pattern is used, plus the G.
 362  *          The way these two are conjoined is by using the append_item_format for G (era).
 363  *          So if that value is, say "{0}, {1}" then the final resulting
 364  *          pattern is "d-MM-yyyy, G". <br>
 365  *          There are actually three available variables : {0} is the pattern so far,
 366  *          {1} is the element we are adding, and {2} is the name of the element. <br>
 367  *          This reflects the way that the CLDR data is organized.
 368  * @since_tizen 2.3.1
 369  *
 370  * @param[in] dtpg      An #i18n_udatepg_h handle. Must not be @c NULL.
 371  * @param[in] field     One of #i18n_udatepg_date_time_pattern_field_e, such as #I18N_UDATEPG_ERA_FIELD.
 372  * @param[in] value     Pattern, such as "{0}, {1}". Must not be @c NULL.
 373  * @param[in] length    The length of @c value, >= 0.
 374  *
 375  * @return The obtained error code.
 376  * @retval #I18N_ERROR_NONE Successful
 377  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 378  *
 379  * @see i18n_udatepg_get_append_item_format()
 380  */
 381 int i18n_udatepg_set_append_item_format ( i18n_udatepg_h dtpg, i18n_udatepg_date_time_pattern_field_e field, const i18n_uchar *value, int32_t length );
 382
 383 /**
 384  * @brief Getter corresponding to i18n_udatepg_set_append_item_format().
 385  * @details Values below 0 or at or above #I18N_UDATEPG_FIELD_COUNT are illegal arguments.
 386  * @remarks The specific error code can be obtained using the get_last_result() method.
 387  *          Error codes are described in Exceptions section.
 388  * @since_tizen 2.3.1
 389  *
 390  * @param[in] dtpg              An #i18n_udatepg_h handle. Must not be @c NULL.
 391  * @param[in] field             One of #i18n_udatepg_date_time_pattern_field_e, such as #I18N_UDATEPG_ERA_FIELD.
 392  * @param[out] pattern_length   A pointer that will receive the length of append item format @a value.
 393  *
 394  * @return The append_item_format for @a field
 395  *
 396  * @exception #I18N_ERROR_NONE Successful
 397  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 398  *
 399  * @see i18n_udatepg_set_append_item_format()
 400  */
 401 const i18n_uchar *i18n_udatepg_get_append_item_format ( const i18n_udatepg_h dtpg, i18n_udatepg_date_time_pattern_field_e field, int32_t *pattern_length );
 402
 403 /**
 404  * @brief Sets the name of field, e.g. "era" in English for ERA.
 405  * @details These are only used if the corresponding append_item_format is used, and if it contains a {2} variable.
 406  *          This reflects the way that the CLDR data is organized.
 407  * @since_tizen 2.3.1
 408  *
 409  * @param[in] dtpg      An #i18n_udatepg_h handle. Must not be @c NULL.
 410  * @param[in] field     #i18n_udatepg_date_time_pattern_field_e, such as #I18N_UDATEPG_ERA_FIELD.
 411  * @param[in] value     Name for the @c field. Must not be @c NULL.
 412  * @param[in] length    The length of @c value, >= 0.
 413  *
 414  * @return The obtained error code.
 415  * @retval #I18N_ERROR_NONE Successful
 416  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 417  *
 418  * @see i18n_udatepg_get_append_item_name()
 419  */
 420 int i18n_udatepg_set_append_item_name ( i18n_udatepg_h dtpg, i18n_udatepg_date_time_pattern_field_e field, const i18n_uchar *value,
 421         int32_t length );
 422
 423 /**
 424  * @brief Getter corresponding to i18n_udatepg_set_append_item_name().
 425  * @details Values below 0 or at or above #I18N_UDATEPG_FIELD_COUNT are illegal arguments.
 426  * @remarks The specific error code can be obtained using the get_last_result() method.
 427  *          Error codes are described in Exceptions section.
 428  * @since_tizen 2.3.1
 429  *
 430  * @param[in] dtpg              The #i18n_udate_format_h handle. Must not be @c NULL.
 431  * @param[in] field             #i18n_udatepg_date_time_pattern_field_e, such as #I18N_UDATEPG_ERA_FIELD.
 432  * @param[out] pattern_length   A pointer that will receive the length of the name for @c field.
 433  *
 434  * @return The name for @c field
 435  *
 436  * @exception #I18N_ERROR_NONE Successful
 437  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 438  *
 439  * @see i18n_udatepg_set_append_item_name()
 440  */
 441 const i18n_uchar *i18n_udatepg_get_append_item_name ( const i18n_udatepg_h dtpg, i18n_udatepg_date_time_pattern_field_e field,
 442         int32_t *pattern_length );
 443
 444 /**
 445  * @brief The date time format is a message format pattern used to compose date and time patterns.
 446  * @brief The default value is "{0} {1}", where {0} will be replaced by the date pattern and {1} will be replaced by the time pattern.
 447  *        This is used when the input skeleton contains both date and time fields,
 448  *        but there is not a close match among the added patterns.
 449  *        For example, suppose that this object was created by adding "dd-MMM" and "hh:mm",
 450  *        and its date time format is the default "{0} {1}". Then if the input skeleton is "MMMdhmm",
 451  *        there is not an exact match, so the input skeleton is broken up into two components "MMMd" and "hmm".
 452  *        There are close matches for those two skeletons, so the result is put together with this pattern, resulting in "d-MMM h:mm".
 453  * @since_tizen 2.3.1
 454  *
 455  * @param[in] dtpg              An #i18n_udate_format_h handle. Must not be @c NULL.
 456  * @param[in] date_time_format  A message format pattern, here {0} will be replaced by the date pattern
 457  *                              and {1} will be replaced by the time pattern. Must not be @c NULL.
 458  * @param[in] length            The length of @c date_time_format, >= 0.
 459  *
 460  * @return The obtained error code.
 461  * @retval #I18N_ERROR_NONE Successful
 462  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 463  *
 464  * @see i18n_udatepg_get_date_time_format()
 465  */
 466 int i18n_udatepg_set_date_time_format ( const i18n_udatepg_h dtpg, const i18n_uchar *date_time_format, int32_t length );
 467
 468 /**
 469  * @brief Getter corresponding to i18n_udatepg_set_date_time_format().
 470  * @remarks The specific error code can be obtained using the get_last_result() method.
 471  *          Error codes are described in Exceptions section.
 472  * @since_tizen 2.3.1
 473  *
 474  * @param[in] dtpg              An #i18n_udate_format_h handle. Must not be @c NULL.
 475  * @param[out] pattern_length   A pointer that will receive the length of the @a date_time_format.
 476  *
 477  * @return A date_time_format
 478  *
 479  * @exception #I18N_ERROR_NONE Successful
 480  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 481  *
 482  * @see i18n_udatepg_set_date_time_format()
 483  */
 484 const i18n_uchar *i18n_udatepg_get_date_time_format ( const i18n_udatepg_h dtpg, int32_t *pattern_length );
 485
 486 /**
 487  * @brief The decimal value is used in formatting fractions of seconds.
 488  * @details If the skeleton contains fractional seconds, then this is used with the fractional seconds.
 489  *          For example, suppose that the input pattern is "hhmmssSSSS",
 490  *          and the best matching pattern internally is "H:mm:ss", and the decimal string is ",".
 491  *          Then the resulting pattern is modified to be "H:mm:ss,SSSS"
 492  * @since_tizen 2.3.1
 493  *
 494  * @param[in] dtpg      The #i18n_udate_format_h handle. Must not be @c NULL.
 495  * @param[in] decimal   Decimal. Must not be @c NULL.
 496  * @param[in] length    The length of @c decimal, >= 0.
 497  *
 498  * @return The obtained error code.
 499  * @retval #I18N_ERROR_NONE Successful
 500  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 501  *
 502  * @see i18n_udatepg_get_decimal()
 503  */
 504 int i18n_udatepg_set_decimal ( i18n_udatepg_h dtpg, const i18n_uchar *decimal, int32_t length );
 505
 506 /**
 507  * @brief Getter corresponding to i18n_udatepg_set_decimal().
 508  * @remarks The specific error code can be obtained using the get_last_result() method.
 509  *          Error codes are described in Exceptions section.
 510  * @since_tizen 2.3.1
 511  *
 512  * @param[in] dtpg              The #i18n_udate_format_h handle. Must not be @c NULL.
 513  * @param[out] pattern_length   A pointer that will receive the length of the @a decimal string.
 514  *
 515  * @return Corresponding to the decimal point.
 516  *
 517  * @exception #I18N_ERROR_NONE Successful
 518  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 519  *
 520  * @see i18n_udatepg_set_decimal()
 521  */
 522 const i18n_uchar *i18n_udatepg_get_decimal ( const i18n_udatepg_h dtpg, int32_t *pattern_length );
 523
 524 /**
 525  * @brief Adjusts the field types (width and subtype) of a @a pattern to match what is in a @a skeleton.
 526  * @details That is, if you supply a @a pattern like "d-M H:m", and a @a skeleton of "MMMMddhhmm",
 527  *          then the input pattern is adjusted to be "dd-MMMM hh:mm".
 528  *          This is used internally to get the best match for the input @a skeleton, but can also be used externally.<br>
 529  *          Note that this function uses a non-const #i18n_udatepg_h:
 530  *          It uses a stateful pattern parser which is set up for each generator object,
 531  *          rather than creating one for each function call. Consecutive calls to this function do not affect each other,
 532  *          but this function cannot be used concurrently on a single generator object.
 533  * @remarks The specific error code can be obtained using the get_last_result() method.
 534  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 535  * @since_tizen 2.3.1
 536  *
 537  * @param[in] dtpg              The #i18n_udate_format_h handle. Must not be @c NULL.
 538  * @param[in] pattern           Input pattern. Must not be @c NULL.
 539  * @param[in] pattern_length    The length of input @a pattern, >= 0.
 540  * @param[in] skeleton          The skeleton. Must not be @c NULL.
 541  * @param[in] skeleton_length   The length of input @a skeleton, >= 0.
 542  * @param[out] dest             Pattern adjusted to match the @a skeleton fields widths and subtypes.
 543  * @param[in] dest_capacity     The capacity of @a dest, >= 0.
 544  *
 545  * @return The length of @a dest.
 546  *
 547  * @exception #I18N_ERROR_NONE Successful
 548  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 549  */
 550 int32_t i18n_udatepg_replace_field_types ( i18n_udatepg_h dtpg, const i18n_uchar *pattern, int32_t pattern_length,
 551         const i18n_uchar *skeleton, int32_t skeleton_length, i18n_uchar *dest, int32_t dest_capacity );
 552
 553 /**
 554  * @brief Adjusts the field types (width and subtype) of a pattern to match what is in a @a skeleton.
 555  * @details That is, if you supply a @a pattern like "d-M H:m", and a @a skeleton of "MMMMddhhmm",
 556  *          then the input @a pattern is adjusted to be "dd-MMMM hh:mm".
 557  *          This is used internally to get the best match for the input @a skeleton, but can also be used externally.<br>
 558  *          Note that this function uses a non-const #i18n_udatepg_h:
 559  *          It uses a stateful pattern parser which is set up for each generator object,
 560  *          rather than creating one for each function call. Consecutive calls to this function do not affect each other,
 561  *          but this function cannot be used concurrently on a single generator object.
 562  * @remarks The specific error code can be obtained using the get_last_result() method.
 563  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 564  * @since_tizen 2.3.1
 565  *
 566  * @param[in] dtpg              The #i18n_udate_format_h handle. Must not be @c NULL.
 567  * @param[in] pattern           Input pattern. Must not be @c NULL.
 568  * @param[in] pattern_length    The length of input @a pattern, >= 0.
 569  * @param[in] skeleton          The skeleton. Must not be @c NULL.
 570  * @param[in] skeleton_length   The length of input @a skeleton, >= 0.
 571  * @param[in] options           Options controlling whether the length of specified
 572  *                              fields in the @a pattern are adjusted to match those in the @a skeleton
 573  *                              (when this would not happen otherwise).
 574  *                              For default behavior, use #I18N_UDATEPG_MATCH_NO_OPTIONS.
 575  * @param[out] dest             Pattern adjusted to match the @a skeleton fields widths and subtypes.
 576  * @param[in] dest_capacity     The capacity of @a dest, >= 0.
 577  *
 578  * @return The length of @a dest.
 579  *
 580  * @exception #I18N_ERROR_NONE Successful
 581  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 582  */
 583 int32_t i18n_udatepg_replace_field_types_with_options ( i18n_udatepg_h dtpg, const i18n_uchar *pattern, int32_t pattern_length,
 584         const i18n_uchar *skeleton, int32_t skeleton_length, i18n_udatepg_date_time_pattern_match_options_e options,
 585         i18n_uchar *dest, int32_t dest_capacity );
 586
 587 /**
 588  * @brief Creates an #i18n_uenumeration_h for list of all the skeletons in canonical form.
 589  * @details Call i18n_udatepg_get_pattern_for_skeleton() to get the corresponding pattern.
 590  * @since_tizen 2.3.1
 591  *
 592  * @param[in] dtpg      An #i18n_udate_format_h handle. Must not be @c NULL.
 593  * @param[out] enumeration A pointer to the #i18n_uenumeration_h for list of all the skeletons. The caller must destroy the object.
 594  *
 595  * @return The obtained error code.
 596  * @retval #I18N_ERROR_NONE Successful
 597  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 598  */
 599 int i18n_udatepg_skeletons_create ( const i18n_udatepg_h dtpg, i18n_uenumeration_h *enumeration );
 600
 601 /**
 602  * @brief Creates an #i18n_uenumeration_h for list of all the base skeletons in canonical form.
 603  * @since_tizen 2.3.1
 604  *
 605  * @param[in] dtpg      An #i18n_udate_format_h handle. Must not be @c NULL.
 606  * @param[out] enumeration A pointer to the #i18n_uenumeration_h for list of all the base skeletons. The caller must destroy the object.
 607  *
 608  * @return The obtained error code.
 609  * @retval #I18N_ERROR_NONE Successful
 610  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 611  */
 612 int i18n_udatepg_base_skeletons_create ( const i18n_udatepg_h dtpg, i18n_uenumeration_h *enumeration );
 613
 614 /**
 615  * @brief Gets the pattern corresponding to a given skeleton.
 616  * @remarks The specific error code can be obtained using the get_last_result() method.
 617  *          Error codes are described in Exceptions section.
 618  * @since_tizen 2.3.1
 619  *
 620  * @param[in] dtpg              The #i18n_udate_format_h handle. Must not be @c NULL.
 621  * @param[in] skeleton          The skeleton. Must not be @c NULL.
 622  * @param[in] skeleton_length   The length of @a skeleton, >= 0.
 623  * @param[out] pattern_length   The pointer to the length of return pattern
 624  *
 625  * @return Pattern corresponding to a given skeleton
 626  *
 627  * @exception #I18N_ERROR_NONE Successful
 628  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 629  */
 630 const i18n_uchar *i18n_udatepg_get_pattern_for_skeleton ( const i18n_udatepg_h dtpg, const i18n_uchar *skeleton, int32_t skeleton_length, int32_t *pattern_length );
 631
 632
 633 #ifdef __cplusplus
 634 }
 635 #endif
 636
 637 /**
 638  * @}
 639  * @}
 640  */
 641
 642 #endif  /* __UTILS_I18N_UDATEPG_H__*/