The Timezone module represents a time zone offset, and also figures out daylight savings.

Required Header

#include <utils_i18n.h>

Overview

The Timezone module represents a time zone offset, and also figures out daylight savings.
Typically, you get an i18n_timezone_h using i18n_timezone_create_default which creates a TimeZone based on the time zone where the program is running. For example, for a program running in Japan, i18n_timezone_create_default creates an i18n_timezone_h based on Japanese Standard Time.
You can also get an i18n_timezone_h using i18n_timezone_create along with a time zone ID. For instance, the time zone ID for the US Pacific Time zone is "America/Los_Angeles". So, you can get a Pacific Time i18n_timezone_h with:
i18n_timezone_h timezone; i18n_timezone_create(&timezone, "America/Los_Angeles"); To create a new i18n_timezone_h, you call the factory function i18n_timezone_create() and pass it a time zone ID. You can use the int i18n_timezone_foreach_timezone_id() function to obtain a list of all the time zone IDs recognized by i18n_timezone_create().
You can also use i18n_timezone_create_default() to create an i18n_timezone_h. This function uses platform-specific APIs to produce an i18n_timezone_h for the time zone corresponding to the client's computer's physical location. For example, if you're in Japan (assuming your machine is set up correctly), i18n_timezone_create_default() will return an i18n_timezone_h for Japanese Standard Time ("Asia/Tokyo").

Functions
int	i18n_timezone_create_unknown (i18n_timezone_h *timezone)
	Returns the "unknown" time zone.
int	i18n_timezone_create_gmt (i18n_timezone_h *timezone)
	The GMT (=UTC) time zone has a raw offset of zero and does not use daylight savings time.
int	i18n_timezone_create (i18n_timezone_h timezone, const char timezone_id)
	Creates an i18n_timezone_h for the given timezone_id.
int	i18n_timezone_destroy (i18n_timezone_h timezone)
	Destroys an i18n_timezone_h.
int	i18n_timezone_foreach_timezone_id_by_region (i18n_system_timezone_type_e timezone_type, const char region, const int32_t raw_offset, i18n_timezone_id_cb cb, void *user_data)
	Returns an enumeration over system time zone IDs with the given filter conditions.
int	i18n_timezone_foreach_timezone_id (i18n_timezone_id_cb cb, void *user_data)
	Returns an enumeration over all recognized time zone IDs. (i.e., all strings that i18n_timezone_create() accepts)
int	i18n_timezone_foreach_timezone_id_with_offset (int32_t raw_offset, i18n_timezone_id_cb cb, void *user_data)
	Returns an enumeration over time zone IDs with a given raw offset from GMT.
int	i18n_timezone_foreach_timezone_id_by_country (const char country, i18n_timezone_id_cb cb, void user_data)
	Returns an enumeration over time zone IDs associated with the given country.
int	i18n_timezone_count_equivalent_ids (const char timezone_id, int32_t count)
	Returns the number of IDs in the equivalency group that includes the given ID.
int	i18n_timezone_get_equivalent_id (const char timezone_id, int32_t index, char *equivalent_timezone_id)
	Returns an ID in the equivalency group that includes the given ID.
int	i18n_timezone_create_default (i18n_timezone_h *timezone)
	Creates a new copy of the default i18n_timezone_h for this host.
int	i18n_timezone_set_default (i18n_timezone_h timezone)
	Sets the default time zone (i.e., what's returned by i18n_timezone_create_default()) to be the specified time zone.
const char *	i18n_timezone_get_tzdata_version (void)
	Returns the timezone data version currently used by I18N.
int	i18n_timezone_get_region (const char timezone_id, char region, int32_t *region_len, int32_t region_capacity)
	Gets the region code associated with the given system time zone ID.
int	i18n_timezone_get_offset_with_date (i18n_timezone_h timezone, i18n_udate date, i18n_ubool local, int32_t raw_offset, int32_t dst_offset)
	Returns the time zone raw and GMT offset for the given moment in time.
int	i18n_timezone_set_raw_offset (i18n_timezone_h timezone, int32_t offset_milliseconds)
	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).
int	i18n_timezone_get_raw_offset (i18n_timezone_h timezone, int32_t *offset_milliseconds)
	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).
int	i18n_timezone_get_id (i18n_timezone_h timezone, char **timezone_id)
	Fills in "timezone_id" with the i18n_timezone_h's ID.
int	i18n_timezone_set_id (i18n_timezone_h timezone, const char *timezone_id)
	Sets the i18n_timezone_h's ID to the specified value.
int	i18n_timezone_get_display_name (i18n_timezone_h timezone, char **display_name)
	Returns a name of this time zone suitable for presentation to the user in the default locale.
int	i18n_timezone_get_display_name_with_locale (i18n_timezone_h timezone, const char language, const char country, char **display_name)
	Returns a name of this time zone suitable for presentation to the user in the default locale.
int	i18n_timezone_get_display_name_with_type (i18n_timezone_h timezone, i18n_ubool daylight, i18n_timezone_display_type_e style, char **display_name)
	Returns a name of this time zone suitable for presentation to the user in the default locale.
int	i18n_timezone_get_display_name_with_type_locale (i18n_timezone_h timezone, i18n_ubool daylight, i18n_timezone_display_type_e style, const char language, const char country, char **display_name)
	Returns a name of this time zone suitable for presentation to the user in the default locale.
int	i18n_timezone_use_daylight_time (i18n_timezone_h timezone, i18n_ubool *daylight_time)
	Queries if this time zone uses daylight savings time.
int	i18n_timezone_has_same_rule (i18n_timezone_h timezone, i18n_timezone_h other, i18n_ubool *same_rule)
	Returns true if this zone has the same rule and offset as another zone.
int	i18n_timezone_clone (i18n_timezone_h timezone, i18n_timezone_h *clone)
	Clones i18n_timezone_h polymorphically.
int	i18n_timezone_get_dst_savings (i18n_timezone_h timezone, int32_t *dst_savings)
	Returns the amount of time to be added to local standard time to get local wall clock time.
int	i18n_timezone_detect_host_timezone (i18n_timezone_h *timezone)
	Creates an i18n_timezone_h detected from the current host system configuration.
int	i18n_timezone_get_display_name_with_locale_id (i18n_timezone_h timezone, const char locale_id, char *display_name)
	Returns a name of this time zone suitable for presentation to the user in the default locale.
int	i18n_timezone_get_display_name_with_type_locale_id (i18n_timezone_h timezone, i18n_ubool daylight, i18n_timezone_display_type_e style, const char locale_id, char *display_name)
	Returns a name of this time zone suitable for presentation to the user in the default locale.
Typedefs
typedef void *	i18n_timezone_h
	handle for object that represents a time zone offset, and also figures out daylight savings..
typedef bool(*	i18n_timezone_id_cb )(const char timezone_id, void user_data)
	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.

Typedef Documentation

typedef void* i18n_timezone_h

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

Since :: 2.3

typedef bool(* i18n_timezone_id_cb)(const char *timezone_id, void *user_data)

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 Type Documentation

enum i18n_timezone_display_type_e

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

Function Documentation

int i18n_timezone_clone	(	i18n_timezone_h	timezone,
		i18n_timezone_h *	clone
	)

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

int i18n_timezone_count_equivalent_ids	(	const char *	timezone_id,
		int32_t *	count
	)

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()

int i18n_timezone_create	(	i18n_timezone_h *	timezone,
		const char *	timezone_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

int i18n_timezone_create_default ( i18n_timezone_h * timezone )

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

int i18n_timezone_create_gmt ( i18n_timezone_h * timezone )

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()

int i18n_timezone_create_unknown ( i18n_timezone_h * timezone )

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()

int i18n_timezone_destroy ( i18n_timezone_h timezone )

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

int i18n_timezone_detect_host_timezone ( i18n_timezone_h * timezone )

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

int i18n_timezone_foreach_timezone_id	(	i18n_timezone_id_cb	cb,
		void *	user_data
	)

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

int i18n_timezone_foreach_timezone_id_by_country	(	const char *	country,
		i18n_timezone_id_cb	cb,
		void *	user_data
	)

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

int i18n_timezone_foreach_timezone_id_by_region	(	i18n_system_timezone_type_e	timezone_type,
		const char *	region,
		const int32_t *	raw_offset,
		i18n_timezone_id_cb	cb,
		void *	user_data
	)

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

int i18n_timezone_foreach_timezone_id_with_offset	(	int32_t	raw_offset,
		i18n_timezone_id_cb	cb,
		void *	user_data
	)

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

int i18n_timezone_get_display_name	(	i18n_timezone_h	timezone,
		char **	display_name
	)

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

int i18n_timezone_get_display_name_with_locale	(	i18n_timezone_h	timezone,
		const char *	language,
		const char *	country,
		char **	display_name
	)

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

int i18n_timezone_get_display_name_with_locale_id	(	i18n_timezone_h	timezone,
		const char *	locale_id,
		char **	display_name
	)

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

int i18n_timezone_get_display_name_with_type	(	i18n_timezone_h	timezone,
		i18n_ubool	daylight,
		i18n_timezone_display_type_e	style,
		char **	display_name
	)

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

int i18n_timezone_get_display_name_with_type_locale	(	i18n_timezone_h	timezone,
		i18n_ubool	daylight,
		i18n_timezone_display_type_e	style,
		const char *	language,
		const char *	country,
		char **	display_name
	)

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

int i18n_timezone_get_display_name_with_type_locale_id	(	i18n_timezone_h	timezone,
		i18n_ubool	daylight,
		i18n_timezone_display_type_e	style,
		const char *	locale_id,
		char **	display_name
	)

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

int i18n_timezone_get_dst_savings	(	i18n_timezone_h	timezone,
		int32_t *	dst_savings
	)

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

int i18n_timezone_get_equivalent_id	(	const char *	timezone_id,
		int32_t	index,
		char **	equivalent_timezone_id
	)

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()

int i18n_timezone_get_id	(	i18n_timezone_h	timezone,
		char **	timezone_id
	)

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

int i18n_timezone_get_offset_with_date	(	i18n_timezone_h	timezone,
		i18n_udate	date,
		i18n_ubool	local,
		int32_t *	raw_offset,
		int32_t *	dst_offset
	)

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

int i18n_timezone_get_raw_offset	(	i18n_timezone_h	timezone,
		int32_t *	offset_milliseconds
	)

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

int i18n_timezone_get_region	(	const char *	timezone_id,
		char *	region,
		int32_t *	region_len,
		int32_t	region_capacity
	)

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"

const char* i18n_timezone_get_tzdata_version ( void )

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

int i18n_timezone_has_same_rule	(	i18n_timezone_h	timezone,
		i18n_timezone_h	other,
		i18n_ubool *	same_rule
	)

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

int i18n_timezone_set_default ( i18n_timezone_h timezone )

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

int i18n_timezone_set_id	(	i18n_timezone_h	timezone,
		const char *	timezone_id
	)

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

int i18n_timezone_set_raw_offset	(	i18n_timezone_h	timezone,
		int32_t	offset_milliseconds
	)

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

int i18n_timezone_use_daylight_time	(	i18n_timezone_h	timezone,
		i18n_ubool *	daylight_time
	)

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

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation