4.13. TimeZone Class

4.13. TimeZone Class
Prev	Chapter 4. System Namespaces and Class Library	Next

The TimeZone class provides access to time zone functionality.

TimeZone objects based on zoneinfo region files can have daylight savings time information; those based on UTC offsets have none.

Table 4.553. TimeZone Method Overview

Method	Except?	Description
`TimeZone::constructor(string $region)` `TimeZone::constructor(softint $secs_east)`	Y	Creates the TimeZone object based on the region name (ex: "America/Chicago") or the number of seconds east of UTC (3600 = UTC +01).
`TimeZone::destructor()`	N	Destroys the TimeZone object.
`TimeZone::copy()`	N	Creates a copy of the TimeZone object.
`int TimeZone::UTCOffset()`	N	Returns the number of seconds east of UTC for the zone; negative numbers indicate a zone west of UTC.
`bool TimeZone::hasDST()`	N	Returns `True` if the current zone has daylight saving's time rules, `False` if not. TimeZone objects based on zoneinfo region files can have (but do not necessarily have) daylight savings time information; those based on UTC offsets have none.
`string TimeZone::region()`	N	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".
`date TimeZone::date(softint $secs, softint $us = 0)` `date TimeZone::date(date $date)`	N	Returns the equivalent date in the current time zone; when using integer arguments, offsets are in seconds and microseconds from 1970-01-01Z.
`date TimeZone::dateMs(softint $ms)`	N	Returns a date in the object's zone based on an offset in milliseconds from 1970-01-01Z.
`date TimeZone::dateUs(softint $us)`	N	Returns a date in the object's zone based on an offset in microseconds from 1970-01-01Z.
`static TimeZone TimeZone::get()`	N	Returns the default time zone for the current execution context.
`static nothing TimeZone::set(TimeZone $zone)`	N	Sets the default time zone for the current execution context.
`static nothing TimeZone::setUTCOffset(softint $secs_east)`	N	Sets the default time zone for the current execution context based on the number of seconds east of UTC; for zones west of UTC, use negative numbers.
`static nothing TimeZone::setRegion(string $region)`	Y	Sets the default time zone for the current execution context from a zoneinfo region file; if there are errors reading or parsing the file, an exception is thrown.

4.13.1. TimeZone::constructor()

Synopsis

Creates the TimeZone object based on the region name (ex: "America/Chicago") or the UTC offset passed as the number of seconds east of UTC for the zone.

Prototype

TimeZone::constructor(string $region)

TimeZone::constructor(softint $secs_east)

Example

my TimeZone $tz("Europe/Prague");

Table 4.554. Arguments for TimeZone::constructor()

Argument	Description
`string $region`	The region name for the time zone (ex: "America/Chicago"); if the zoneinfo file for the region cannot be found or parsed, then an exception is thrown.
`softint $secs_east`	The number of seconds east of UTC for the time zone; for zones west of UTC, use negative numbers.

Table 4.555. Exceptions Thrown by TimeZone::constructor()

err	desc
`TZINFO-ERROR`	Unable to read zoneinfo file; invalid file magic; error parsing zoneinfo file, etc

4.13.2. TimeZone::destructor()

Synopsis

Destroys the TimeZone object.

Example

delete $tz;

4.13.3. TimeZone::copy()

Synopsis

Creates a copy of the TimeZone object.

Example

my TimeZone $newzone = $tz.copy();

4.13.4. TimeZone::UTCOffset()

Synopsis

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

Prototype

int TimeZone::UTCOffset()

Example

my int $offset = $tz.UTCOffset();

Table 4.556. Return Values for TimeZone::UTCOffset()

Return Type	Description
`int`	Returns the number of seconds east of UTC for the zone; negative numbers indicate a zone west of UTC.

4.13.5. TimeZone::hasDST()

Synopsis

Returns True if the current zone has daylight saving's time rules, False if not. TimeZone objects based on zoneinfo region files can have (but do not necessarily have) daylight savings time information; those based on UTC offsets have none.

Prototype

bool TimeZone::hasDST()

Example

my bool $hasdst = $tz.hasDST();

Table 4.557. Return Values for TimeZone::hasDST()

Return Type	Description
`bool`	Returns `True` if the current zone has daylight saving's time rules, `False` if not. TimeZone objects based on zoneinfo region files can have (but do not necessarily have) daylight savings time information; those based on UTC offsets have none.

4.13.6. TimeZone::region()

Synopsis

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".

Prototype

string TimeZone::region()

Example

my string $region = $tz.region();

Table 4.558. Return Values for TimeZone::region()

Return Type	Description
`string`	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".

4.13.7. TimeZone::date()

Synopsis

Returns the equivalent date in the current time zone; when using integer arguments, offsets are in seconds and microseconds from 1970-01-01Z.

Prototype

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

date TimeZone::date(date $date)

Example

my date $dt = $tz.date($other);

Table 4.559. Arguments for TimeZone::set()

Argument	Description
`softint $secs, softint $us = 0`	Offset in seconds and microseconds from 1970-01-01Z.
`date $date`	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.

Table 4.560. Return Values for TimeZone::date()

Return Type	Description
`date`	Returns the equivalent date in the current time zone; when using integer arguments, offsets are in seconds and microseconds from 1970-01-01Z.

4.13.8. TimeZone::dateMs()

Synopsis

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

Prototype

date TimeZone::dateMs(softint $ms)

Example

my date $dt = $tz.dateMs($ms);

Table 4.561. Return Values for TimeZone::dateMs()

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

4.13.9. TimeZone::dateUs()

Synopsis

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

Prototype

date TimeZone::dateUs(softint $us)

Example

my date $dt = $tz.dateUs($us);

Table 4.562. Return Values for TimeZone::dateUs()

Return Type	Description
`date`	Returns a date in the object's zone based on an offset in microseconds from 1970-01-01Z.

4.13.10. TimeZone::get()

Synopsis

Returns the default time zone for the current execution context.

Prototype

static TimeZoneTimeZone::get()

Example

my TimeZone $tz = TimeZone::get();

Table 4.563. Return Values for TimeZone::get()

Return Type	Description
`TimeZone`	Returns the default time zone for the current execution context.

4.13.11. TimeZone::set()

Synopsis

Sets the default time zone for the current execution context.

Argument	Description
`TimeZone $zone`	The default time zone to set for the current execution context.

4.13.12. TimeZone::setUTCOffset()

Synopsis

Sets the default time zone for the current execution context based on the number of seconds east of UTC; for zones west of UTC, use negative numbers.

Time zones set with this method cannot have any daylight savings time information; to set a zone with daylight savings time information, use TimeZone::setRegion() instead.

Prototype

static nothing TimeZone::setUTCOffset(softint $secs_east)

Example

The following examples are all equivalent, setting the time zone to +02 UTC:

TimeZone::setUTCOffset(7200);

TimeZone::setUTCOffset(2h);

TimeZone::setUTCOffset(PT2H);

Table 4.565. Arguments for TimeZone::setUTCOffset()

Argument	Description
`softint $secs_east`	The number of seconds east of UTC; for zones west of UTC, use negative numbers

4.13.13. static TimeZone::setRegion()

Synopsis

Sets the default time zone for the current execution context from a zoneinfo region file; if there are errors reading or parsing the file, an exception is thrown.

Prev	Up	Next
4.12. SSLCertificate Class	Home	4.14. SQL Constants