handle for object that represents a time zone offset, and also figures out daylight savings..

Since :

2.3

Callback function for i18n_timezone_foreach_timezone_id(), i18n_timezone_foreach_timezone_id_with_offset(), and i18n_timezone_foreach_timezone_id_by_country() that returns an enumeration over all recognized time zone IDs.

Since :

2.3

Parameters:

[in]	timezone_id	time zone ID
[in]	user_data	the user data passed to the callback function

Returns:

true to continue with the next iteration of the loop, otherwise false to break out of the loop.

See also:

i18n_ustring_unescape_at()

Enumeration for use with i18n_timezone_get_display_name(), i18n_timezone_get_display_name_with_locale(), and i18n_timezone_get_display_name_with_type().

Since :

2.3

Enumerator:

I18N_TIMEZONE_DISPLAY_TYPE_SHORT	Selector for short display name
I18N_TIMEZONE_DISPLAY_TYPE_LONG	Selector for long display name
I18N_TIMEZONE_DISPLAY_TYPE_SHORT_GENERIC	Selector for short generic display name
I18N_TIMEZONE_DISPLAY_TYPE_LONG_GENERIC	Selector for long generic display name
I18N_TIMEZONE_DISPLAY_TYPE_SHORT_GMT	Selector for short display name derived
I18N_TIMEZONE_DISPLAY_TYPE_LONG_GMT	Selector for long display name derived from time zone offset
I18N_TIMEZONE_DISPLAY_TYPE_SHORT_COMMONLY_USED	Selector for short display name derived from the time zone's fallback name
I18N_TIMEZONE_DISPLAY_TYPE_GENERIC_LOCATION	Selector for long display name derived from the time zone's fallback name

Clones i18n_timezone_h polymorphically.

Clients are responsible for deleting the i18n_timezone_h cloned.

Since :

2.3

Parameters:

[in]	timezone	The i18n_timezone_h to clone.
[out]	clone	A new copy of this i18n_timezone_h.

Return values:

I18N_ERROR_NONE

Successful

Returns the number of IDs in the equivalency group that includes the given ID.

An equivalency group contains zones that have the same GMT offset and rules.
The returned count includes the given ID; it is always >= 1. The given ID must be a system time zone. If it is not, returns zero.

Since :

2.3

Parameters:

[in]	timezone_id	a system time zone ID
[out]	count	the number of zones in the equivalency group containing 'timezone_id', or zero if 'timezone_id' is not a valid system ID

Return values:

I18N_ERROR_NONE

Successful

See also:

i18n_timezone_get_equivalent_id()

Creates an i18n_timezone_h for the given timezone_id.

Since :

2.3

Parameters:

[out]	timezone	the GMT/UTC time zone.
[in]	timezone_id	the ID for an i18n_timezone_h, such as "America/Los_Angeles", or a custom ID such as "GMT-8:00".

Return values:

I18N_ERROR_NONE

Successful

Creates a new copy of the default i18n_timezone_h for this host.

Unless the default time zone has already been set using i18n_timezone_set_default(), the default is determined by querying the system using methods in TPlatformUtilities. If the system routines fail, or if they specify an i18n_timezone_h or i18n_timezone_h offset which is not recognized, the i18n_timezone_h indicated by the ID kLastResortID is instantiated and made the default.

This function determines the default timezone by querying the system once and storing the obtained timezone as default until the application terminates.

To query the system for the current timezone, use i18n_timezone_detect_host_timezone().

Since :

2.3

Parameters:

[out]

timezone

A default i18n_timezone_h. Clients are responsible for deleting the time zone object returned.

Return values:

I18N_ERROR_NONE

Successful

The GMT (=UTC) time zone has a raw offset of zero and does not use daylight savings time.

This is a commonly used time zone.
Note: For backward compatibility reason, the ID used by the time zone returned by this method is "GMT", although the I18N's canonical ID for the GMT time zone is "Etc/GMT".

Since :

2.3

Parameters:

[out]

timezone

the GMT/UTC time zone.

Return values:

I18N_ERROR_NONE

Successful

See also:

i18n_timezone_create_unknown()

Returns the "unknown" time zone.

i18n_timezone_create() returns a mutable clone of this time zone if the input ID is not recognized.

Since :

2.3

Parameters:

[out]

timezone

the "unknown" time zone.

Return values:

I18N_ERROR_NONE

Successful

See also:

i18n_timezone_create()

i18n_timezone_create_gmt()

Destroys an i18n_timezone_h.

Once destroyed, an i18n_timezone_h may no longer be used.

Since :

2.3

Parameters:

[in]

timezone

The i18n_timezone_h to destroy.

Return values:

I18N_ERROR_NONE

Successful

Creates an i18n_timezone_h detected from the current host system configuration.

This function does not change the default time zone and does not update the current ICU's default. It may return a different i18n_timezone_h from the one returned by i18n_timezone_create_default().

Since :

3.0

Parameters:

[out]

timezone

A new instance of i18n_timezone_h detected from the current host system configuration. Users are responsible for deleting the returned time zone object with i18n_timezone_destroy().

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

Returns an enumeration over all recognized time zone IDs. (i.e., all strings that i18n_timezone_create() accepts)

Since :

2.3

Parameters:

[in]	cb	The callback function to get an enumeration object, owned by the caller.
[in]	user_data	The user data to be passed to the callback function.

Return values:

I18N_ERROR_NONE

Successful

Returns an enumeration over time zone IDs associated with the given country.

Some zones are affiliated with no country (e.g., "UTC"); these may also be retrieved, as a group.

Since :

2.3

Parameters:

[in]	country	The ISO 3166 two-letter country code, or NULL to retrieve zones not affiliated with any country.
[in]	cb	The callback function to get an enumeration object, owned by the caller.
[in]	user_data	The user data to be passed to the callback function.

Return values:

I18N_ERROR_NONE

Successful

Returns an enumeration over system time zone IDs with the given filter conditions.

Since :

2.3

Parameters:

[in]	timezone_type	The system time zone type.
[in]	region	The ISO 3166 two-letter country code or UN M.49 three-digit area code. When NULL, no filtering done by region.
[in]	raw_offset	An offset from GMT in milliseconds, ignoring the effect of daylight savings time, if any. When NULL, no filtering done by zone offset.
[in]	cb	The callback function to get an enumeration object, owned by the caller.
[in]	user_data	The user data to be passed to the callback function.

Return values:

I18N_ERROR_NONE

Successful

Returns an enumeration over time zone IDs with a given raw offset from GMT.

There may be several times zones with the same GMT offset that differ in the way they handle daylight savings time. For example, the state of Arizona doesn't observe daylight savings time. If you ask for the time zone IDs corresponding to GMT-7:00, you'll get back an enumeration over two time zone IDs: "America/Denver," which corresponds to Mountain Standard Time in the winter and Mountain Daylight Time in the summer, and "America/Phoenix", which corresponds to Mountain Standard Time year-round, even in the summer.

Since :

2.3

Parameters:

[in]	raw_offset	an offset from GMT in milliseconds, ignoring the effect of daylight savings time, if any
[in]	cb	The callback function to get an enumeration object, owned by the caller.
[in]	user_data	The user data to be passed to the callback function.

Return values:

I18N_ERROR_NONE

Successful

Returns a name of this time zone suitable for presentation to the user in the default locale.

This method returns the long name, not including daylight savings. If the display name is not available for the locale, then this method returns a string in the localized GMT offset format such as GMT[+-]HH:mm.

Since :

2.3

Parameters:

[in]	timezone	The i18n_timezone_h to get a display name.
[out]	display_name	The human-readable name of this time zone in the default locale.

Return values:

I18N_ERROR_NONE

Successful

Returns a name of this time zone suitable for presentation to the user in the default locale.

Deprecated:

Deprecated since 5.0. Use i18n_timezone_get_display_name_with_locale_id() instead.

This method returns the long name, not including daylight savings. If the display name is not available for the locale, then this method returns a string in the localized GMT offset format such as GMT[+-]HH:mm.

Since :

2.3

Parameters:

[in]	timezone	The i18n_timezone_h to get a display name.
[in]	language	The language in which to supply the display name. This parameter can be NULL; if so, the locale is initialized to match the current default locale.
[in]	country	The country in which to supply the display name. This parameter can be NULL.
[out]	display_name	The human-readable name of this time zone in the default locale.

Return values:

I18N_ERROR_NONE

Successful

Returns a name of this time zone suitable for presentation to the user in the default locale.

This method returns the long name, not including daylight savings. If the display name is not available for the locale, then this method returns a string in the localized GMT offset format such as GMT[+-]HH:mm.

Since :

5.0

Remarks:

display_name is allocated on heap and should be released by the caller with the free() function.

Parameters:

[in]	timezone	The i18n_timezone_h to get a display name
[in]	locale_id	The locale string containing language and country code
[out]	display_name	The human-readable name of this time zone in the default locale

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

Returns a name of this time zone suitable for presentation to the user in the default locale.

If the display name is not available for the locale, then this method returns a string in the localized GMT offset format such as GMT[+-]HH:mm.

Since :

2.3

Parameters:

[in]	timezone	The i18n_timezone_h to get a display name.
[in]	daylight	If true, display_name is filled with the daylight savings name.
[in]	style	The style displayed on.
[out]	display_name	The human-readable name of this time zone in the default locale.

Return values:

I18N_ERROR_NONE

Successful

Returns a name of this time zone suitable for presentation to the user in the default locale.

Deprecated:

Deprecated since 5.0. Use i18n_timezone_get_display_name_with_type_locale_id() instead.

If the display name is not available for the locale, then this method returns a string in the localized GMT offset format such as GMT[+-]HH:mm.

Since :

2.3

Parameters:

[in]	timezone	The i18n_timezone_h to get a display name.
[in]	daylight	If true, display_name is filled with the daylight savings name.
[in]	style	The style displayed on.
[in]	language	The language in which to supply the display name. This parameter can be NULL; if so, the locale is initialized to match the current default locale.
[in]	country	The country in which to supply the display name. This parameter can be NULL.
[out]	display_name	The human-readable name of this time zone in the default locale.

Return values:

I18N_ERROR_NONE

Successful

Returns a name of this time zone suitable for presentation to the user in the default locale.

If the display name is not available for the locale, then this method returns a string in the localized GMT offset format such as GMT[+-]HH:mm.

Since :

5.0

Remarks:

display_name is allocated on heap and should be released by the caller with the free() function.

Parameters:

[in]	timezone	The i18n_timezone_h to get a display name
[in]	daylight	If true, display_name is filled with the daylight savings name
[in]	style	The style displayed on
[in]	locale_id	The locale string containing language and country code
[out]	display_name	The human-readable name of this time zone in the default locale

Returns:

0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

Returns the amount of time to be added to local standard time to get local wall clock time.

The default implementation always returns 3600000 milliseconds (i.e., one hour) if this time zone observes Daylight Saving Time. Otherwise, 0 (zero) is returned.
If an underlying TimeZone implementation subclass supports historical Daylight Saving Time changes, this method returns the known latest daylight saving value.

Since :

2.3

Parameters:

[in]	timezone	The i18n_timezone_h to get DST savings.
[out]	dst_savings	The amount of saving time in milliseconds.

Return values:

I18N_ERROR_NONE

Successful

Returns an ID in the equivalency group that includes the given ID.

An equivalency group contains zones that have the same GMT offset and rules.
The given index must be in the range 0..n-1, where n is the out parameter value from i18n_timezone_count_equivalent_ids(timezone_id, &n). For some value of 'index', the returned value will be equal to the given id. If the given id is not a valid system time zone, or if 'index' is out of range, then returns an empty string.

Since :

2.3

Parameters:

[in]	timezone_id	a system time zone ID
[in]	index	a value from 0 to n-1, where n is the out parameter value from i18n_timezone_count_equivalent_ids(timezone_id, &n)
[out]	equivalent_timezone_id	the ID of the index-th zone in the equivalency group containing 'timezone_id', or an empty string if 'timezone_id' is not a valid system ID or 'index' is out of range

Return values:

I18N_ERROR_NONE

Successful

See also:

i18n_timezone_count_equivalent_ids()

Fills in "timezone_id" with the i18n_timezone_h's ID.

Since :

2.3

Parameters:

[in]	timezone	The i18n_timezone_h to get a timezone ID.
[out]	timezone_id	Receives this i18n_timezone_h's ID.

Return values:

I18N_ERROR_NONE

Successful

Returns the time zone raw and GMT offset for the given moment in time.

Upon return, local-millis = GMT-millis + rawOffset + dstOffset. All computations are performed in the proleptic Gregorian calendar.

Since :

2.3

Parameters:

[in]	timezone	The i18n_timezone_h to get an offset.
[in]	date	moment in time for which to return offsets, in units of milliseconds from January 1, 1970 0:00 GMT, either GMT time or local wall time, depending on `local'.
[in]	local	output if true, `date' is local wall time; otherwise it is in GMT time.
[out]	raw_offset	parameter to receive the raw offset, that is, the offset not including DST adjustments
[out]	dst_offset	output parameter to receive the DST offset, that is, the offset to be added to `raw_offset' to obtain the total offset between local and GMT time. If DST is not in effect, this value is zero; otherwise it is a positive value, typically one hour.

Return values:

I18N_ERROR_NONE

Successful

Gets the i18n_timezone_h's raw GMT offset (i.e., the number of milliseconds to add to GMT to get local time, before taking daylight savings time into account).

Since :

2.3

Parameters:

[in]	timezone	The i18n_timezone_h to get a raw offset.
[out]	offset_milliseconds	The i18n_timezone_h's raw GMT offset.

Return values:

I18N_ERROR_NONE

Successful

Gets the region code associated with the given system time zone ID.

The region code is either ISO 3166 2-letter country code or UN M.49 3-digit area code. When the time zone is not associated with a specific location, for example - "Etc/UTC", "EST5EDT", then this method returns "001" (UN M.49 area code for World).

Since :

2.3

Parameters:

[in]	timezone_id	The system time zone ID.
[out]	region	Output buffer for receiving the region code.
[out]	region_len	The length of the region code.
[in]	region_capacity	The size of the output buffer. If it is lower than required region buffer size, then I18N_ERROR_BUFFER_OVERFLOW error is returned.

Returns:

the version string, such as "2007f"

Returns the timezone data version currently used by I18N.

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in i18n_error_code_e description.

Since :

2.3

Returns:

the version string, such as "2007f"

Exceptions:

I18N_ERROR_NONE

Successful

Returns true if this zone has the same rule and offset as another zone.

That is, if this zone differs only in ID, if at all.

Since :

2.3

Parameters:

[in]	timezone	The i18n_timezone_h to know whether has the same rule or not.
[in]	other	The i18n_timezone_h to be compared with.
[out]	same_rule	True if the given zone is the same as this one, with the possible exception of the ID.

Return values:

I18N_ERROR_NONE

Successful

Sets the default time zone (i.e., what's returned by i18n_timezone_create_default()) to be the specified time zone.

If NULL is specified for the time zone, the default time zone is set to the default host time zone. The caller remains responsible for deleting it.
This function is not thread safe. It is an error for multiple threads to concurrently attempt to set the default time zone, or for any thread to attempt to reference the default zone while another thread is setting it.

Since :

2.3

Remarks:

Do not use unless you know what you are doing.

Parameters:

[in]

timezone

The given timezone.

Return values:

I18N_ERROR_NONE

Successful

Sets the i18n_timezone_h's ID to the specified value.

This doesn't affect any other fields. for example,

i18n_timezone_h timezone = NULL;
i18n_timezone_create ( &timezone, "America/New_York" );
i18n_timezone_set_id ( "America/Los_Angeles" );

the timezone's GMT offset and daylight-savings rules don't change to those for Los Angeles. They're still those for New York. Only the ID has changed.

Since :

2.3

Parameters:

[in]	timezone	The i18n_timezone_h to set a timezone ID.
[in]	timezone_id	The new time zone ID.

Return values:

I18N_ERROR_NONE

Successful

Sets the i18n_timezone_h's raw GMT offset (i.e., the number of milliseconds to add to GMT to get local time, before taking daylight savings time into account).

Since :

2.3

Parameters:

[in]	timezone	The i18n_timezone_h to set a raw offset.
[in]	offset_milliseconds	The new raw GMT offset for this time zone.

Return values:

I18N_ERROR_NONE

Successful

Queries if this time zone uses daylight savings time.

Since :

2.3

Parameters:

[in]	timezone	The i18n_timezone_h to know whether uses daylight savings time or not.
[out]	daylight_time	True if this time zone uses daylight savings time, False, otherwise.

Return values:

I18N_ERROR_NONE

Successful