Tizen Native API  5.5

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.

Required Header

#include <utils_i18n.h>

Overview

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. Once that is done, a query can be made using a "skeleton", which is a pattern that just includes the desired fields and lengths(Since Tizen 3.0 constants for skeletons are available - see I18N_UDATE_YEAR and many, many others). The generator will return the "best fit" pattern corresponding to that skeleton.
The main method people will use is i18n_udatepg_get_best_pattern(), since normally i18n_udatepg_h is pre-built with data from a particular locale. However, generators can be built directly from other data as well.

All input handlers must not be NULL.

Sample Code 1

Gets the best pattern according to a given locale and formats a current date and time using an i18n_udate_format_h

    i18n_udatepg_h pattern_generator = NULL;
    char *locale = I18N_ULOCALE_US;

    dlog_print(DLOG_INFO, LOG_TAG, "pattern_generator\n");

    if(!pattern_generator) {
        // create a pattern generator according to a given locale
        i18n_udatepg_create(locale, &pattern_generator);
    }

    if(!pattern_generator) {
        dlog_print(DLOG_INFO, LOG_TAG, "i18n_udatepg_create fail");
        return ;
    }

    i18n_uchar bestPattern[64] = {0,};
    char bestPatternString[64] = {0,};
    int bestPatternLength, len;
    const char *custom_format = "yyyy.MM.dd G 'at' HH:mm:ss zzz";
    i18n_uchar uch_custom_format[64];
    int ret = I18N_ERROR_NONE;

    dlog_print(DLOG_INFO, LOG_TAG, "getBestPattern\n");

    i18n_ustring_copy_ua(uch_custom_format, custom_format);
    len = i18n_ustring_get_length(uch_custom_format);

    // gets the best pattern that matches the given custom_format
    i18n_udatepg_get_best_pattern(pattern_generator, uch_custom_format, len, bestPattern, 64, &bestPatternLength);

    i18n_ustring_copy_au_n(bestPatternString, bestPattern, 64);
    // gets "MM/dd/yyyy G h:mm:ss a zzz" as the best pattern
    dlog_print(DLOG_INFO, LOG_TAG, "getBestPattern(char[]) : %s \n", bestPatternString);

    // closes a generator
    i18n_udatepg_destroy(pattern_generator);

    i18n_udate_format_h formatter_KR = NULL;
    i18n_udate_format_h formatter_LA = NULL;
    i18n_udate_format_h formatter_SaoPaulo = NULL;
    i18n_uchar formatted[64] = {0,};
    char result[64] = {0,};
    int formattedLength;
    i18n_udate date;
    const char *timezone_KR = "GMT+9:00";   // TimeZone for Korea/Seoul
    const char *timezone_LA = "America/Los_Angeles";
    const char *timezone_SaoPaulo = "America/Sao_Paulo";    // Brazil/East
    i18n_uchar utf16_timezone_KR[64] = {0,};
    i18n_uchar utf16_timezone_LA[64] = {0,};
    i18n_uchar utf16_timezone_SaoPaulo[64] = {0,};

    i18n_ustring_copy_ua_n(utf16_timezone_KR, timezone_KR, strlen(timezone_KR));
    i18n_ustring_copy_ua_n(utf16_timezone_LA, timezone_LA, strlen(timezone_LA));
    i18n_ustring_copy_ua_n(utf16_timezone_SaoPaulo, timezone_SaoPaulo, strlen(timezone_SaoPaulo));

    // creates new i18n_udate_format to format dates and times
    ret = i18n_udate_create(I18N_UDATE_FULL , I18N_UDATE_FULL , locale, utf16_timezone_KR, -1, bestPattern, -1, &formatter_KR);
    if (ret != I18N_ERROR_NONE) {
        dlog_print(DLOG_INFO, LOG_TAG, "i18n_udate_create failed !!! \n");
    }
    if (!formatter_KR) {
        dlog_print(DLOG_INFO, LOG_TAG, "formatter is NULL\n");
    }
    ret = i18n_udate_create(I18N_UDATE_FULL , I18N_UDATE_FULL , locale, utf16_timezone_LA, -1, bestPattern, -1, &formatter_LA);
    if (ret != I18N_ERROR_NONE) {
        dlog_print(DLOG_INFO, LOG_TAG, "i18n_udate_create failed !!! \n");
    }
    if (!formatter_LA) {
        dlog_print(DLOG_INFO, LOG_TAG, "formatter is NULL\n");
    }
    ret = i18n_udate_create(I18N_UDATE_PATTERN , I18N_UDATE_PATTERN , locale, utf16_timezone_SaoPaulo, -1, bestPattern, -1, &formatter_SaoPaulo);
    if (ret != I18N_ERROR_NONE) {
        dlog_print(DLOG_INFO, LOG_TAG, "i18n_udate_create failed !!! \n");
    }
    if (!formatter_SaoPaulo) {
        dlog_print(DLOG_INFO, LOG_TAG, "formatter is NULL\n");
    }

    dlog_print(DLOG_INFO, LOG_TAG, "i18n_udate_format_date\n");

    // gets the current date and time
    i18n_ucalendar_get_now(&date);

    // formats a date using i18n_udate_format
    i18n_udate_format_date(formatter_KR, date, formatted, 64, NULL, &formattedLength);
    i18n_ustring_copy_au_n(result, formatted, 64);
    //ex) KOREA/Seoul - Current date : Wednesday, June 18, 2014 1:34:54 PM GMT+09:00
    dlog_print(DLOG_INFO, LOG_TAG, "KOREA/Seoul - Current date : %s\n",result);

    // formats a date using i18n_udate_format
    i18n_udate_format_date(formatter_LA, date, formatted, 64, NULL, &formattedLength);
    i18n_ustring_copy_au_n(result, formatted, 64);
    //ex) America/LOS Angeles - Current date : Tuesday, June 17, 2014 9:34:54 PM Pacific Daylight Time
    dlog_print(DLOG_INFO, LOG_TAG, "America/LOS Angeles - Current date : %s\n",result);

    // formats a date using i18n_udate_format
    i18n_udate_format_date(formatter_SaoPaulo, date, formatted, 64, NULL, &formattedLength);
    i18n_ustring_copy_au_n(result, formatted, 64);
    //ex) Brazil/Sao Paulo - Current date : 6 18, 2014 AD, 1:34:54 PM GMT-2
    dlog_print(DLOG_INFO, LOG_TAG, "Brazil/Sao Paulo - Current date : %s\n",result);

    dlog_print(DLOG_INFO, LOG_TAG, "i18n_udate_destroy\n");
    // destroy an #i18n_udate_format_h
    i18n_udate_destroy(formatter_KR);
    i18n_udate_destroy(formatter_LA);
    i18n_udate_destroy(formatter_SaoPaulo);

Functions

int i18n_udatepg_create (const char *locale, i18n_udatepg_h *dtpg)
 Opens a generator according to a given locale.
int i18n_udatepg_destroy (i18n_udatepg_h dtpg)
 Destroys a generator.
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)
 Gets the best pattern matching the input skeleton.
int i18n_udatepg_create_empty (i18n_udatepg_h *dtpg)
 Creates an empty generator, to be constructed with i18n_udatepg_add_pattern() etc.
int i18n_udatepg_clone (const i18n_udatepg_h dtpg, i18n_udatepg_h *dtpg_clone)
 Creates a copy of a generator.
int32_t i18n_udatepg_get_best_pattern_with_options (i18n_udatepg_h dtpg, const i18n_uchar *skeleton, int32_t length, i18n_udatepg_date_time_pattern_match_options_e options, i18n_uchar *best_pattern, int32_t capacity)
 Gets the best pattern matching the input skeleton.
int32_t i18n_udatepg_get_skeleton (i18n_udatepg_h dtpg, const i18n_uchar *pattern, int32_t length, i18n_uchar *skeleton, int32_t capacity)
 Gets a unique skeleton from a given pattern. For example, both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd".
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)
 Gets a unique base skeleton from a given pattern.
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)
 Adds a pattern to the generator.
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)
 An append_item_format is a pattern used to append a field if there is no good match.
const i18n_uchari18n_udatepg_get_append_item_format (const i18n_udatepg_h dtpg, i18n_udatepg_date_time_pattern_field_e field, int32_t *pattern_length)
 Getter corresponding to i18n_udatepg_set_append_item_format().
int i18n_udatepg_set_append_item_name (i18n_udatepg_h dtpg, i18n_udatepg_date_time_pattern_field_e field, const i18n_uchar *value, int32_t length)
 Sets the name of field, e.g. "era" in English for ERA.
const i18n_uchari18n_udatepg_get_append_item_name (const i18n_udatepg_h dtpg, i18n_udatepg_date_time_pattern_field_e field, int32_t *pattern_length)
 Getter corresponding to i18n_udatepg_set_append_item_name().
int i18n_udatepg_set_date_time_format (const i18n_udatepg_h dtpg, const i18n_uchar *date_time_format, int32_t length)
 The date time format is a message format pattern used to compose date and time patterns.
const i18n_uchari18n_udatepg_get_date_time_format (const i18n_udatepg_h dtpg, int32_t *pattern_length)
 Getter corresponding to i18n_udatepg_set_date_time_format().
int i18n_udatepg_set_decimal (i18n_udatepg_h dtpg, const i18n_uchar *decimal, int32_t length)
 The decimal value is used in formatting fractions of seconds.
const i18n_uchari18n_udatepg_get_decimal (const i18n_udatepg_h dtpg, int32_t *pattern_length)
 Getter corresponding to i18n_udatepg_set_decimal().
int32_t i18n_udatepg_replace_field_types (i18n_udatepg_h dtpg, const i18n_uchar *pattern, int32_t pattern_length, const i18n_uchar *skeleton, int32_t skeleton_length, i18n_uchar *dest, int32_t dest_capacity)
 Adjusts the field types (width and subtype) of a pattern to match what is in a skeleton.
int32_t i18n_udatepg_replace_field_types_with_options (i18n_udatepg_h dtpg, const i18n_uchar *pattern, int32_t pattern_length, const i18n_uchar *skeleton, int32_t skeleton_length, i18n_udatepg_date_time_pattern_match_options_e options, i18n_uchar *dest, int32_t dest_capacity)
 Adjusts the field types (width and subtype) of a pattern to match what is in a skeleton.
int i18n_udatepg_skeletons_create (const i18n_udatepg_h dtpg, i18n_uenumeration_h *enumeration)
 Creates an i18n_uenumeration_h for list of all the skeletons in canonical form.
int i18n_udatepg_base_skeletons_create (const i18n_udatepg_h dtpg, i18n_uenumeration_h *enumeration)
 Creates an i18n_uenumeration_h for list of all the base skeletons in canonical form.
const i18n_uchari18n_udatepg_get_pattern_for_skeleton (const i18n_udatepg_h dtpg, const i18n_uchar *skeleton, int32_t skeleton_length, int32_t *pattern_length)
 Gets the pattern corresponding to a given skeleton.

Typedefs

typedef void * i18n_udatepg_h
 Handle for a date/time pattern generator object.

Typedef Documentation

typedef void* i18n_udatepg_h

Handle for a date/time pattern generator object.

Since :
2.3

Enumeration Type Documentation

Enumeration for status return values from i18n_udatepg_add_pattern().

Since :
2.3.1
Enumerator:
I18N_UDATEPG_NO_CONFLICT 

No conflict

I18N_UDATEPG_BASE_CONFLICT 

Base conflict

I18N_UDATEPG_CONFLICT 

Conflict

I18N_UDATEPG_CONFLICT_COUNT 

Number of status return values

Enumeration for field number constants for i18n_udatepg_get_append_item_format() and similar functions.

These constants are separate from i18n_udate_format_field_e despite semantic overlap because some fields are merged for the date/time pattern generator.

Since :
2.3.1
Enumerator:
I18N_UDATEPG_ERA_FIELD 

Era field

I18N_UDATEPG_YEAR_FIELD 

Year field

I18N_UDATEPG_QUARTER_FIELD 

Quarter field

I18N_UDATEPG_MONTH_FIELD 

Month field

I18N_UDATEPG_WEEK_OF_YEAR_FIELD 

Week of year field

I18N_UDATEPG_WEEK_OF_MONTH_FIELD 

Week of month field

I18N_UDATEPG_WEEKDAY_FIELD 

Weekday field

I18N_UDATEPG_DAY_OF_YEAR_FIELD 

Day of year field

I18N_UDATEPG_DAY_OF_WEEK_IN_MONTH_FIELD 

Day of week in month field

I18N_UDATEPG_DAY_FIELD 

Day field

I18N_UDATEPG_DAYPERIOD_FIELD 

Day period field

I18N_UDATEPG_HOUR_FIELD 

Hour field

I18N_UDATEPG_MINUTE_FIELD 

Minute field

I18N_UDATEPG_SECOND_FIELD 

Second field

I18N_UDATEPG_FRACTIONAL_SECOND_FIELD 

Fractional second field

I18N_UDATEPG_ZONE_FIELD 

Zone field

I18N_UDATEPG_FIELD_COUNT 

Field count

Enumeration for masks to control forcing the length of specified fields in the returned pattern to match those in the skeleton (when this would not happen otherwise).
.

These may be combined to force the length of multiple fields. Used with i18n_udatepg_get_best_pattern_with_options(), i18n_udatepg_replace_field_types_with_options().

Since :
2.3.1
Enumerator:
I18N_UDATEPG_MATCH_NO_OPTIONS 

No options

I18N_UDATEPG_MATCH_HOUR_FIELD_LENGTH 

Hour field length

I18N_UDATEPG_MATCH_ALL_FIELDS_LENGTH 

All fields length


Function Documentation

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 
)

Adds a pattern to the generator.

If the pattern has the same skeleton as an existing pattern, and the override parameter is set, then the previous value is overridden. Otherwise, the previous value is retained. In either case, the conflicting status is set and previous value is stored in conflicting pattern.
Note that single-field patterns (like "MMM") are automatically added, and don't need to be added explicitly!

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]dtpgAn i18n_udatepg_h handle. Must not be NULL.
[in]patternInput pattern, such as "dd/MMM". Must not be NULL.
[in]pattern_lengthThe length of pattern, >= 0.
[in]overridewhen existing values are to be overridden use true, otherwise use false.
[out]conflicting_patternPrevious pattern with the same skeleton.
[in]capacityThe capacity of conflicting_pattern.
[out]conflict_statusA pointer to the conflicting status The value could be I18N_UDATEPG_NO_CONFLICT, I18N_UDATEPG_BASE_CONFLICT or I18N_UDATEPG_CONFLICT.
Returns:
Length of conflicting_pattern. -1 if conflict_status is I18N_UDATEPG_NO_CONFLICT
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter

Creates an i18n_uenumeration_h for list of all the base skeletons in canonical form.

Since :
2.3.1
Parameters:
[in]dtpgAn i18n_udate_format_h handle. Must not be NULL.
[out]enumerationA pointer to the i18n_uenumeration_h for list of all the base skeletons. The caller must destroy the object.
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_udatepg_clone ( const i18n_udatepg_h  dtpg,
i18n_udatepg_h dtpg_clone 
)

Creates a copy of a generator.

Since :
2.3.1
Parameters:
[in]dtpgAn i18n_udatepg_h handle to be copied. Must not be NULL.
[out]dtpg_cloneA pointer to clone of dtpg handle.
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_udatepg_create ( const char *  locale,
i18n_udatepg_h dtpg 
)

Opens a generator according to a given locale.

Remarks:
Must release dtpg using i18n_udatepg_destroy().
Since :
2.3
Parameters:
[in]localeIf NULL - default locale will be used.
[out]dtpgA pointer to i18n_udatepg_h. Must not be NULL.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter

Creates an empty generator, to be constructed with i18n_udatepg_add_pattern() etc.

Since :
2.3.1
Parameters:
[out]dtpgA pointer to the i18n_udatepg_h handle.
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter

Destroys a generator.

Since :
2.3
Parameters:
[in]dtpgA pointer to i18n_udatepg_h. Must not be NULL.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
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 
)

Getter corresponding to i18n_udatepg_set_append_item_format().

Values below 0 or at or above I18N_UDATEPG_FIELD_COUNT are illegal arguments.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
Since :
2.3.1
Parameters:
[in]dtpgAn i18n_udatepg_h handle. Must not be NULL.
[in]fieldOne of i18n_udatepg_date_time_pattern_field_e, such as I18N_UDATEPG_ERA_FIELD.
[out]pattern_lengthA pointer that will receive the length of append item format value.
Returns:
The append_item_format for field
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
See also:
i18n_udatepg_set_append_item_format()
const i18n_uchar* i18n_udatepg_get_append_item_name ( const i18n_udatepg_h  dtpg,
i18n_udatepg_date_time_pattern_field_e  field,
int32_t *  pattern_length 
)

Getter corresponding to i18n_udatepg_set_append_item_name().

Values below 0 or at or above I18N_UDATEPG_FIELD_COUNT are illegal arguments.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
Since :
2.3.1
Parameters:
[in]dtpgThe i18n_udate_format_h handle. Must not be NULL.
[in]fieldi18n_udatepg_date_time_pattern_field_e, such as I18N_UDATEPG_ERA_FIELD.
[out]pattern_lengthA pointer that will receive the length of the name for field.
Returns:
The name for field
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
See also:
i18n_udatepg_set_append_item_name()
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 
)

Gets a unique base skeleton from a given pattern.

This is the same as the skeleton, except that differences in length are minimized so as to only preserve the difference between string and numeric form. So for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd"(notice the single d).
Note that this function uses a non-const i18n_udatepg_h : It uses a stateful pattern parser which is set up for each generator object, rather than creating one for each function call. Consecutive calls to this function do not affect each other, but this function cannot be used concurrently on a single generator object.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]dtpgAn i18n_udatepg_h handle. Must not be NULL.
[in]patternInput pattern, such as "dd/MMM". Must not be NULL.
[in]lengthThe length of pattern, >= 0.
[out]base_skeletonSuch as "Md".
[in]capacityThe capacity of base skeleton, >= 0.
Returns:
The length of base_skeleton.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
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 
)

Gets the best pattern matching the input skeleton.

It is guaranteed to have all of the fields in the skeleton.

Remarks:
This function uses a non-const i18n_udatepg_h: It uses a stateful pattern parser which is set up for each generator object, rather than creating one for each function call. Consecutive calls to this function do not affect each other, but this function cannot be used concurrently on a single generator object.
Since :
2.3
Parameters:
[in]dtpgA pointer to i18n_udatepg_h. Must not be NULL.
[in]skeletonThe skeleton is a pattern containing only the variable fields.
For example, "MMMdd" and "mmhh" are skeletons. Must not be NULL.
[in]lenThe length of the skeleton, >= 0.
[out]best_patternThe best pattern found from the given skeleton.
[in]capacityThe capacity of best_pattern, >= 0
[out]best_pattern_lenThe length of best_pattern.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_BUFFER_OVERFLOWA result would not fit in the supplied buffer
int32_t i18n_udatepg_get_best_pattern_with_options ( i18n_udatepg_h  dtpg,
const i18n_uchar skeleton,
int32_t  length,
i18n_udatepg_date_time_pattern_match_options_e  options,
i18n_uchar best_pattern,
int32_t  capacity 
)

Gets the best pattern matching the input skeleton.

It is guaranteed to have all of the fields in the skeleton.

Note that this function uses a non-const i18n_udatepg_h: It uses a stateful pattern parser which is set up for each generator object, rather than creating one for each function call. Consecutive calls to this function do not affect each other, but this function cannot be used concurrently on a single generator object.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]dtpgAn i18n_udatepg_h handle. Must not be NULL.
[in]skeletonThe skeleton is a pattern containing only the variable fields; for example, "MMMdd" and "mmhh" are skeletons. Must not be NULL.
[in]lengthThe length of skeleton, >= 0.
[in]optionsOptions for forcing the length of specified fields in the returned pattern to match those in the skeleton (when this would not happen otherwise). For default behavior, use I18N_UDATEPG_MATCH_NO_OPTIONS.
[out]best_patternThe best pattern found from the given skeleton.
[in]capacityThe capacity of best_pattern, >= 0.
Returns:
The length of best_pattern.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
const i18n_uchar* i18n_udatepg_get_date_time_format ( const i18n_udatepg_h  dtpg,
int32_t *  pattern_length 
)

Getter corresponding to i18n_udatepg_set_date_time_format().

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
Since :
2.3.1
Parameters:
[in]dtpgAn i18n_udate_format_h handle. Must not be NULL.
[out]pattern_lengthA pointer that will receive the length of the date_time_format.
Returns:
A date_time_format
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
See also:
i18n_udatepg_set_date_time_format()
const i18n_uchar* i18n_udatepg_get_decimal ( const i18n_udatepg_h  dtpg,
int32_t *  pattern_length 
)

Getter corresponding to i18n_udatepg_set_decimal().

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
Since :
2.3.1
Parameters:
[in]dtpgThe i18n_udate_format_h handle. Must not be NULL.
[out]pattern_lengthA pointer that will receive the length of the decimal string.
Returns:
Corresponding to the decimal point.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
See also:
i18n_udatepg_set_decimal()
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 
)

Gets the pattern corresponding to a given skeleton.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
Since :
2.3.1
Parameters:
[in]dtpgThe i18n_udate_format_h handle. Must not be NULL.
[in]skeletonThe skeleton. Must not be NULL.
[in]skeleton_lengthThe length of skeleton, >= 0.
[out]pattern_lengthThe pointer to the length of return pattern
Returns:
Pattern corresponding to a given skeleton
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int32_t i18n_udatepg_get_skeleton ( i18n_udatepg_h  dtpg,
const i18n_uchar pattern,
int32_t  length,
i18n_uchar skeleton,
int32_t  capacity 
)

Gets a unique skeleton from a given pattern. For example, both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd".

Note that this function uses a non-const i18n_udatepg_h: It uses a stateful pattern parser which is set up for each generator object, rather than creating one for each function call. Consecutive calls to this function do not affect each other, but this function cannot be used concurrently on a single generator object.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]dtpgAn i18n_udatepg_h handle. Must not be NULL.
[in]patternInput pattern, such as "dd/MMM". Must not be NULL.
[in]lengthThe length of pattern, >= 0.
[out]skeletonSuch as "MMMdd".
[in]capacityThe capacity of skeleton, >= 0.
Returns:
The length of skeleton.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int32_t i18n_udatepg_replace_field_types ( i18n_udatepg_h  dtpg,
const i18n_uchar pattern,
int32_t  pattern_length,
const i18n_uchar skeleton,
int32_t  skeleton_length,
i18n_uchar dest,
int32_t  dest_capacity 
)

Adjusts the field types (width and subtype) of a pattern to match what is in a skeleton.

That is, if you supply a pattern like "d-M H:m", and a skeleton of "MMMMddhhmm", then the input pattern is adjusted to be "dd-MMMM hh:mm". This is used internally to get the best match for the input skeleton, but can also be used externally.
Note that this function uses a non-const i18n_udatepg_h: It uses a stateful pattern parser which is set up for each generator object, rather than creating one for each function call. Consecutive calls to this function do not affect each other, but this function cannot be used concurrently on a single generator object.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]dtpgThe i18n_udate_format_h handle. Must not be NULL.
[in]patternInput pattern. Must not be NULL.
[in]pattern_lengthThe length of input pattern, >= 0.
[in]skeletonThe skeleton. Must not be NULL.
[in]skeleton_lengthThe length of input skeleton, >= 0.
[out]destPattern adjusted to match the skeleton fields widths and subtypes.
[in]dest_capacityThe capacity of dest, >= 0.
Returns:
The length of dest.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int32_t i18n_udatepg_replace_field_types_with_options ( i18n_udatepg_h  dtpg,
const i18n_uchar pattern,
int32_t  pattern_length,
const i18n_uchar skeleton,
int32_t  skeleton_length,
i18n_udatepg_date_time_pattern_match_options_e  options,
i18n_uchar dest,
int32_t  dest_capacity 
)

Adjusts the field types (width and subtype) of a pattern to match what is in a skeleton.

That is, if you supply a pattern like "d-M H:m", and a skeleton of "MMMMddhhmm", then the input pattern is adjusted to be "dd-MMMM hh:mm". This is used internally to get the best match for the input skeleton, but can also be used externally.
Note that this function uses a non-const i18n_udatepg_h: It uses a stateful pattern parser which is set up for each generator object, rather than creating one for each function call. Consecutive calls to this function do not affect each other, but this function cannot be used concurrently on a single generator object.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]dtpgThe i18n_udate_format_h handle. Must not be NULL.
[in]patternInput pattern. Must not be NULL.
[in]pattern_lengthThe length of input pattern, >= 0.
[in]skeletonThe skeleton. Must not be NULL.
[in]skeleton_lengthThe length of input skeleton, >= 0.
[in]optionsOptions controlling whether the length of specified fields in the pattern are adjusted to match those in the skeleton (when this would not happen otherwise). For default behavior, use I18N_UDATEPG_MATCH_NO_OPTIONS.
[out]destPattern adjusted to match the skeleton fields widths and subtypes.
[in]dest_capacityThe capacity of dest, >= 0.
Returns:
The length of dest.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
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 
)

An append_item_format is a pattern used to append a field if there is no good match.

For example, suppose that the input skeleton is "GyyyyMMMd", and there is no matching pattern internally, but there is a pattern matching "yyyyMMMd", say "d-MM-yyyy". Then that pattern is used, plus the G. The way these two are conjoined is by using the append_item_format for G (era). So if that value is, say "{0}, {1}" then the final resulting pattern is "d-MM-yyyy, G".
There are actually three available variables : {0} is the pattern so far, {1} is the element we are adding, and {2} is the name of the element.
This reflects the way that the CLDR data is organized.

Since :
2.3.1
Parameters:
[in]dtpgAn i18n_udatepg_h handle. Must not be NULL.
[in]fieldOne of i18n_udatepg_date_time_pattern_field_e, such as I18N_UDATEPG_ERA_FIELD.
[in]valuePattern, such as "{0}, {1}". Must not be NULL.
[in]lengthThe length of value, >= 0.
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
See also:
i18n_udatepg_get_append_item_format()
int i18n_udatepg_set_append_item_name ( i18n_udatepg_h  dtpg,
i18n_udatepg_date_time_pattern_field_e  field,
const i18n_uchar value,
int32_t  length 
)

Sets the name of field, e.g. "era" in English for ERA.

These are only used if the corresponding append_item_format is used, and if it contains a {2} variable. This reflects the way that the CLDR data is organized.

Since :
2.3.1
Parameters:
[in]dtpgAn i18n_udatepg_h handle. Must not be NULL.
[in]fieldi18n_udatepg_date_time_pattern_field_e, such as I18N_UDATEPG_ERA_FIELD.
[in]valueName for the field. Must not be NULL.
[in]lengthThe length of value, >= 0.
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
See also:
i18n_udatepg_get_append_item_name()
int i18n_udatepg_set_date_time_format ( const i18n_udatepg_h  dtpg,
const i18n_uchar date_time_format,
int32_t  length 
)

The date time format is a message format pattern used to compose date and time patterns.

The default value is "{0} {1}", where {0} will be replaced by the date pattern and {1} will be replaced by the time pattern. This is used when the input skeleton contains both date and time fields, but there is not a close match among the added patterns. For example, suppose that this object was created by adding "dd-MMM" and "hh:mm", and its date time format is the default "{0} {1}". Then if the input skeleton is "MMMdhmm", there is not an exact match, so the input skeleton is broken up into two components "MMMd" and "hmm". There are close matches for those two skeletons, so the result is put together with this pattern, resulting in "d-MMM h:mm".

Since :
2.3.1
Parameters:
[in]dtpgAn i18n_udate_format_h handle. Must not be NULL.
[in]date_time_formatA message format pattern, here {0} will be replaced by the date pattern and {1} will be replaced by the time pattern. Must not be NULL.
[in]lengthThe length of date_time_format, >= 0.
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
See also:
i18n_udatepg_get_date_time_format()
int i18n_udatepg_set_decimal ( i18n_udatepg_h  dtpg,
const i18n_uchar decimal,
int32_t  length 
)

The decimal value is used in formatting fractions of seconds.

If the skeleton contains fractional seconds, then this is used with the fractional seconds. For example, suppose that the input pattern is "hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and the decimal string is ",". Then the resulting pattern is modified to be "H:mm:ss,SSSS"

Since :
2.3.1
Parameters:
[in]dtpgThe i18n_udate_format_h handle. Must not be NULL.
[in]decimalDecimal. Must not be NULL.
[in]lengthThe length of decimal, >= 0.
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
See also:
i18n_udatepg_get_decimal()
int i18n_udatepg_skeletons_create ( const i18n_udatepg_h  dtpg,
i18n_uenumeration_h enumeration 
)

Creates an i18n_uenumeration_h for list of all the skeletons in canonical form.

Call i18n_udatepg_get_pattern_for_skeleton() to get the corresponding pattern.

Since :
2.3.1
Parameters:
[in]dtpgAn i18n_udate_format_h handle. Must not be NULL.
[out]enumerationA pointer to the i18n_uenumeration_h for list of all the skeletons. The caller must destroy the object.
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter