src/include/mobile/utils_i18n_udate.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_UDATE_H__
  18 #define __UTILS_I18N_UDATE_H__
  19
  20 #include <utils_i18n_types.h>
  21
  22 /**
  23  * @file utils_i18n_udate.h
  24  * @version 0.1
  25  * @brief utils_i18n_udate
  26  */
  27
  28 /**
  29  * @ingroup CAPI_BASE_UTILS_I18N_MODULE
  30  * @defgroup CAPI_BASE_UTILS_I18N_UDATE_MODULE Udate
  31  * @brief The Udate module consists of functions that convert dates and time from their
  32  * internal representations to textual form and back again in a language-independent
  33  * manner.
  34  *
  35  * @section CAPI_BASE_UTILS_I18N_UDATE_MODULE_HEADER Required Header
  36  *  \#include <utils_i18n.h>
  37  *
  38  * @section CAPI_BASE_UTILS_I18N_UDATE_MODULE_OVERVIEW Overview
  39  * @details The Udate module consists of functions that convert dates and time from their
  40  * internal representations to textual form and back again in a language-independent
  41  * manner. Converting from the internal representation (milliseconds since midnight,
  42  * January 1, 1970) to text is known as "formatting," and converting from text to
  43  * milliseconds is known as "parsing". We currently define only one concrete handle
  44  * #i18n_udate_format_h, which can handle pretty much all normal date formatting and parsing
  45  * actions.\n
  46  * The Udate module helps you format and parse dates for any locale. Your code can be
  47  * completely independent of the locale conventions for months, days of the week,
  48  * or even the calendar format: lunar vs. solar.
  49  *
  50  * @section CAPI_BASE_UTILS_I18N_UDATE_MODULE_SAMPLE_CODE_1 Sample Code 1
  51  * @brief Gets the best pattern according to a given locale and formats a current date and time using a locale_udate_format_h
  52  * @code
  53     i18n_udatepg_h pattern_generator = NULL;
  54     char *locale = I18N_ULOCALE_US;
  55
  56     dlog_print(DLOG_INFO, LOG_TAG, "pattern_generator\n");
  57
  58     if(!pattern_generator) {
  59         // create a pattern generator according to a given locale
  60         i18n_udatepg_create(locale, &pattern_generator);
  61     }
  62
  63     if(!pattern_generator) {
  64         dlog_print(DLOG_INFO, LOG_TAG, "i18n_udatepg_create fail");
  65         return ;
  66     }
  67
  68     i18n_uchar bestPattern[64] = {0,};
  69     char bestPatternString[64] = {0,};
  70     int bestPatternLength, len;
  71     const char *custom_format = "yyyy.MM.dd G 'at' HH:mm:ss zzz";
  72     i18n_uchar uch_custom_format[64];
  73     int ret = I18N_ERROR_NONE;
  74
  75     dlog_print(DLOG_INFO, LOG_TAG, "getBestPattern\n");
  76
  77     i18n_ustring_copy_ua(uch_custom_format, custom_format);
  78     len = i18n_ustring_get_length(uch_custom_format);
  79
  80     // gets the best pattern that matches the given custom_format
  81     i18n_udatepg_get_best_pattern(pattern_generator, uch_custom_format, len, bestPattern, 64, &bestPatternLength);
  82
  83     i18n_ustring_copy_au_n(bestPatternString, bestPattern, 64);
  84     // gets "MM/dd/yyyy G h:mm:ss a zzz" as the best pattern
  85     dlog_print(DLOG_INFO, LOG_TAG, "getBestPattern(char[]) : %s \n", bestPatternString);
  86
  87     // closes a generator
  88     i18n_udatepg_destroy(pattern_generator);
  89
  90     i18n_udate_format_h formatter_KR = NULL;
  91     i18n_udate_format_h formatter_LA = NULL;
  92     i18n_udate_format_h formatter_SaoPaulo = NULL;
  93     i18n_uchar formatted[64] = {0,};
  94     char result[64] = {0,};
  95     int formattedLength;
  96     i18n_udate date;
  97     const char *timezone_KR = "GMT+9:00";   // TimeZone for Korea/Seoul
  98     const char *timezone_LA = "America/Los_Angeles";
  99     const char *timezone_SaoPaulo = "America/Sao_Paulo";    // Brazil/East
 100     i18n_uchar utf16_timezone_KR[64] = {0,};
 101     i18n_uchar utf16_timezone_LA[64] = {0,};
 102     i18n_uchar utf16_timezone_SaoPaulo[64] = {0,};
 103
 104     i18n_ustring_copy_ua_n(utf16_timezone_KR, timezone_KR, strlen(timezone_KR));
 105     i18n_ustring_copy_ua_n(utf16_timezone_LA, timezone_LA, strlen(timezone_LA));
 106     i18n_ustring_copy_ua_n(utf16_timezone_SaoPaulo, timezone_SaoPaulo, strlen(timezone_SaoPaulo));
 107
 108     // creates new i18n_udate_format_h to format dates and times
 109     ret = i18n_udate_create(I18N_UDATE_FULL , I18N_UDATE_FULL , locale, utf16_timezone_KR, -1, bestPattern, -1, &formatter_KR);
 110     if ( ret != I18N_ERROR_NONE ) {
 111         dlog_print(DLOG_INFO, LOG_TAG, "i18n_udate_create failed !!! \n");
 112     }
 113     if (!formatter_KR) {
 114         dlog_print(DLOG_INFO, LOG_TAG, "formatter is NULL\n");
 115     }
 116     ret = i18n_udate_create(I18N_UDATE_FULL , I18N_UDATE_FULL , locale, utf16_timezone_LA, -1, bestPattern, -1, &formatter_LA);
 117     if ( ret != I18N_ERROR_NONE ) {
 118         dlog_print(DLOG_INFO, LOG_TAG, "i18n_udate_create failed !!! \n");
 119     }
 120     if (!formatter_LA) {
 121         dlog_print(DLOG_INFO, LOG_TAG, "formatter is NULL\n");
 122     }
 123     ret = i18n_udate_create(I18N_UDATE_PATTERN , I18N_UDATE_PATTERN , locale, utf16_timezone_SaoPaulo, -1, bestPattern, -1, &formatter_SaoPaulo);
 124     if ( ret != I18N_ERROR_NONE ) {
 125         dlog_print(DLOG_INFO, LOG_TAG, "i18n_udate_create failed !!! \n");
 126     }
 127     if (!formatter_LA) {
 128         dlog_print(DLOG_INFO, LOG_TAG, "formatter is NULL\n");
 129     }
 130
 131     dlog_print(DLOG_INFO, LOG_TAG, "i18n_udate_format_date\n");
 132
 133     // gets the current date and time
 134     i18n_ucalendar_get_now(&date);
 135
 136     // formats a date using i18n_udate_format_h
 137     i18n_udate_format_date(formatter_KR, date, formatted, 64, NULL, &formattedLength);
 138     i18n_ustring_copy_au_n(result, formatted, 64);
 139     //ex) KOREA/Seoul - Current date : Wednesday, June 18, 2014 1:34:54 PM GMT+09:00
 140     dlog_print(DLOG_INFO, LOG_TAG, "KOREA/Seoul - Current date : %s\n",result);
 141
 142     // formats a date using i18n_udate_format
 143     i18n_udate_format_date(formatter_LA, date, formatted, 64, NULL, &formattedLength);
 144     i18n_ustring_copy_au_n(result, formatted, 64);
 145     //ex) America/LOS Angeles - Current date : Tuesday, June 17, 2014 9:34:54 PM Pacific Daylight Time
 146     dlog_print(DLOG_INFO, LOG_TAG, "America/LOS Angeles - Current date : %s\n",result);
 147
 148     // formats a date using i18n_udate_format_h
 149     i18n_udate_format_date(formatter_SaoPaulo, date, formatted, 64, NULL, &formattedLength);
 150     i18n_ustring_copy_au_n(result, formatted, 64);
 151     //ex) Brazil/Sao Paulo - Current date : 6 18, 2014 AD, 1:34:54 PM GMT-2
 152     dlog_print(DLOG_INFO, LOG_TAG, "Brazil/Sao Paulo - Current date : %s\n",result);
 153
 154     dlog_print(DLOG_INFO, LOG_TAG, "i18n_udate_destroy\n");
 155     // destroy an i18n_udate_format_h
 156     i18n_udate_destroy(formatter_KR);
 157     i18n_udate_destroy(formatter_LA);
 158     i18n_udate_destroy(formatter_SaoPaulo);
 159  * @endcode
 160  */
 161
 162 #ifdef __cplusplus
 163 extern "C" {
 164 #endif
 165
 166 /**
 167  * @addtogroup CAPI_BASE_UTILS_I18N_UDATE_MODULE
 168  * @{
 169  */
 170
 171 /**
 172  * @brief Creates a new #i18n_udate_format_h for formatting and parsing dates and times.
 173  * @details A #i18n_udate_format_h may be used to format dates in calls to {@link i18n_udate_create()}.
 174  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 175  * @remarks Must release @a format using i18n_udate_destroy().
 176  *
 177  * @param[in] time_style The style used to format times\n One of #I18N_UDATE_FULL, #I18N_UDATE_LONG,
 178  * #I18N_UDATE_MEDIUM, #I18N_UDATE_SHORT, #I18N_UDATE_DEFAULT, or #I18N_UDATE_NONE (relative time styles
 179  * are not currently supported).
 180  * @param[in] date_style The style used to format dates\n One of #I18N_UDATE_FULL, #I18N_UDATE_LONG,
 181  * #I18N_UDATE_MEDIUM, #I18N_UDATE_SHORT, #I18N_UDATE_DEFAULT, #I18N_UDATE_RELATIVE, #I18N_UDATE_LONG_RELATIVE,
 182  * #I18N_UDATE_MEDIUM_RELATIVE, #I18N_UDATE_SHORT_RELATIVE, #I18N_UDATE_PATTERN, or #I18N_UDATE_NONE
 183  * @param[in] locale The locale specifying the formatting conventions.
 184  * @param[in] tz_id A timezone ID specifying the timezone to use\n  If @c 0, use the default timezone.
 185  * @param[in] tz_id_len The length of @a tz_id, otherwise @c -1 if NULL-terminated.
 186  * @param[in] pattern A pattern specifying the format to use. The pattern is generated by Udatepg module.
 187  * When the pattern parameter is used, pass in #I18N_UDATE_PATTERN for both time_style and date_style.
 188  * @param[in] pattern_len The number of characters in the pattern, or otherwise @c -1 if NULL-terminated.
 189  * @param[out] format A pointer to an #i18n_udate_format_h to use for formatting dates and times, otherwise @c 0 if an error occurs.
 190  *
 191  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 192  * @retval #I18N_ERROR_NONE Successful
 193  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 194  */
 195 int i18n_udate_create ( i18n_udate_format_style_e time_style, i18n_udate_format_style_e date_style, const char *locale, const i18n_uchar *tz_id, int32_t tz_id_len, const i18n_uchar *pattern, int pattern_len, i18n_udate_format_h *format );
 196
 197 /**
 198  * @brief Destroys an #i18n_udate_format_h.
 199  * @details Once destroyed, an #i18n_udate_format_h may no longer be used.
 200  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 201  *
 202  * @param[in] format The formatter to destroy.
 203  *
 204  * @retval #I18N_ERROR_NONE Successful
 205  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 206  */
 207 int i18n_udate_destroy ( i18n_udate_format_h format );
 208
 209 /**
 210  * @brief Formats a date using an #i18n_udate_format_h.
 211  * @details The date will be formatted using the conventions specified in {@link i18n_udate_create()}
 212  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 213  *
 214  * @param[in] format The formatter to use.
 215  * @param[in] date_to_format The date to format.
 216  * @param[out] result A pointer to a buffer to receive the formatted number.
 217  * @param[in] result_len The maximum size of the result.
 218  * @param[in] pos A pointer to an i18n_ufield_position\n
 219  * On input, position->field is read\n
 220  * On output, position->beginIndex and position->endIndex indicate
 221  * the beginning and ending indices of field number position->field, if such a field exists\n
 222  * This parameter may be @c NULL, in which case no field
 223  * position data is returned.
 224  * @param[out] buf_size_needed The total buffer size needed\n
 225  * If greater than @a result_len, the output was truncated.
 226  *
 227  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 228  * @retval #I18N_ERROR_NONE Successful
 229  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 230  */
 231 int i18n_udate_format_date ( const i18n_udate_format_h format, i18n_udate date_to_format, i18n_uchar *result, int32_t result_len, i18n_ufield_position_h pos, int32_t *buf_size_needed );
 232
 233
 234 // Newly Added APIs
 235
 236 /**
 237  * @brief Maps from an #i18n_udate_format_h to the corresponding #i18n_ucalendar_date_fields_e.
 238  * @details Note: since the mapping is many-to-one, there is no inverse mapping.
 239  * @since_tizen 2.3.1
 240  *
 241  * @param[in] field The #i18n_udate_format_h to map.
 242  *     #I18N_UDATE_FORMAT_TIMEZONE_LOCALIZED_GMT_OFFSET_FIELD, #I18N_UDATE_FORMAT_TIMEZONE_ISO_FIELD,
 243  *     #I18N_UDATE_FORMAT_TIMEZONE_ISO_LOCAL_FIELD and #I18N_UDATE_FORMAT_FIELD_COUNT are not supported.
 244  * @param[out] date_field_type A pointer to the #i18n_ucalendar_date_fields_e.
 245  *
 246  * @return Error code.
 247  * @retval #I18N_ERROR_NONE Successful
 248  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 249  */
 250 int i18n_udate_to_calendar_date_field ( i18n_udate_format_field_e field, i18n_ucalendar_date_fields_e *date_field_type );
 251
 252 /**
 253  * @brief Creates a copy of an #i18n_udate_format_h.
 254  * @details This function performs a deep copy.
 255  * @since_tizen 2.3.1
 256  *
 257  * @param[in] format     The format to copy.
 258  * @param[out] format_clone A pointer to clone of @c format.
 259  *
 260  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 261  * @retval #I18N_ERROR_NONE Successful
 262  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 263  */
 264 int i18n_udate_clone ( const i18n_udate_format_h format, i18n_udate_format_h *format_clone );
 265
 266 /**
 267  * @brief Parses a string into an date/time using an #i18n_udate_format_h.
 268  * @details The date will be parsed using the conventions specified in {@link i18n_udate_create()}.<br>
 269  *          Note that the normal date formats associated with some calendars - such as the Chinese lunar calendar - do not specify enough fields to enable dates to be parsed unambiguously.
 270  *          In the case of the Chinese lunar calendar, while the year within the current 60-year cycle is specified,
 271  *          the number of such cycles since the start date of the calendar (in the #I18N_UCALENDAR_ERA field of the i18n_ucalendar_h) is not normally part of the format,
 272  *          and parsing may assume the wrong era.
 273  *          For such cases it is recommended that clients parse using i18n_udate_parse_calendar() with the calendar passed in set to the current date,
 274  *          or to a date within the era/cycle that should be assumed if absent in the format.
 275  * @since_tizen 2.3.1
 276  *
 277  * @param[in] format      The formatter to use.
 278  * @param[in] text        The text to parse.
 279  * @param[in] text_length The length of text, or -1 if NULL-terminated.
 280  * @param[in] parse_pos   If not 0, on input a pointer to an integer specifying the offset at which to begin parsing.
 281  *                        If not 0, on output the offset at which parsing ended.
 282  * @param[out] parsed_date A pointer to the value of the parsed date/time.
 283  *
 284  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 285  * @retval #I18N_ERROR_NONE Successful
 286  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 287  *
 288  * @see i18n_udate_format_date()
 289  */
 290 int i18n_udate_parse ( const i18n_udate_format_h format, const i18n_uchar *text, int32_t text_length, int32_t *parse_pos, i18n_udate *parsed_date );
 291
 292 /**
 293  * @brief Parses a string into an date/time using an #i18n_udate_format_h.
 294  * @details The date will be parsed using the conventions specified in {@link i18n_udate_create()}.
 295  * @since_tizen 2.3.1
 296  *
 297  * @param[in] format         The formatter to use.
 298  * @param[in,out] calendar   A pointer to calendar set on input to the date and time to be used for missing values in the date/time string being parsed,
 299  *                           and set on output to the parsed date/time.
 300  *                           When the calendar type is different from the internal calendar held by the #i18n_udate_format_h instance,
 301  *                           the internal calendar will be cloned to a work calendar set to the same milliseconds and time zone as this calendar parameter,
 302  *                           field values will be parsed based on the work calendar, then the result (milliseconds and time zone) will be set in this calendar.
 303  * @param[in] text           The text to parse.
 304  * @param[in] text_length    The length of text, or -1 if NULL-terminated.
 305  * @param[in] parse_pos      If not 0, on input a pointer to an integer specifying the offset at which to begin parsing.
 306  *                           If not 0, on output the offset at which parsing ended.
 307  *
 308  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 309  * @retval #I18N_ERROR_NONE Successful
 310  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 311  *
 312  * @see i18n_udate_format_date()
 313  */
 314 int i18n_udate_parse_calendar (const i18n_udate_format_h format, i18n_ucalendar_h *calendar, const i18n_uchar *text,
 315         int32_t text_length, int32_t *parse_pos );
 316
 317 /**
 318  * @brief Determines if an #i18n_udate_format_h will perform lenient parsing.
 319  * @details With lenient parsing, the parser may use heuristics to interpret inputs that do not precisely match the pattern.
 320  *          With strict parsing, inputs must match the pattern.
 321  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
 322  * @since_tizen 2.3.1
 323  *
 324  * @param[in] format     The #i18n_udate_format_h to query.
 325  *
 326  * @return true if format is set to perform lenient parsing, false otherwise.
 327  *
 328  * @exception #I18N_ERROR_NONE Successful
 329  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 330  *
 331  * @see i18n_udate_set_lenient()
 332  */
 333 i18n_ubool i18n_udate_is_lenient ( const i18n_udate_format_h format );
 334
 335 /**
 336  * @brief Specifies whether an #i18n_udate_format_h will perform lenient parsing.
 337  * @details With lenient parsing, the parser may use heuristics to interpret inputs that do not precisely match the pattern.
 338  *          With strict parsing, inputs must match the pattern.
 339  * @since_tizen 2.3.1
 340  *
 341  * @param[in] format      The #i18n_udate_format_h to set.
 342  * @param[in] is_lenient true if fmt should perform lenient parsing, false otherwise.
 343  *
 344  * @return Error code.
 345  * @retval #I18N_ERROR_NONE Successful
 346  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 347  *
 348  * @see i18n_udate_is_lenient()
 349  */
 350 int i18n_udate_set_lenient ( i18n_udate_format_h format, i18n_ubool is_lenient );
 351
 352 /**
 353  * @brief Gets the #i18n_ucalendar_h associated with an #i18n_udate_format_h.
 354  * @details An #i18n_udate_format_h uses an #i18n_ucalendar_h to convert a raw value to, for example, the day of the week.
 355  * @since_tizen 2.3.1
 356  *
 357  * @param[in] format        The #i18n_udate_format_h to query.
 358  * @param[out] calendar     A pointer to the #i18n_ucalendar_h used by format.
 359  *
 360  * @return Error code.
 361  * @exception #I18N_ERROR_NONE Successful
 362  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 363  *
 364  * @see i18n_udate_set_calendar()
 365  */
 366 int i18n_udate_get_calendar ( const i18n_udate_format_h format, i18n_ucalendar_h *calendar);
 367
 368 /**
 369  * @brief Sets the #i18n_ucalendar_h associated with an #i18n_udate_format_h.
 370  * @details An #i18n_udate_format_h uses an #i18n_ucalendar_h to convert a raw value to, for example, the day of the week.
 371  * @since_tizen 2.3.1
 372  *
 373  * @param[in] format             The #i18n_udate_format_h.
 374  * @param[in] calendar_to_set    An #i18n_ucalendar_h to be used by the format.
 375  *
 376  * @return Error code.
 377  * @retval #I18N_ERROR_NONE Successful
 378  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 379  *
 380  * @see i18n_udate_get_calendar()
 381  */
 382 int i18n_udate_set_calendar ( i18n_udate_format_h format, const i18n_ucalendar_h calendar_to_set );
 383
 384 /**
 385  * @brief Gets the #i18n_unumber_format_h associated with an #i18n_udate_format_h.
 386  * @details An #i18n_udate_format_h uses an #i18n_unumber_format_h to format numbers within a date, for example the day number.
 387  * @since_tizen 2.3.1
 388  *
 389  * @param[in] format            The formatter to query.
 390  * @param[out] number_format    A pointer to the #i18n_unumber_format_h used by @a format to format numbers.
 391  *
 392  * @return Error code.
 393  * @exception #I18N_ERROR_NONE Successful
 394  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 395  *
 396  * @see i18n_udate_set_number_format()
 397  */
 398 int i18n_udate_get_number_format ( const i18n_udate_format_h format, i18n_unumber_format_h *number_format );
 399
 400 /**
 401  * @brief Sets the #i18n_unumber_format_h associated with an #i18n_udate_format_h.
 402  * @details An #i18n_udate_format_h uses an #i18n_unumber_format_h to format numbers within a date, for example the day number.
 403  * @since_tizen 2.3.1
 404  *
 405  * @param[in] format                 The #i18n_udate_format_h to set.
 406  * @param[in] number_format_to_set   An #i18n_unumber_format_h to be used by @a format to format numbers.
 407  *
 408  * @return Error code.
 409  * @retval #I18N_ERROR_NONE Successful
 410  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 411  *
 412  * @see i18n_udate_get_number_format()
 413  */
 414 int i18n_udate_set_number_format ( i18n_udate_format_h format, const i18n_unumber_format_h number_format_to_set );
 415
 416 /**
 417  * @brief Gets a locale for which date/time formatting patterns are available.
 418  * @details An #i18n_udate_format_h in a locale returned by this function will perform the correct formatting and parsing for the locale.
 419  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
 420  * @since_tizen 2.3.1
 421  *
 422  * @param[in] locale_index     The index of the desired locale.
 423  *
 424  * @return A locale for which date/time formatting patterns are available, or 0 if none.
 425  * @exception #I18N_ERROR_NONE Successful
 426  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 427
 428  * @see i18n_udate_count_available()
 429  */
 430 const char *i18n_udate_get_available ( int32_t locale_index );
 431
 432 /**
 433  * @brief Determines how many locales have date/time formatting patterns available.
 434  * @details This function is the most useful for determining the loop ending condition for calls to {@link #i18n_udate_get_available()}.
 435  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
 436  * @since_tizen 2.3.1
 437  *
 438  * @return The number of locales for which date/time formatting patterns are available.
 439  *
 440  * @exception #I18N_ERROR_NONE Successful
 441  *
 442  * @see i18n_udate_get_available()
 443  */
 444 int32_t i18n_udate_count_available ( void );
 445
 446 /**
 447  * @brief Gets the year relative to which all 2-digit years are interpreted.
 448  * @details For example, if the 2-digit start year is 2100, the year 99 will be interpreted as 2199.
 449  *
 450  * @since_tizen 2.3.1
 451  *
 452  * @param[in] format     The #i18n_udate_format_h to get.
 453  * @param[out] year A pointer to the year relative to which all 2-digit years are interpreted.
 454  *
 455  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 456  * @retval #I18N_ERROR_NONE Successful
 457  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 458  *
 459  * @see i18n_udate_set_2digit_year_start()
 460  */
 461 int i18n_udate_get_2digit_year_start ( const i18n_udate_format_h format, i18n_udate *year );
 462
 463 /**
 464  * @brief Sets the year relative to which all 2-digit years will be interpreted.
 465  * @details For example, if the 2-digit start year is 2100, the year 99 will be interpreted as 2199.
 466  *
 467  * @since_tizen 2.3.1
 468  *
 469  * @param[in] format  The #i18n_udate_format_h to map.
 470  * @param[in] date    The year relative to which all 2-digit years will be interpreted.
 471  *
 472  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 473  * @retval #I18N_ERROR_NONE Successful
 474  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 475  *
 476  * @see i18n_udate_get_2digit_year_start()
 477  */
 478 int i18n_udate_set_2digit_year_start ( i18n_udate_format_h format, i18n_udate date );
 479
 480 /**
 481  * @brief Extracts the pattern from an #i18n_udate_format_h.
 482  * @details The pattern will follow the pattern syntax rules.
 483  * @remarks The specific error code can be obtained using the get_last_result() method.
 484  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 485  * @since_tizen 2.3.1
 486  *
 487  * @param[in] format         The #i18n_udate_format_h to query.
 488  * @param[in] localized      true if the pattern should be localized, false otherwise.
 489  * @param[out] result        A pointer to a buffer to receive the pattern.
 490  * @param[in] result_length  The maximum size of result.
 491  *
 492  * @return The total buffer size needed; if greater than result_length, the output was truncated.
 493  *
 494  * @exception #I18N_ERROR_NONE Successful
 495  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 496  *
 497  * @see i18n_udate_apply_pattern()
 498  */
 499 int32_t i18n_udate_to_pattern ( const i18n_udate_format_h format, i18n_ubool localized, i18n_uchar *result,
 500         int32_t result_length );
 501
 502 /**
 503  * @brief Sets the pattern used by an #i18n_udate_format_h.
 504  * @details The pattern should follow the pattern syntax rules.
 505  * @since_tizen 2.3.1
 506  *
 507  * @param[in] format         The #i18n_udate_format_h to set.
 508  * @param[in] localized      true if the pattern is localized, false otherwise.
 509  * @param[in] pattern        The new pattern.
 510  * @param[in] pattern_length The length of pattern, or -1 if NULL-terminated.
 511  *
 512  * @return Error code.
 513  * @retval #I18N_ERROR_NONE Successful
 514  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 515  *
 516  * @see i18n_udate_to_pattern()
 517  */
 518 int i18n_udate_apply_pattern ( i18n_udate_format_h format, i18n_ubool localized, const i18n_uchar *pattern,
 519         int32_t pattern_length );
 520
 521 /**
 522  * @brief Gets the symbols associated with an #i18n_udate_format_h.
 523  * @details The symbols are what an #i18n_udate_format_h uses to represent locale-specific data, for example month or day names.
 524  * @remarks The specific error code can be obtained using the get_last_result() method.
 525  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 526  * @since_tizen 2.3.1
 527  *
 528  * @param[in] format        The #i18n_udate_format_h to query.
 529  * @param[in] type          The type of symbols to get.
 530  *                          All the types defined in the #i18n_udate_format_symbol_type_e enumeration are supported.
 531  * @param[in] symbol_index  The desired symbol of type type.
 532  * @param[out] result       A pointer to a buffer to receive the pattern.
 533  * @param[in] result_length The maximum size of the result buffer.
 534  *
 535  * @return The total buffer size needed; if greater than result_length, the output was truncated.
 536  *
 537  * @exception #I18N_ERROR_NONE Successful
 538  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 539  *
 540  * @see i18n_udate_count_symbols()
 541  * @see #i18n_udate_set_symbols()
 542  */
 543 int32_t i18n_udate_get_symbols ( const i18n_udate_format_h format, i18n_udate_format_symbol_type_e type, int32_t symbol_index,
 544         i18n_uchar *result, int32_t result_length );
 545
 546 /**
 547  * @brief Counts the number of particular symbols for an #i18n_udate_format_h.
 548  * @details This function is most useful for determining the loop termination condition for calls to {@link #i18n_udate_get_symbols()}.
 549  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
 550  * @since_tizen 2.3.1
 551  *
 552  * @param[in] format The #i18n_udate_format_h to query.
 553  * @param[in] type   The type of symbols to count.
 554  *                   If wrong type is passed, 0 will be returned.
 555  *
 556  * @return The number of symbols of type @a type.
 557  *
 558  * @exception #I18N_ERROR_NONE Successful
 559  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 560  *
 561  * @see i18n_udate_get_symbols()
 562  * @see #i18n_udate_set_symbols()
 563  */
 564 int32_t i18n_udate_count_symbols ( const i18n_udate_format_h format, i18n_udate_format_symbol_type_e type );
 565
 566 /**
 567  * @brief Sets the symbols associated with an #i18n_udate_format_h.
 568  * @details The symbols are what an #i18n_udate_format_h uses to represent locale-specific data, for example month or day names.
 569  *
 570  * @since_tizen 2.3.1
 571  *
 572  * @param[in] format       The #i18n_udate_format_h to set.
 573  * @param[in] type         The type of symbols to set.
 574  *                         All the types defined in the #i18n_udate_format_symbol_type_e enumeration are supported.
 575  *                         If a type not defined in the enumeration is passed, then the #I18N_ERROR_NOT_SUPPORTED error is returned.
 576  * @param[in] symbol_index The index of the symbol to set of type type.
 577  * @param[in] value        The new value.
 578  * @param[in] value_length The length of @a value, or @c -1 if NULL-terminated.
 579  *
 580  * @return Error code. Error codes not listed below are described in the #i18n_error_code_e enumeration.
 581  * @retval #I18N_ERROR_NONE Successful
 582  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 583  *
 584  * @see i18n_udate_count_symbols()
 585  * @see #i18n_udate_get_symbols()
 586  */
 587 int i18n_udate_set_symbols ( i18n_udate_format_h format, i18n_udate_format_symbol_type_e type, int32_t symbol_index,
 588         i18n_uchar *value, int32_t value_length );
 589
 590 /**
 591  * @brief Gets the locale for this date format object.
 592  * @details You can choose between valid and actual locale.
 593  * @remarks The specific error code can be obtained using the get_last_result() method.
 594  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 595  * @since_tizen 2.3.1
 596  *
 597  * @param[in] format  The #i18n_udate_format_h to get the locale from.
 598  * @param[in] type    The type of the locale we're looking for (valid or actual).
 599  *
 600  * @return The locale name.
 601  *
 602  * @exception #I18N_ERROR_NONE Successful
 603  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 604  */
 605 const char * i18n_udate_get_locale_by_type ( const i18n_udate_format_h format, i18n_ulocale_data_locale_type_e type );
 606
 607 /**
 608  * @brief Sets a particular #i18n_udisplay_context_e value in the formatter, such as #I18N_UDISPLAY_CONTEXT_CAPITALIZATION_FOR_STANDALONE.
 609  * @remarks I18N_UDISPLAY_CONTEXT_STANDARD_NAMES and I18N_UDISPLAY_CONTEXT_DIALECT_NAMES are not supported.
 610  *
 611  * @since_tizen 2.3.1
 612  *
 613  * @param[in]  format The #i18n_udate_format_h to set a #i18n_udisplay_context_e value.
 614  * @param[in]  value  The #i18n_udisplay_context_e value to set.
 615  *
 616  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 617  * @retval #I18N_ERROR_NONE Successful
 618  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 619  */
 620 int i18n_udate_set_context ( i18n_udate_format_h format, i18n_udisplay_context_e value );
 621
 622
 623 /**
 624  * @}
 625  * @}
 626  */
 627
 628 #ifdef __cplusplus
 629 }
 630 #endif
 631
 632 #endif  /* __UTILS_I18N_UDATE_H__*/