Date_TimeZone (Constructor) [line 321]
void Date_TimeZone(
string
$ps_id)
|
|
Constructor
Creates a new Date::TimeZone object, representing the time zone specified in $id.
If the supplied ID is invalid, the created time zone is "UTC".
A note about time zones of the form 'Etc/*' (quoted from the public domain 'tz' data-base (see ftp://elsie.nci.nih.gov/pub/tzdata2007i.tar.gz [file 'etcetera']):
These entries are mostly present for historical reasons, so that people in areas not otherwise covered by the tz files could use a time zone that was right for their area. These days, the tz files cover almost all the inhabited world, and the only practical need now for the entries that are not on UTC are for ships at sea that cannot use POSIX TZ settings.
Etc/GMT (GMT) Etc/UTC (UTC) Etc/UCT (UCT)
The following link uses older naming conventions, but it belongs here. We want this to work even on installations that omit the other older names.
Etc/GMT (equivalent to GMT)
Etc/UTC (equivalent to Etc/Universal) Etc/UTC (equivalent to Etc/Zulu)
Etc/GMT (equivalent to Etc/Greenwich) Etc/GMT (equivalent to Etc/GMT-0) Etc/GMT (equivalent to Etc/GMT+0) Etc/GMT (equivalent to Etc/GMT0)
We use POSIX-style signs in the Zone names and the output abbreviations, even though this is the opposite of what many people expect. POSIX has positive signs west of Greenwich, but many people expect positive signs east of Greenwich. For example, TZ='Etc/GMT+4' uses the abbreviation "GMT+4" and corresponds to 4 hours behind UTC (i.e. west of Greenwich) even though many people would expect it to mean 4 hours ahead of UTC (i.e. east of Greenwich).
In the draft 5 of POSIX 1003.1-200x, the angle bracket notation (which is not yet supported by the tz code) allows for TZ='<GMT-4>+4'; if you want time zone abbreviations conforming to ISO 8601 you can use TZ='<-0400>+4'. Thus the commonly-expected offset is kept within the angle bracket (and is used for display) while the POSIX sign is kept outside the angle bracket (and is used for calculation).
Do not use a TZ setting like TZ='GMT+4', which is four hours behind GMT but uses the completely misleading abbreviation "GMT".
Earlier incarnations of this package were not POSIX-compliant, and we did not want things to change quietly if someone accustomed to the old way uses the codes from previous versions so we moved the names into the Etc subdirectory.
Etc/GMT-14 (14 hours ahead of Greenwich) Etc/GMT-13 (13) Etc/GMT-12 (12) Etc/GMT-11 (11) Etc/GMT-10 (10) Etc/GMT-9 (9) Etc/GMT-8 (8) Etc/GMT-7 (7) Etc/GMT-6 (6) Etc/GMT-5 (5) Etc/GMT-4 (4) Etc/GMT-3 (3) Etc/GMT-2 (2) Etc/GMT-1 (1) Etc/GMT+1 (1 hour behind Greenwich) Etc/GMT+2 (2) Etc/GMT+3 (3) Etc/GMT+4 (4) Etc/GMT+5 (5) Etc/GMT+6 (6) Etc/GMT+7 (7) Etc/GMT+8 (8) Etc/GMT+9 (9) Etc/GMT+10 (10) Etc/GMT+11 (11) Etc/GMT+12 (12)
Parameters:
getAvailableIDs [line 1025]
Returns the list of valid time zone id strings
getDefault [line 420]
Returns a TimeZone object representing the system default time zone
The system default time zone is initialized during the loading of this file.
getDSTLongName [line 1137]
Returns the DST long name for this time zone, e.g.
'Central Daylight Time'
getDSTSavings [line 929]
Get the DST offset for this time zone
Returns the DST offset of this time zone, in milliseconds, if the zone observes DST, zero otherwise. Currently the DST offset is hard-coded to one hour.
getDSTShortName [line 1152]
string getDSTShortName(
)
|
|
Returns the DST short name for this time zone, e.g. 'CDT'
getID [line 1040]
Returns the time zone id for this time zone, i.e. "America/Chicago"
getLongName [line 1067]
string getLongName(
[mixed
$pm_insummertime = false])
|
|
Returns the long name for this time zone
Long form of time zone name, e.g. 'Greenwich Mean Time'. Additionally a Date object can be passed in which case the Summer time name will be returned instead if the date falls in Summer time, e.g. 'British Summer Time'.
N.B. this is not a unique identifier - for this purpose use the time zone ID.
Parameters:
getOffset [line 996]
int getOffset(
mixed
$pm_insummertime)
|
|
Returns the DST-corrected offset from UTC for the given date
Gets the offset to UTC for a given date/time, taking into account daylight savings time, if the time zone observes it and if it is in effect.
N.B. that the offset is calculated historically and in the future according to the current Summer time rules, and so this function is proleptically correct, but not necessarily historically correct. (Although if you want to be correct about times in the distant past, this class is probably not for you because the whole notion of time zones does not apply, and historically there are so many time zone changes, Summer time rule changes, name changes, calendar changes, that calculating this sort of information is beyond the scope of this package altogether.)
Parameters:
getRawOffset [line 962]
Returns the raw (non-DST-corrected) offset from UTC/GMT for this time zone
getShortName [line 1107]
string getShortName(
[mixed
$pm_insummertime = false])
|
|
Returns the short name for this time zone
Returns abbreviated form of time zone name, e.g. 'GMT'. Additionally a Date object can be passed in which case the Summer time name will be returned instead if the date falls in Summer time, e.g. 'BST'.
N.B. this is not a unique identifier - for this purpose use the time zone ID.
Parameters:
getSummerTimeEndDay [line 1250]
string getSummerTimeEndDay(
)
|
|
Returns the a code representing the day on which Summer time ends
getSummerTimeEndMonth [line 1233]
int getSummerTimeEndMonth(
)
|
|
Returns the month number in which Summer time ends
getSummerTimeEndTime [line 1267]
int getSummerTimeEndTime(
)
|
|
Returns the time of day at which which Summer time ends
getSummerTimeStartDay [line 1192]
string getSummerTimeStartDay(
)
|
|
Returns the a code representing the day on which Summer time starts
Returns a string in one of the following forms:
5 the fifth of the month lastSun the last Sunday in the month lastMon the last Monday in the month Sun>=8 first Sunday on or after the 8th Sun<=25 last Sunday on or before the 25th
getSummerTimeStartMonth [line 1168]
int getSummerTimeStartMonth(
)
|
|
Returns the month number in which Summer time starts
getSummerTimeStartTime [line 1216]
int getSummerTimeStartTime(
)
|
|
Returns the time of day at which which Summer time starts
The returned time is an offset, in milliseconds, from midnight UTC. Note that the offset can be negative, which represents the fact that the time zone is East of Greenwich, and that when the clocks change locally, the time in Greenwich is actually a time belonging to the previous day in UTC. This, obviously, is unhelpful if you want to know the local time at which the clocks change, but it is of immense value for the purpose of calculation.
hasDaylightTime [line 602]
Returns true if this zone observes daylight savings time
inDaylightTime [line 739]
bool inDaylightTime(
object
$pm_date, [bool
$pb_repeatedhourdefault = false])
|
|
Is the given date/time in DST for this time zone
Works for all years, positive and negative. Possible problems are that when the clocks go forward, there is an invalid hour which is skipped. If a time in this hour is specified, this function returns an error. When the clocks go back, there is an hour which is repeated, that is, the hour is gone through twice - once in Summer time and once in standard time. If this time is specified, then this function returns '$pb_repeatedhourdefault', because there is no way of knowing which is correct, and both possibilities are equally likely.
Also bear in mind that the clocks go forward at the instant of the hour specified in the time-zone array below, and if this exact hour is specified then the clocks have actually changed, and this function reflects this.
Parameters:
inDaylightTimeStandard [line 848]
bool inDaylightTimeStandard(
object
$pm_date)
|
|
Returns whether the given date/time in local standard time is in Summer time
For example, if the clocks go forward at 1.00 standard time, then if the specified date/time is at 1.00, the function will return true, although the correct local time will actually be 2.00.
This function is reliable for all dates and times, unlike the related function 'inDaylightTime()', which will fail if passed an invalid time (the skipped hour) and will be wrong half the time if passed an ambiguous time (the repeated hour).
Parameters:
isEqual [line 527]
bool isEqual(
object
$tz)
|
|
Is this time zone equal to another
Tests to see if this time zone is equal (ids match) to a given Date_TimeZone object.
Parameters:
isEquivalent [line 559]
bool isEquivalent(
object
$pm_tz)
|
|
Is this time zone equivalent to another
Tests to see if this time zone is equivalent to a given time zone object. Equivalence in this context consists in the two time zones having:
an equal offset from UTC in both standard and Summer time (if the time zones observe Summer time) the same Summer time start and end rules, that is, the two time zones must switch from standard time to Summer time, and vice versa, on the same day and at the same time
Parameters:
isValidID [line 499]
bool isValidID(
string
$ps_id)
|
|
Tests if given time zone ID (e.g. 'London/Europe') is valid and unique
Checks if given ID is either represented in the $_DATE_TIMEZONE_DATA time zone data, or is a UTC offset in one of the following forms, i.e. an offset with no geographical or political base:
UTC[+/-][hh]:[mm] - e.g. UTC+03:00 UTC[+/-][hh][mm] - e.g. UTC-0530 UTC[+/-][hh] - e.g. UTC+03 UTC[+/-][h] - e.g. UTC-1 (the last is not ISO 8601 standard but is the preferred form)
N.B. these are not sanctioned by any ISO standard, but the form of the offset itself, i.e. the part after the characters 'UTC', is the ISO 8601 standard form for representing this part.
The form '[+/-][h]' is not ISO conformant, but ISO 8601 only defines the form of the time zone offset of a particular time, that is, it actually defines the form '<time>UTC[+/-][hh]', and its purview does not apparently cover the name of the time zone itself. For this there is no official international standard (or even a non- international standard). The closest thing to a sanctioning body is the 'tz' database (http://www.twinsun.com/tz/tz-link.htm) which is run by volunteers but which is heavily relied upon by various programming languages and the internet community. However they mainly define geographical/political time zone names of the form 'London/Europe' because their main aim is to collate the time zone definitions which are set by individual countries/states, not to prescribe any standard.
However it seems that the de facto standard to describe time zones as non-geographically/politically-based areas where the local time on all clocks reads the same seems to be the form 'UTC[+/-][h]' for integral numbers of hours, and 'UTC[+/-][hh]:[mm]' otherwise. (See http://en.wikipedia.org/wiki/List_of_time_zones)
N.B. 'GMT' is also commonly used instead of 'UTC', but 'UTC' seems to be technically preferred. GMT-based IDs still exist in the 'tz data-base', but beware of POSIX-style offsets which are the opposite way round to what people normally expect.
Parameters:
setDefault [line 437]
void setDefault(
string
$id)
|
|
Sets the system default time zone to the time zone in $id
Parameters:
