Qore::TimeZone Class Reference

The TimeZone class provides access to time zone functionality. More...

Inheritance diagram for Qore::TimeZone:

Public Member Methods
int	UTCOffset ()
	Returns the number of seconds east of UTC for the zone; negative numbers indicate a zone west of UTC. More...
	constructor (string region)
	Creates the TimeZone object based on the region name (ex: "America/Chicago") More...
	constructor (softint seconds_east)
	Creates the TimeZone object based on the number of seconds east of UTC (3600 = UTC +01) More...
	copy ()
	Creates a copy of the TimeZone object. More...
date	date (softint secs, softint us=0)
	Returns the equivalent date in the time zone of the current object. More...
date	date (date d)
	Returns the equivalent date in the time zone of the current object. More...
date	date (string dtstr)
	Returns the equivalent date in the time zone of the current object. More...
date	date (string dtstr, string mask)
	Returns a date/time value in the current TimeZone corresponding to parsing a string argument according to a format mask. More...
date	dateMs (softint ms)
	Returns a date in the object's zone based on an offsets in milliseconds from 1970-01-01Z. More...
date	dateUs (softint us)
	Returns a date in the object's zone based on an offsets in microseconds from 1970-01-01Z. More...
bool	hasDST ()
	Returns True if the zone has daylight saving time rules, False if not. More...
string	region ()
	Returns the region name as a string; if the current zone is based on a UTC offset, then the UTC offset is returned as a string like "+01:00". More...
Public Member Methods inherited from Qore::Serializable
	constructor ()
	The constructor does not perform any action; this class is just used to mark a class as serializable by inheriting this class.
	copy ()
	The copy constructor does not perform any action; this class is just used to mark a class as serializable by inheriting this class.
	serialize (OutputStream stream)
	converts the object to binary data representing the object More...
binary	serialize ()
	converts the object to binary data representing the object More...
hash< SerializationInfo >	serializeToData ()
	converts the object to a serialization hash representing the object More...

Static Public Member Methods
static TimeZone	get ()
	Returns a TimeZone object for the current time zone. More...
static nothing	set (TimeZone zone)
	Sets the time zone for the current Program object from a TimeZone object. More...
static nothing	setRegion (string region)
	Sets the time zone for the current Program object from a time zone region name. More...
static nothing	setUTCOffset (softint seconds_east)
	Sets the time zone for the current Program object from an integer offset in seconds east of UTC. More...
Static Public Member Methods inherited from Qore::Serializable
static auto	deserialize (InputStream stream)
	Deserializes data produced with serialize() and returns the value represented by the data. More...
static auto	deserialize (binary bin)
	Deserializes data produced with serialize() and returns the value represented by the data. More...
static auto	deserialize (string bin)
	Deserializes data produced with serialize() and returns the value represented by the data. More...
static auto	deserialize (hash< SerializationInfo > data)
	Deserializes data produced with serializeToData() and returns the value represented by the data. More...
static hash< SerializationInfo >	deserializeToData (InputStream stream)
	Deserializes data produced with serialize() and returns the value represented by the data. More...
static hash< SerializationInfo >	deserializeToData (binary bin)
	Deserializes data produced with serialize() and returns the value represented by the data. More...
static	serialize (auto val, OutputStream stream)
	serializes the data and writes the serialized data to the given output stream More...
static binary	serialize (auto val)
	serializes the data and returns the serialized data as a binary object More...
static hash< SerializationInfo >	serializeToData (auto val)
	converts the value to a serialization hash representing the value More...

Detailed Description

The TimeZone class provides access to time zone functionality.

TimeZone objects based on zoneinfo region files (on UNIX) or registry information (on Windows) can have daylight savings time information; those based on UTC offsets have none.

The TimeZone class supports data serialization; deserialization can fail if the object is based on a region that is not present on the target machine.

Member Function Documentation

constructor() [1/2]

Qore::TimeZone::constructor

(

softint

seconds_east

)

Creates the TimeZone object based on the number of seconds east of UTC (3600 = UTC +01)

Parameters

seconds_east

The number of seconds east of UTC for the time zone; for zones west of UTC, use negative numbers

Example:

TimeZone tz(3600);

constructor() [2/2]

Qore::TimeZone::constructor

(

string

region

)

Creates the TimeZone object based on the region name (ex: "America/Chicago")

Parameters

region

The region name for the time zone (ex: "America/Chicago"); if the zoneinfo file for the region cannot be found or parsed (on UNIX) or if the registry entry cannot be found (on Windows), then an exception is thrown

Note

On Windows zoneinfo region names (ex: "Europe/Prague") are converted to registry entries under HKEY_LOCAL_MACHINE SOFTWARE\Microsoft\Windows NT\CurrentVersion\Time Zones (ex: "Central Europe Standard Time"); on Windows you can also pass a registry key directly (ex: "Central Europe Standard Time") as the region, in this case it will be used to find the timezone info in registry, however the region name will then be converted to the first corresponding zoneinfo region according to alphabet (ex: "Central Europe Standard Time" -> "Europe/Belgrade"); if an absolute path to a file is given as the argument, then a zoneinfo file is read and parsed from the given location

Example:

TimeZone tz("Europe/Prague");

Exceptions

TZINFO-ERROR	Unable to read zoneinfo file; invalid file magic; error parsing zoneinfo file, etc
ILLEGAL-FILESYSTEM-ACCESS	thrown if a path was passed for region and the Qore::PO_NO_FILESYSTEM sandboxing restriction is set

Since

Qore 0.8.12 an absolute path to a zoneinfo file can be provided if the Qore::PO_NO_FILESYSTEM sandboxing restriction is not in place (checked at runtime if an absolute path is passed)

copy()

Qore::TimeZone::copy

(

)

Creates a copy of the TimeZone object.

Example:

TimeZone newzone = tz.copy();

date() [1/4]

date Qore::TimeZone::date

(

date

d

)

Returns the equivalent date in the time zone of the current object.

Code Flags:

CONSTANT

Parameters

d	A date that will be used to create the date in the time zone of the objects; the same point in time will be returned but in the time zone of the object

Example:

date dt = tz.date(2012-01-01T13:56:23+01:00);

date() [2/4]

date Qore::TimeZone::date	(	softint	secs,
		softint	us = 0
	)

Returns the equivalent date in the time zone of the current object.

Code Flags:

CONSTANT

Parameters

secs	offset are in seconds from 1970-01-01Z
us	offset are in microseconds from 1970-01-01Z

Example:

date dt = tz.date(secs);

date() [3/4]

date Qore::TimeZone::date

(

string

dtstr

)

Returns the equivalent date in the time zone of the current object.

Code Flags:

CONSTANT

Parameters

dtstr

The string to be used to return a date in the object's time zone

Example:

date dt = tz.date("2012-01-01T13:56:23");

Since

Qore 0.8.4

date() [4/4]

date Qore::TimeZone::date	(	string	dtstr,
		string	mask
	)

Returns a date/time value in the current TimeZone corresponding to parsing a string argument according to a format mask.

Code Flags:

RET_VALUE_ONLY

Parameters

dtstr	a string giving a date
mask	the mask for the date value; see Date Mask Format for information on the format of the format mask

Returns

the date/time value in the current TimeZone corresponding to parsing the dtstr string argument according to mask serving as a format mask

Example:

TimeZone tz("Europe/London");
printf("%y\n", tz.date("05/02/2012", "DD/MM/YYYY")); # outputs: 2012-02-05 00:00:00 Sun Z (GMT)

Exceptions

DATE-CONVERT-ERROR

invalid mask specification

See also

similar to but more useful than Qore::date(string, string)

Since

Qore 0.8.6

dateMs()

date Qore::TimeZone::dateMs

(

softint

ms

)

Returns a date in the object's zone based on an offsets in milliseconds from 1970-01-01Z.

Code Flags:

CONSTANT

Parameters

ms	an offsets in milliseconds from 1970-01-01Z

Returns

a date in the object's zone based on the given offsets in milliseconds from 1970-01-01Z

Example:

date dt = tz.dateMs(offset_ms);

dateUs()

date Qore::TimeZone::dateUs

(

softint

us

)

Returns a date in the object's zone based on an offsets in microseconds from 1970-01-01Z.

Code Flags:

CONSTANT

Parameters

us	an offsets in microseconds from 1970-01-01Z

Returns

a date in the object's zone based on the given offsets in microseconds from 1970-01-01Z

Example:

date dt = tz.dateUs(offset_uss);

get()

static TimeZone Qore::TimeZone::get ( )

static

Returns a TimeZone object for the current time zone.

Returns

a TimeZone object for the current time zone

Code Flags:

CONSTANT

Example:

TimeZone tz = TimeZone::get();

hasDST()

bool Qore::TimeZone::hasDST

(

)

Returns True if the zone has daylight saving time rules, False if not.

TimeZone objects based on zoneinfo region files (on UNIX) or registry information (on Windows) can have (but do not necessarily have) daylight savings time information; those based on UTC offsets have none

Returns

True if the current zone has daylight saving time rules, False if not

Code Flags:

CONSTANT

Example:

bool hasdst = tz.hasDST();

region()

string Qore::TimeZone::region

(

)

Returns the region name as a string; if the current zone is based on a UTC offset, then the UTC offset is returned as a string like "+01:00".

Returns

the region name as a string; if the current zone is based on a UTC offset, then the UTC offset is returned as a string like "+01:00"

Code Flags:

CONSTANT

Example:

string region = tz.region();

set()

static nothing Qore::TimeZone::set ( TimeZone  zone )

static

Sets the time zone for the current Program object from a TimeZone object.

Restrictions:

Qore::PO_NO_LOCALE_CONTROL

Parameters

zone	the time zone to set

Example:

TimeZone tz("Europe/Prague");
TimeZone::set(tz);

setRegion()

static nothing Qore::TimeZone::setRegion ( string  region )

static

Sets the time zone for the current Program object from a time zone region name.

Restrictions:

Qore::PO_NO_LOCALE_CONTROL

Parameters

region

the region name to set

Note

On Windows you can use both zoneinfo region names (ex: "Europe/Prague") as well as the Windows registry keys under HKEY_LOCAL_MACHINE SOFTWARE\Microsoft\Windows NT\CurrentVersion\Time Zones (ex: "Central Europe Standard Time"); note that in this case the Windows-style names will only be used to load the timezone info from registry and the name will then be converted to the first corresponding zoneinfo region according to alphabet (ex: "Central Europe Standard Time" -> "Europe/Belgrade").

Example:

TimeZone::setRegion("Europe/Prague");

setUTCOffset()

static nothing Qore::TimeZone::setUTCOffset ( softint  seconds_east )

static

Sets the time zone for the current Program object from an integer offset in seconds east of UTC.

Restrictions:

Qore::PO_NO_LOCALE_CONTROL

Parameters

seconds_east

the number of seconds east of UTC for the new time zone (negative numbers give seconds west of UTC)

Example:

TimeZone::setUTCOffset(3600);

UTCOffset()

int Qore::TimeZone::UTCOffset

(

)

Returns the number of seconds east of UTC for the zone; negative numbers indicate a zone west of UTC.

Returns

the number of seconds east of UTC for the zone; negative numbers indicate a zone west of UTC

Code Flags:

CONSTANT

Example:

int offset = tz.UTCOffset();