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_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().
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_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().
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_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().
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_uchar *	i18n_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_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.
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

enum i18n_udatepg_date_time_pattern_conflict_e

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

enum i18n_udatepg_date_time_pattern_field_e

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

enum i18n_udatepg_date_time_pattern_match_options_e

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]	dtpg	An i18n_udatepg_h handle. Must not be `NULL`.
[in]	pattern	Input pattern, such as "dd/MMM". Must not be `NULL`.
[in]	pattern_length	The length of `pattern`, >= 0.
[in]	override	when existing values are to be overridden use true, otherwise use false.
[out]	conflicting_pattern	Previous pattern with the same skeleton.
[in]	capacity	The capacity of `conflicting_pattern`.
[out]	conflict_status	A 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_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

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.

Since :: 2.3.1

Remarks:: The enumeration should be released using i18n_uenumeration_destroy().

Parameters:

[in]	dtpg	An i18n_udate_format_h handle. Must not be `NULL`.
[out]	enumeration	A 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_NONE Successful

I18N_ERROR_INVALID_PARAMETER

Invalid function parameter

 #include <stdio.h>
 #include <stdlib.h>
 #include <utils_i18n.h>
 int main() {
    i18n_error_code_e error_code;
    i18n_uenumeration_h enumeration = NULL;
    i18n_udatepg_h dtpg = NULL;
    error_code = i18n_udatepg_create_empty(&dtpg);
    if (error_code != I18N_ERROR_NONE) {
        printf("Error i18n_udatepg_create_empty: %d\n", error_code);
        return EXIT_FAILURE;
    }
    error_code = i18n_udatepg_base_skeletons_create(dtpg, &enumeration);
    if (error_code != I18N_ERROR_NONE) {
        printf("Error i18n_udatepg_base_skeletons_create: %d\n", error_code);
        i18n_udatepg_destroy(dtpg);
        return EXIT_FAILURE;
    }
    i18n_uenumeration_destroy(enumeration);
    i18n_udatepg_destroy(dtpg);
    return EXIT_SUCCESS;
 }

int i18n_udatepg_clone	(	const i18n_udatepg_h	dtpg,
		i18n_udatepg_h *	dtpg_clone
	)

Creates a copy of a generator.

Since :: 2.3.1

Remarks:: The dtpg should be released using i18n_udatepg_destroy().

Parameters:

[in]	dtpg	An i18n_udatepg_h handle to be copied. Must not be `NULL`.
[out]	dtpg_clone	A pointer to clone of dtpg handle.

Returns:: The obtained error code.

Return values:

I18N_ERROR_NONE Successful

I18N_ERROR_INVALID_PARAMETER

Invalid function parameter

 #include <stdio.h>
 #include <stdlib.h>
 #include <utils_i18n.h>
 int main() {
    i18n_error_code_e error_code;
  i18n_udatepg_h dtpg = NULL;
  i18n_udatepg_h dtpg_clone = NULL;
    error_code = i18n_udatepg_create_empty(&dtpg);
    if (error_code != I18N_ERROR_NONE) {
        printf("Error i18n_udatepg_create_empty: %d\n", error_code);
        return EXIT_FAILURE;
    }
    error_code = i18n_udatepg_clone(dtpg, &dtpg_clone);
    if (error_code != I18N_ERROR_NONE) {
        printf("Error i18n_udatepg_clone: %d\n", error_code);
        i18n_udatepg_destroy(dtpg);
        return EXIT_FAILURE;
    }
    i18n_udatepg_destroy(dtpg_clone);
    i18n_udatepg_destroy(dtpg);
    return EXIT_SUCCESS;
 }

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]	locale	If `NULL` - default locale will be used.
[out]	dtpg	A pointer to i18n_udatepg_h. Must not be `NULL`.

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_udatepg_create_empty ( i18n_udatepg_h * dtpg )

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

Since :: 2.3.1

Remarks:: The dtpg should be released using i18n_udatepg_destroy().

Parameters:

[out] dtpg A pointer to the i18n_udatepg_h handle.

Returns:: The obtained error code.

Return values:

I18N_ERROR_NONE Successful

I18N_ERROR_INVALID_PARAMETER

Invalid function parameter

 #include <stdio.h>
 #include <stdlib.h>
 #include <utils_i18n.h>
 int main() {
    i18n_error_code_e error_code;
    i18n_udatepg_h dtpg = NULL;
    error_code = i18n_udatepg_create_empty(&dtpg);
    if (error_code != I18N_ERROR_NONE) {
        printf("Error i18n_udatepg_create_empty: %d\n", error_code);
        return EXIT_FAILURE;
    }
    i18n_udatepg_destroy(dtpg);
    return EXIT_SUCCESS;
 }

int i18n_udatepg_destroy ( i18n_udatepg_h dtpg )

Destroys a generator.

Since :: 2.3

Parameters:

[in] dtpg A pointer to i18n_udatepg_h. Must not be NULL.

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid 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]	dtpg	An i18n_udatepg_h handle. Must not be `NULL`.
[in]	field	One of i18n_udatepg_date_time_pattern_field_e, such as I18N_UDATEPG_ERA_FIELD.
[out]	pattern_length	A pointer that will receive the length of append item format value.

Returns:: The append_item_format for field

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid 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]	dtpg	The i18n_udate_format_h handle. Must not be `NULL`.
[in]	field	i18n_udatepg_date_time_pattern_field_e, such as I18N_UDATEPG_ERA_FIELD.
[out]	pattern_length	A pointer that will receive the length of the name for `field`.

Returns:: The name for field

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid 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]	dtpg	An i18n_udatepg_h handle. Must not be `NULL`.
[in]	pattern	Input pattern, such as "dd/MMM". Must not be `NULL`.
[in]	length	The length of `pattern`, >= 0.
[out]	base_skeleton	Such as "Md".
[in]	capacity	The capacity of base_skeleton, >= 0.

Returns:: The length of base_skeleton.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid 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]	dtpg	A pointer to i18n_udatepg_h. Must not be `NULL`.
[in]	skeleton	The skeleton is a pattern containing only the variable fields. For example, "MMMdd" and "mmhh" are skeletons. Must not be `NULL`.
[in]	len	The length of the skeleton, >= 0.
[out]	best_pattern	The best pattern found from the given skeleton.
[in]	capacity	The capacity of best_pattern, >= 0
[out]	best_pattern_len	The length of best_pattern.

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_BUFFER_OVERFLOW	A 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]	dtpg	An i18n_udatepg_h handle. Must not be `NULL`.
[in]	skeleton	The skeleton is a pattern containing only the variable fields; for example, "MMMdd" and "mmhh" are skeletons. Must not be `NULL`.
[in]	length	The length of skeleton, >= 0.
[in]	options	Options 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_pattern	The best pattern found from the given skeleton.
[in]	capacity	The capacity of best_pattern, >= 0.

Returns:: The length of best_pattern.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid 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]	dtpg	An i18n_udate_format_h handle. Must not be `NULL`.
[out]	pattern_length	A pointer that will receive the length of the date_time_format.

Returns:: A date_time_format

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid 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]	dtpg	The i18n_udate_format_h handle. Must not be `NULL`.
[out]	pattern_length	A pointer that will receive the length of the decimal string.

Returns:: Corresponding to the decimal point.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid 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]	dtpg	The i18n_udate_format_h handle. Must not be `NULL`.
[in]	skeleton	The skeleton. Must not be `NULL`.
[in]	skeleton_length	The length of skeleton, >= 0.
[out]	pattern_length	The pointer to the length of return pattern

Returns:: Pattern corresponding to a given skeleton

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid 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]	dtpg	An i18n_udatepg_h handle. Must not be `NULL`.
[in]	pattern	Input pattern, such as "dd/MMM". Must not be `NULL`.
[in]	length	The length of `pattern`, >= 0.
[out]	skeleton	Such as "MMMdd".
[in]	capacity	The capacity of skeleton, >= 0.

Returns:: The length of skeleton.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid 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]	dtpg	The i18n_udate_format_h handle. Must not be `NULL`.
[in]	pattern	Input pattern. Must not be `NULL`.
[in]	pattern_length	The length of input pattern, >= 0.
[in]	skeleton	The skeleton. Must not be `NULL`.
[in]	skeleton_length	The length of input skeleton, >= 0.
[out]	dest	Pattern adjusted to match the skeleton fields widths and subtypes.
[in]	dest_capacity	The capacity of dest, >= 0.

Returns:: The length of dest.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid 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]	dtpg	The i18n_udate_format_h handle. Must not be `NULL`.
[in]	pattern	Input pattern. Must not be `NULL`.
[in]	pattern_length	The length of input pattern, >= 0.
[in]	skeleton	The skeleton. Must not be `NULL`.
[in]	skeleton_length	The length of input skeleton, >= 0.
[in]	options	Options 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]	dest	Pattern adjusted to match the skeleton fields widths and subtypes.
[in]	dest_capacity	The capacity of dest, >= 0.

Returns:: The length of dest.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid 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]	dtpg	An i18n_udatepg_h handle. Must not be `NULL`.
[in]	field	One of i18n_udatepg_date_time_pattern_field_e, such as I18N_UDATEPG_ERA_FIELD.
[in]	value	Pattern, such as "{0}, {1}". Must not be `NULL`.
[in]	length	The length of `value`, >= 0.

Returns:: The obtained error code.

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid 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]	dtpg	An i18n_udatepg_h handle. Must not be `NULL`.
[in]	field	i18n_udatepg_date_time_pattern_field_e, such as I18N_UDATEPG_ERA_FIELD.
[in]	value	Name for the `field`. Must not be `NULL`.
[in]	length	The length of `value`, >= 0.

Returns:: The obtained error code.

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid 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]	dtpg	An i18n_udate_format_h handle. Must not be `NULL`.
[in]	date_time_format	A 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]	length	The length of `date_time_format`, >= 0.

Returns:: The obtained error code.

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid 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]	dtpg	The i18n_udate_format_h handle. Must not be `NULL`.
[in]	decimal	Decimal. Must not be `NULL`.
[in]	length	The length of `decimal`, >= 0.

Returns:: The obtained error code.

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid 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

Remarks:: The enumeration should be released using i18n_uenumeration_destroy().

Parameters:

[in]	dtpg	An i18n_udate_format_h handle. Must not be `NULL`.
[out]	enumeration	A 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_NONE Successful

I18N_ERROR_INVALID_PARAMETER

Invalid function parameter

 #include <stdio.h>
 #include <stdlib.h>
 #include <utils_i18n.h>
 int main() {
    i18n_error_code_e error_code;
    i18n_uenumeration_h enumeration = NULL;
    i18n_udatepg_h dtpg = NULL;
    error_code = i18n_udatepg_create_empty(&dtpg);
    if (error_code != I18N_ERROR_NONE) {
        printf("Error i18n_udatepg_create_empty: %d\n", error_code);
        return EXIT_FAILURE;
    }
    error_code = i18n_udatepg_skeletons_create(dtpg, &enumeration);
    if (error_code != I18N_ERROR_NONE) {
        printf("Error i18n_udatepg_skeletons_create: %d\n", error_code);
        i18n_udatepg_destroy(dtpg);
        return EXIT_FAILURE;
    }
    i18n_uenumeration_destroy(enumeration);
    i18n_udatepg_destroy(dtpg);
    return EXIT_SUCCESS;
 }

Required Header

Overview

Sample Code 1

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation