Time zone. More...

Inheritance diagram for MTimeZone:

Public Member Functions
	MTimeZone ()
	Default constructor to create the current timezone, the one that matches the computer timezone. More...

	MTimeZone (const MStdString &name)
	Constructor that creates a new timezone using operating system defined timezone name. More...

	MTimeZone (int standardOffset)
	Constructor that creates a new timezone with only a standard offset defined. More...

	MTimeZone (int standardOffset, const MStdString &standardName)
	Constructor to create a timezone with a standard offset and name. More...

	MTimeZone (int standardOffset, int daylightOffset, const MTimeRecurrentYearly &switchToDaylightTime, const MTimeRecurrentYearly &switchToStandardTime)
	Constructor that creates a new unnamed timezone with an offset, and daylight saving time parameters defined. More...

	MTimeZone (int standardOffset, int daylightOffset, const MTimeRecurrentYearly &switchToDaylightTime, const MTimeRecurrentYearly &switchToStandardTime, const MStdString &standardName, const MStdString &daylightName)
	Constructor that creates a new named timezone with daylight saving time defined. More...

	MTimeZone (const MTimeZone &other)
	Copy constructor, creates a timezone from a copy given. More...

virtual	~MTimeZone ()
	Object destructor.

MTimeZone &	operator= (const MTimeZone &other)
	Assignment operator, assigns one timezone into another. More...

bool	operator== (const MTimeZone &other) const
	Equality operator, returns true if all properties of one timezone match another timezone's properties.

bool	operator!= (const MTimeZone &other) const
	Inequality operator, returns true if any property of one timezone does not match one in another timezone.

MTime	GetLocalTime () const
	Get local time according to this timezone. More...

MTime	GetStandardTime () const
	Get standard time according to this timezone. More...

bool	SupportsDST () const
	Whether the local timezone has a notion of DST currently, and in the future. More...

bool	HasSwitchTimes () const
	Whether the local timezone has any switch times in the past or in the future, related to DST or not. More...

int	GetLocalToUtcOffset (const MTime &localTime) const
	Get the shift of the given local time from UTC, given the properties of the current timezone. More...

int	GetUtcToLocalOffset (const MTime &utcTime) const
	Get the shift of the given UTC time from Local, given the properties of the current timezone. More...

int	GetStandardOffsetForTime (const MTime &utcTime) const
	Get the standard offset for a given time. More...

int	GetDaylightOffsetForYear (int year) const
	Get the daylight offset in a given year. More...

bool	IsDST (const MTime &time, bool isTimeUtc=false) const
	True will mean that according to this timezone, the given time is in DST. More...

MTimeRecurrentYearly &	GetSwitchToDaylightTime ()
	The recurring local time where time goes from Standard to DST. More...

const MTimeRecurrentYearly &	GetSwitchToDaylightTimeConst () const
	Constant C++ version of GetSwitchToDaylightTime.

MTimeRecurrentYearly &	GetSwitchToStandardTime ()
	The recurring local time where time goes from DST back to Standard. More...

const MTimeRecurrentYearly &	GetSwitchToStandardTimeConst () const
	Constant C++ version of GetSwitchToStandardTime.

MTime	GetNextSwitchTime (const MTime &anchorTime, bool isTimeUtc=false) const
	Calculate the time at which the timezone offset will be switched. More...

int	GetSwitchTimeOffsetChange (const MTime &time, bool isTimeUtc=false) const
	Return the number of seconds added or subtracted around the given switch time. More...

void	Clear ()
	Clear all fields of timezone. More...

MTime	UtcToLocal (const MTime &time) const
	Convert the given time from UTC to Local, using this timezone information. More...

MTime	LocalToUtc (const MTime &time) const
	Convert the given time from Local to UTC, using this locale. More...

MTime	UtcToStandard (const MTime &time) const
	Convert the given time from UTC to Standard, without respecting the DST offset and switch time. More...

MTime	StandardToUtc (const MTime &time) const
	Convert the given time from Standard to UTC, without respecting the DST offset and switch time. More...

MTime	StandardToLocal (const MTime &time) const
	Convert the given time from Standard to Local, by possibly applying a DST shift. More...

MTime	LocalToStandard (const MTime &time) const
	Convert the given time from Local to Standard, by possibly applying a DST shift. More...

void	SetFromCurrentSystem ()
	Sets the current timezone from the current system timezone. More...

void	SetByName (const MStdString &name)
	Sets the current timezone using the name given. More...

MTimeZone *	NewClone () const
	Reflection-enabled copy constructor, clone service.


bool	InitializedFromDatabase () const

void	SetInitializedFromDatabase (bool yes)


const MStdString &	GetStandardName () const

void	SetStandardName (const MStdString &)


const MStdString &	GetDaylightName () const

void	SetDaylightName (const MStdString &name)


int	GetStandardOffset () const

void	SetStandardOffset (int offset)


int	GetDaylightOffset () const

void	SetDaylightOffset (int offset)


const MStdString &	GetDisplayName () const

void	SetDisplayName (const MStdString &name)

Public Member Functions inherited from MObject
virtual	~MObject ()
	Object destructor.

virtual const MClass *	GetClass () const =0
	Get the final class of the object. More...

virtual unsigned	GetEmbeddedSizeof () const
	For embedded object types, return the size of the class. More...

bool	IsEmbeddedObject () const
	Tell if the object is of embedded kind. More...

SHOW_INTERNAL MVariant	Call (const MStdString &name, const MVariant &params)
	Call the object service with parameters, given as variant. More...

MVariant	Call0 (const MStdString &name)
	Call the object service with no parameters. More...

MVariant	Call1 (const MStdString &name, const MVariant &p1)
	Call the object service with one parameter. More...

MVariant	Call2 (const MStdString &name, const MVariant &p1, const MVariant &p2)
	Call the object service with two parameter. More...

MVariant	Call3 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3)
	Call the object service with three parameter. More...

MVariant	Call4 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4)
	Call the object service with four parameter. More...

MVariant	Call5 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4, const MVariant &p5)
	Call the object service with five parameter. More...

MVariant	Call6 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4, const MVariant &p5, const MVariant &p6)
	Call the object service with six parameter. More...

virtual MVariant	CallV (const MStdString &name, const MVariant::VariantVector &params)
	Call the object service with parameters, given as variant vector. More...

virtual bool	IsPropertyPresent (const MStdString &name) const
	Tell if the property with the given name exists.

virtual bool	IsServicePresent (const MStdString &name) const
	Tell if the service with the given name exists.

virtual MVariant	GetProperty (const MStdString &name) const
	Get the property value using name of the property. More...

virtual void	SetProperty (const MStdString &name, const MVariant &value)
	Set the property using name of the property, and value. More...

virtual MStdStringVector	GetAllPropertyNames () const
	Return the list of publicly available properties, persistent or not. More...

virtual MStdStringVector	GetAllPersistentPropertyNames () const
	Return the list of persistent properties. More...

virtual void	SetPersistentPropertiesToDefault ()
	Set the persistent properties of the object to their default values. More...

virtual MVariant	GetPersistentPropertyDefaultValue (const MStdString &name) const
	Get the default value of persistent property with the name given. More...

virtual void	SetPersistentPropertyToDefault (const MStdString &name)
	Set the persistent property with the name given to default value. More...

virtual const char *	GetType () const
	Get the name of the type for the object (could be the same as class name).

virtual void	SetType (const MStdString &)
	Intentionally, it will set the name of the type for the object, but the service will not allow setting the name to anything other than the current name. More...

virtual void	Validate ()
	Validate internal structures of the object. More...

Static Public Member Functions
static MTimeZone *	GetCurrent ()
	Access the globally present current computer timezone. More...

static MStdStringVector	GetAllTimeZoneNames ()
	Access the names of all globally present timezones, as defined by the operating system. More...

static MStdStringVector	GetAllTimeZoneDisplayNames ()
	Access the names of all globally present timezones, verbose representation. More...

static MStdStringVector	GetAllTimeZoneLocalNames ()
	Access the unprocessed local names of the timezone, a rather concise representation. More...

static MTime	GetUtcTime ()
	Get current UTC time, independent from any timezone, static property.

static MStdString	StandardNameWindowsToIana (const MStdString &windowsName)
	Return a correspondent IANA timezone name from Windows timezone name. More...

static MStdString	StandardNameIanaToWindows (const MStdString &ianaName)
	Return a correspondent Windows timezone name from IANA timezone name. More...

Static Public Member Functions inherited from MObject
static const MClass *	GetStaticClass ()
	Get the declared class of this particular object. More...

static bool	IsClassPresent (const MStdString &name)
	Tells if the given class name is available. More...

Static Public Attributes
static const char	s_timezoneNameSeparator []
	Timezone name separator, as used to separate name from display name.

static const unsigned	s_timezoneNameSeparatorSize
	Number of characters of timezone name separator, s_timezoneNameSeparator.

Static Public Attributes inherited from MObject
static const MClass	s_class
	Class of MObject.

Additional Inherited Members
Protected Member Functions inherited from MObject
	MObject ()
	Object constructor, protected as the class is abstract.

void	DoSetPersistentPropertiesToDefault (const MClass *staticClass)
	Set the persistent properties to their default values for one object provided the class for that object. More...

Detailed Description

Time zone.

Timezone holds information about offset from Coordinated Universal Time, Daylight Saving Time (DST) settings, switch dates, and names for all of it. Timezones can be created by supplying values directly, or by name using services supplied by the operating system.

There is a static property, Current timezone, from which the computer current timezone can be accessed. However one cannot change computer's timezone using MeteringSDK interfaces.

Constructor & Destructor Documentation

MTimeZone::MTimeZone ( )

Default constructor to create the current timezone, the one that matches the computer timezone.

If the user creates such timezone, it will not be updated automatically if the computer timezone changes after the class is created. Instead, it will stay the same as the time when it was created. Similarly, one can change any properties of this object without affecting the computer timezone.

To create a timezone with all fields set to zeros or empty strings, use constructor that accepts a single standard offset, and have it at zero.

Postcondition: InitializedFromDatabase property will be true.

MTimeZone::MTimeZone ( const MStdString & name )

Constructor that creates a new timezone using operating system defined timezone name.

All timezone properties get filled from the operating system definition for such timezone.

Parameters

name	Name of the timezone. The given timezone name shall be valid, and it shall be defined in the operating system, otherwise an exception is thrown.

Postcondition: InitializedFromDatabase property will be false.

MTimeZone::MTimeZone ( int standardOffset )

Constructor that creates a new timezone with only a standard offset defined.

No name is given to daylight or to standard time. The created timezone will have no daylight saving time settings.

Parameters

standardOffset Standard offset of this timezone in seconds. There is a check that the given offset is within range of -13 to 13 hours, which translates into standardOffset value range of -46800 .. 46800, and it should be divisible by 5 minutes (300 seconds), or an exception will be raised.

Postcondition: InitializedFromDatabase property will be false.

MTimeZone::MTimeZone	(	int	standardOffset,
		const MStdString &	standardName
	)

Constructor to create a timezone with a standard offset and name.

No name is given to to daylight time, and the newly created timezone will have no daylight saving time settings. This call does not use the operating system facilities to verify whether such timezone name exists, or whether it has the same standard offset as one supplied.

Parameters

standardOffset	Standard offset of this timezone from UTC in seconds. There is a check that the given offset is within range of -13 to 13 hours, which translates into range -46800 .. 46800, and it should be divisible by 5 minutes (300 seconds), or an exception will be raised.
standardName	The name to give to the newly created timezone object, does not have to be the one defined by the operating system.

Postcondition: InitializedFromDatabase property will be false.

MTimeZone::MTimeZone	(	int	standardOffset,
		int	daylightOffset,
		const MTimeRecurrentYearly &	switchToDaylightTime,
		const MTimeRecurrentYearly &	switchToStandardTime
	)

Constructor that creates a new unnamed timezone with an offset, and daylight saving time parameters defined.

No names are given to daylight time or to standard time. The given offsets are in seconds. This call does not use the operating system facilities to verify whether such timezone name exists, or whether it has the same standard offset as one supplied.

Parameters

standardOffset	Standard offset of this timezone from UTC in seconds. There is a check that the given offset is within range of -13 to 13 hours, which translates into range -46800 .. 46800, and it should be divisible by 5 minutes (300 seconds), or an exception will be raised.
daylightOffset	Daylight offset of this timezone from standard in seconds, typically 3600 seconds or one hour. There is a check that the given offset is within range of -3 to 3 hours (range -10800 .. 10800), and it should be divisible by 5 minutes (300 seconds), or an exception will be raised.
switchToDaylightTime	Yearly recurring local switch time, at which the daylight time starts. On the northern hemisphere this would typically be in March or April, while on the southern this is September or October.
switchToStandardTime	Yearly recurring local switch time, at which the daylight time ends. On the northern hemisphere this would typically be in September or October, while on the southern this is March or April.

Postcondition: InitializedFromDatabase property will be false.

MTimeZone::MTimeZone	(	int	standardOffset,
		int	daylightOffset,
		const MTimeRecurrentYearly &	switchToDaylightTime,
		const MTimeRecurrentYearly &	switchToStandardTime,
		const MStdString &	standardName,
		const MStdString &	daylightName
	)

Constructor that creates a new named timezone with daylight saving time defined.

All timezone properties are filled with parameters given in this constructor. This call does not use the operating system facilities to verify whether such timezone name exists, or whether it has the same standard offset as one supplied.

Parameters

standardOffset	Standard offset of this timezone from UTC in seconds. There is a check that the given offset is within range of -13 to 13 hours, which translates into range -46800 .. 46800, and it should be divisible by 5 minutes (300 seconds), or an exception will be raised.
daylightOffset	Daylight offset of this timezone from standard in seconds, typically 3600 seconds or one hour. There is a check that the given offset is within range of -3 to 3 hours (range -10800 .. 10800), and it should be divisible by 5 minutes (300 seconds), or an exception will be raised.
switchToDaylightTime	Yearly recurring local switch time, at which the daylight time starts. On the northern hemisphere this would typically be in March or April, while on the southern this is September or October.
switchToStandardTime	Yearly recurring local switch time, at which the daylight time ends. On the northern hemisphere this would typically be in September or October, while on the southern this is March or April.
standardName	The name to give to the newly created timezone object, does not have to be the one defined by the operating system.
daylightName	The daylight name to give to the newly created timezone object, does not have to be the one defined by the operating system.

Postcondition: InitializedFromDatabase property will be false.

MTimeZone::MTimeZone ( const MTimeZone & other )

Copy constructor, creates a timezone from a copy given.

After construction, a copy can be modified without influencing the computer timezone, or the timezone from which this copy is made.

Parameters

other Timezone object from which a copy shall be made.

Member Function Documentation

void MTimeZone::Clear ( )

Clear all fields of timezone.

Effectively creates a UTC timezone, however its name will be empty. The method is a convenience call before creating a custom timezone.

static MStdStringVector MTimeZone::GetAllTimeZoneDisplayNames ( )

static

Access the names of all globally present timezones, verbose representation.

A typical timezone display name will be "Eastern Standard Time | (GMT-05:00) Eastern Time (US & Canada)". Note that the display timezone name is locale dependent.

See also: GetAllTimeZoneNames - return short timezone names in English locale.; GetAllTimeZoneLocalNames - different from this, return shorter but localized timezone names.

static MStdStringVector MTimeZone::GetAllTimeZoneLocalNames ( )

static

Access the unprocessed local names of the timezone, a rather concise representation.

A typical timezone local name will be "(GMT-05:00) Eastern Time (US & Canada)". Note that the display timezone name is locale dependent.

See also: GetAllTimeZoneNames - return short timezone names in English locale.; GetAllTimeZoneDisplayNames - different from this, return longer and more verbose localized timezone names.

static MStdStringVector MTimeZone::GetAllTimeZoneNames ( )

static

Access the names of all globally present timezones, as defined by the operating system.

A typical timezone name will be "Eastern Standard Time". Note that the timezone name is not locale dependent.

See also: GetAllTimeZoneDisplayNames - return descriptive names suitable for displaying to the user.

static MTimeZone* MTimeZone::GetCurrent ( )

static

Access the globally present current computer timezone.

Important behavior of this property is that the computer timezone information is not fetched every time this property is accessed. Instead, the timezone value is cached to speed up the call. To support cases when the computer timezone changes from the administrative facility of the operating system, this property, when accessed, re-reads the timezone information, but no more often than each ten seconds. The value returned by this call will only reinitialize if the operating system's timezone changes.

This property can be used from multiple threads, however one should never attempt to change the timezone returned by this method.

While the computer timezone can be accessed, the MeteringSDK interface does not have means to change the current timezone as it is assumed to be an administrative task separate from applications built with MeteringSDK.

See also: SetFromCurrentSystem - forcefully reinitialize the timezone object from the current system timezone.

const MStdString& MTimeZone::GetDaylightName ( ) const

inline

Get daylight saving time name of this timezone object.

int MTimeZone::GetDaylightOffset ( ) const

inline

DST shift from Standard in seconds at the present year, typically 3600 seconds or one hour.

DST shift stays the same for any date of the year. One can use the method IsDST to determine if the given local time is in the DST. Local time DST status is not respected by this value, shall be taken into consideration separately. Normally DST makes a shift by one hour, but there are time zones when the shift is made by 30 minutes, or 2 hours.

Precondition: When set, there is a check that the given offset is within range. The correct daylight saving offset shall be in range -10800 .. 10800, which is -3 .. 3 hours, and it should be divisible by 300 seconds (5 minutes). Otherwise an exception will be thrown.

int MTimeZone::GetDaylightOffsetForYear ( int year ) const

Get the daylight offset in a given year.

If DST is not observed in the given year, zero is returned. Otherwise, if the given year has DST, this is the number of seconds the local time clock has to move at DST.

If the timezone has an offset change that is not DST related, zero is returned for such year.

Parameters

year	The year in four-digit format for which to determine the DST offset.

Returns: Offset in seconds.

const MStdString& MTimeZone::GetDisplayName ( ) const

inline

Locale dependent timezone name suitable for displaying to humans.

MTime MTimeZone::GetLocalTime ( ) const

Get local time according to this timezone.

Local time respects DST and the timezone shift.

int MTimeZone::GetLocalToUtcOffset ( const MTime & localTime ) const

Get the shift of the given local time from UTC, given the properties of the current timezone.

Different from GetDaylightOffset and GetStandardOffset, this service takes into consideration whether the given time is within DST period.

A closely related call GetUtcToLocalOffset will yield a reverse value unless the given timezone supports DST, and the localTime parameter is within a DST hour.

Local time ambiguity that takes place when DST is being switched back to Standard is resolved by this method in a way as if the given local time is on DST.

Invalid local time that takes place when DST is switched on from Standard is not reported as error.

Parameters

localTime The time for which to determine the current offset from UTC, has to be local time. If the current time is null, a No Value exception is thrown.

Returns: Offset in seconds

MTime MTimeZone::GetNextSwitchTime	(	const MTime &	anchorTime,
		bool	isTimeUtc = `false`
	)		const

Calculate the time at which the timezone offset will be switched.

The offset switch can be due to a regular and recurring DST switch, or it can be changed once at some particular date even without going on or off DST. It is very possible that the next switch time will appear in more than a year or two from the anchor date. For example, for "Russian Standard Time" and an anchor date "2011-04-01", the next switch time returned is "2014-10-25".

If there is no offset switch starting from the specified anchor time then this method returns null time (IsNull). Otherwise return the moment at which the offset switch is performed.

Not all operating systems offer an API to access switch times, and an algorithm will try to determine the switch time to the precision of one second by first walking forward by 64-day steps from the anchor and looking at returned local offsets. When the difference in offsets is found within the 64-day interval, a binary search for a switch time is performed. Therefore, the call can be slow, but no slower than one second on Android.

Different from GetSwitchToStandardTime and GetSwitchToDaylightTime, this API is supported on all operating systems.

Parameters

anchorTime	Time, local or UTC, that is the starting time from which to search for the switch time. Whether this is a UTC time is determined by isTimeUtc parameter.
isTimeUtc	Whether the anchor time and a return value are in UTC or Local, false by default.

Returns: Time, local or UTC, when the next switch will be performed by the timezone. The returned time can be null if there is no next switch time. Whether this is a UTC time is determined by isTimeUtc parameter.

See also: GetSwitchToStandardTime for the switch from DST to standard in recurring format; GetSwitchToDaylightTime for the switch from standard to DST time in recurring format

const MStdString& MTimeZone::GetStandardName ( ) const

inline

Standard timezone name, as used by this object.

int MTimeZone::GetStandardOffset ( ) const

inline

Timezone shift in seconds from UTC at the present year.

Timezone DST status is not respected by this value, shall be taken into consideration separately. This property modifies only this timezone setting, without affecting the computer timezone.

Precondition: When set, there is a check that the given offset is within range. The correct standard offset should be within range of -13 .. 13 hours, which translates into range -46800 .. 46800, and it should be divisible by 5 minutes (300 seconds). Otherwise an exception will be thrown.

int MTimeZone::GetStandardOffsetForTime ( const MTime & utcTime ) const

Get the standard offset for a given time.

If the time given is not on DST, this is equal to local offset. Otherwise, if the given time is on DST, this is the local offset at the time this DST period ends.

Parameters

utcTime The UTC time for which to determine the current standard offset. If the current time is null, a No Value exception is thrown.

Returns: Standard offset in seconds.

MTime MTimeZone::GetStandardTime ( ) const

Get standard time according to this timezone.

Standard time does not respect DST, if DST exists for this timezone.

int MTimeZone::GetSwitchTimeOffsetChange	(	const MTime &	time,
		bool	isTimeUtc = `false`
	)		const

Return the number of seconds added or subtracted around the given switch time.

Parameters

time	Switch time coming from GetNextSwitchTime or by any other means. Whether this is a UTC or local is determined by isTimeUtc parameter. It is not an error to give a time at which no switch is performed, in this case the returned value will be zero.
isTimeUtc	Whether the anchor time and a return value are in UTC or Local, false by default.

Returns: Seconds added or subtracted by the current timezone at a given time. If the given time is not a switch time then the returned value is zero.

MTimeRecurrentYearly& MTimeZone::GetSwitchToDaylightTime ( )

The recurring local time where time goes from Standard to DST.

Many timezones regularly change their DST rules, and when this property returns null time it does not mean there are no DST switches. Furthermore, this recurring local switch time can be calculated internally based on the switch time data in the coming three years from currennt date.

See also: GetSwitchToStandardTime for the switch to standard from DST local time in recurring format.; GetNextSwitchTime returns MTime object with the DST switch time that will be occurring in the future.; HasSwitchTimes tells if the timezone has any transitions, regular or not, in the past or in the future.; SupportsDST tells if the timezone has DST related switches currently or in the future.

MTimeRecurrentYearly& MTimeZone::GetSwitchToStandardTime ( )

The recurring local time where time goes from DST back to Standard.

Many timezones regularly change their DST rules, and when this property returns null time it does not mean there are no DST switches. Furthermore, this recurring local switch time can be calculated internally based on the switch time data in the coming three years from currennt date.

See also: GetSwitchToDaylightTime for the switch from standard to DST local time in recurring format.; GetNextSwitchTime returns MTime object with the DST switch time that will be occurring in the future.; HasSwitchTimes tells if the timezone has any transitions, regular or not, in the past or in the future.; SupportsDST tells if the timezone has DST related switches currently or in the future.

int MTimeZone::GetUtcToLocalOffset ( const MTime & utcTime ) const

Get the shift of the given UTC time from Local, given the properties of the current timezone.

Different from GetDaylightOffset and GetStandardOffset, this service takes into consideration whether the given time is within DST period.

A closely related call GetLocalToUtcOffset will yield a reverse value unless the given timezone supports DST, and the utcTime parameter is within a DST hour.

Parameters

utcTime The time for which to determine the current offset from Local, has to be UTC time. If the current time is null, a No Value exception is thrown.

Returns: Offset in seconds

bool MTimeZone::HasSwitchTimes ( ) const

Whether the local timezone has any switch times in the past or in the future, related to DST or not.

When this property is false the timezone has no DST switches, or any other changes to the offset.

See also: SupportsDST tells if the timezone has DST related switches currently or in the future.

bool MTimeZone::InitializedFromDatabase ( ) const

inline

Whether the timezone was initialized from the operating system standard timezone database, or directly specified by the user.

This flag will be true only if the timezone is loaded from the internal timezone database, as present in the OS. Once the timezone is loaded from the database, any attempt to change any of its properties leads to setting this flag back to false.

bool MTimeZone::IsDST	(	const MTime &	time,
		bool	isTimeUtc = `false`
	)		const

True will mean that according to this timezone, the given time is in DST.

When the service takes the local time, as determined by the second parameter being false, and when the switch from Standard to DST occurs, there is a range of impossible local time values (typically an hour). By convention, since it is already after the DST switch, this time range resolves into a time as if DST switch has occurred, and for such time IsDST will return True. When DST switches into Local, and the clock is moved backwards, there is an ambiguous local time, and for such time IsDST will again return True.

When the service takes a UTC time, as determined by the second parameter being true, there is no ambiguity.

Parameters

time	The time for which to determine if it fits within DST period. If the current time is null, an exception is thrown. Whether this is a UTC or local time is determined by optional parameter isTimeUtc, which is false by default (local time if not present).
isTimeUtc	whether the given time is in UTC. When absent, this is false, and the time is given in local format.

Returns: bool Whether the given local or UTC time is within the Daylight Saving Time range.

MTime MTimeZone::LocalToStandard ( const MTime & time ) const

Convert the given time from Local to Standard, by possibly applying a DST shift.

The DST offset is applied only if it is defined, and the given time is in the DST range.

Parameters

time	Local time to convert to Standard according to current timezone rules. It is an expectation that the given time is a local one, while of course this cannot be checked. The object shall not be null, or an exception is thrown.

See also: UtcToLocal - Convert UTC time to local.; LocalToUtc - Convert local time to UTC.; UtcToStandard - Convert UTC time to Standard, without respecting the DST offset and switch time.; StandardToUtc - Convert Standard time to UTC, without respecting the DST offset and switch time.; StandardToLocal - Convert Standard time to Local by possibly applying a DST shift.

MTime MTimeZone::LocalToUtc ( const MTime & time ) const

Convert the given time from Local to UTC, using this locale.

The standard offset and DST offset are applied if the given time fits in the DST range.

Local time ambiguity that takes place when DST is being switched back to Standard is resolved by this method in a way as if the given local time is on DST.

Invalid local time that takes place when DST is switched on from Standard is not reported as error.

Parameters

time	Local time to convert to UTC according to current timezone rules. It is an expectation that the given time is a local one, while of course this cannot be checked. The object shall not be null, or an exception is thrown.

See also: UtcToLocal - Convert UTC time to local.; UtcToStandard - Convert UTC time to Standard, without respecting the DST offset and switch time.; StandardToUtc - Convert Standard time to UTC, without respecting the DST offset and switch time.; LocalToStandard - Convert Local time to Standard by possibly applying a DST shift.; StandardToLocal - Convert Standard time to Local by possibly applying a DST shift.

MTimeZone& MTimeZone::operator= ( const MTimeZone & other )

Assignment operator, assigns one timezone into another.

Assignment to a current timezone only changes the object instance, it does not change the timezone in the computer.

Parameters

other Timezone object from which all properties of this timezone shall be initialized.

void MTimeZone::SetByName ( const MStdString & name )

Sets the current timezone using the name given.

The operating system timezone names can be obtained by GetAllTimeZoneNames. Also, the timezone name is not the same as standard timezone name or daylight timezone name as all three are different. This class does not set the current timezone of the operating system.

Parameters

name	The timezone name, as known by the operating system. If the name is unknown, an exception is thrown.

Postcondition: InitializedFromDatabase property will be true.

void MTimeZone::SetDaylightName ( const MStdString & name )

Get daylight saving time name of this timezone object.

void MTimeZone::SetDaylightOffset ( int offset )

DST shift from Standard in seconds at the present year, typically 3600 seconds or one hour.

DST shift stays the same for any date of the year. One can use the method IsDST to determine if the given local time is in the DST. Local time DST status is not respected by this value, shall be taken into consideration separately. Normally DST makes a shift by one hour, but there are time zones when the shift is made by 30 minutes, or 2 hours.

Precondition: When set, there is a check that the given offset is within range. The correct daylight saving offset shall be in range -10800 .. 10800, which is -3 .. 3 hours, and it should be divisible by 300 seconds (5 minutes). Otherwise an exception will be thrown.

void MTimeZone::SetDisplayName ( const MStdString & name )

Locale dependent timezone name suitable for displaying to humans.

void MTimeZone::SetFromCurrentSystem ( )

Sets the current timezone from the current system timezone.

This call updates this object from the computer's current timezone information.

void MTimeZone::SetInitializedFromDatabase ( bool yes )

inline

Whether the timezone was initialized from the operating system standard timezone database, or directly specified by the user.

This flag will be true only if the timezone is loaded from the internal timezone database, as present in the OS. Once the timezone is loaded from the database, any attempt to change any of its properties leads to setting this flag back to false.

void MTimeZone::SetStandardName ( const MStdString & )

Standard timezone name, as used by this object.

void MTimeZone::SetStandardOffset ( int offset )

Timezone shift in seconds from UTC at the present year.

Timezone DST status is not respected by this value, shall be taken into consideration separately. This property modifies only this timezone setting, without affecting the computer timezone.

Precondition: When set, there is a check that the given offset is within range. The correct standard offset should be within range of -13 .. 13 hours, which translates into range -46800 .. 46800, and it should be divisible by 5 minutes (300 seconds). Otherwise an exception will be thrown.

static MStdString MTimeZone::StandardNameIanaToWindows ( const MStdString & ianaName )

static

Return a correspondent Windows timezone name from IANA timezone name.

Windows and IANA timezone names are both locale independent, always in English. The mapping is hard-coded, and can get outdated in old software versions. Therefore, it is not guaranteed that the given or returned name exist in the current operating system. Empty string is returned if the correspondent name does not exist.

Parameters

ianaName IANA timezone name such as "America/New_York".

Returns: Windows name, a string such as "Eastern Standard Time" or an empty string if there is no mapping for a given name.

static MStdString MTimeZone::StandardNameWindowsToIana ( const MStdString & windowsName )

static

Return a correspondent IANA timezone name from Windows timezone name.

Windows and IANA timezone names are both locale independent, always in English. The mapping is hard-coded, and can get outdated in old software versions. Therefore, it is not guaranteed that the given or returned name exist in the current operating system. Empty string is returned if the correspondent name does not exist.

Parameters

windowsName Windows timezone name such as "Eastern Standard Time".

Returns: IANA name, a string such as "America/New_York" or an empty string if there is no mapping for a given name.

MTime MTimeZone::StandardToLocal ( const MTime & time ) const

Convert the given time from Standard to Local, by possibly applying a DST shift.

The DST offset is applied only if it is defined, and the given time is in the DST range.

Parameters

time	Standard time to convert to local according to current timezone rules. It is an expectation that the given time is a standard one, while of course this cannot be checked. The object shall not be null, or an exception is thrown.

See also: UtcToLocal - Convert UTC time to local.; LocalToUtc - Convert local time to UTC.; UtcToStandard - Convert UTC time to Standard, without respecting the DST offset and switch time.; StandardToUtc - Convert Standard time to UTC, without respecting the DST offset and switch time.; LocalToStandard - Convert Local time to Standard by possibly applying a DST shift.

MTime MTimeZone::StandardToUtc ( const MTime & time ) const

Convert the given time from Standard to UTC, without respecting the DST offset and switch time.

The standard offset is applied. DST has no effect irregardless of whether or not it is defined.

Parameters

time	Standard time to convert to UTC according to current timezone rules. It is an expectation that the given time is a standard one, while of course this cannot be checked. The object shall not be null, or an exception is thrown.

See also: UtcToLocal - Convert UTC time to local.; LocalToUtc - Convert local time to UTC.; UtcToStandard - Convert UTC time to Standard, without respecting the DST offset and switch time.; StandardToLocal - Convert Standard time to Local by possibly applying a DST shift.; LocalToStandard - Convert Local time to Standard by possibly applying a DST shift.

bool MTimeZone::SupportsDST ( ) const

Whether the local timezone has a notion of DST currently, and in the future.

When this property is true, the timezone has times currently or in the future where IsDST is true. When this property is false the timezone has no daylight saving related switches currently, or in the future. The timezone can still have DST in the past, or it can have transitions in the future unrelated to DST.

See also: HasSwitchTimes tells if the timezone has any transitions, regular or not, in the past or in the future.

MTime MTimeZone::UtcToLocal ( const MTime & time ) const

Convert the given time from UTC to Local, using this timezone information.

The standard offset and DST offset are applied if the given time fits in the DST range.

Parameters

time	UTC time to convert to Local according to current timezone rules. It is an expectation that the given time is a UTC one, while of course this cannot be checked. The object shall not be null, or an exception is thrown.

See also: LocalToUtc - Convert local time to UTC.; UtcToStandard - Convert UTC time to Standard, without respecting the DST offset and switch time.; StandardToUtc - Convert Standard time to UTC, without respecting the DST offset and switch time.; LocalToStandard - Convert Local time to Standard by possibly applying a DST shift.; StandardToLocal - Convert Standard time to Local by possibly applying a DST shift.

MTime MTimeZone::UtcToStandard ( const MTime & time ) const

Convert the given time from UTC to Standard, without respecting the DST offset and switch time.

The standard offset is applied. DST has no effect irregardless of whether or not it is defined.

Parameters

time	UTC time to convert to Standard according to current timezone rules. It is an expectation that the given time is a local one, while of course this cannot be checked. The object shall not be null, or an exception is thrown.

See also: UtcToLocal - Convert UTC time to local.; LocalToUtc - Convert local time to UTC.; StandardToUtc - Convert Standard time to UTC, without respecting the DST offset and switch time.; LocalToStandard - Convert Local time to Standard by possibly applying a DST shift.; StandardToLocal - Convert Standard time to Local by possibly applying a DST shift.

Public Member Functions

Static Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation