Debian Codegraph @

closure-library/closure/goog/i18n/timezone.js

raw
1 // Copyright 2008 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Functions to provide timezone information for use with
17 * date/time format.
18 */
19
20 goog.provide('goog.i18n.TimeZone');
21
22 goog.require('goog.array');
23 /** @suppress {extraRequire} goog.date.DateLike represents a Date or a
24 * goog.Date object. It is a parameter in the following methods:
25 * - getDaylightAdjustment
26 * - getGMTString
27 * - getLongName
28 * - getOffset
29 * - getRFCTimeZoneString
30 * - getShortName
31 * - isDaylightTime
32 * - getLongNameGMT
33 * - getGenericLocation
34 * Lint warns that this require is unnecessary but the closure compiler needs
35 * it in order to accept a Date or a goog.Date object as a goog.date.DateLike
36 * parameter in any of these methods. */
37 goog.require('goog.date.DateLike');
38 goog.require('goog.object');
39 goog.require('goog.string');
40
41
42
43 /**
44 * TimeZone class implemented a time zone resolution and name information
45 * source for client applications. The time zone object is initiated from
46 * a time zone information object. Application can initiate a time zone
47 * statically, or it may choose to initiate from a data obtained from server.
48 * Each time zone information array is small, but the whole set of data
49 * is too much for client application to download. If end user is allowed to
50 * change time zone setting, dynamic retrieval should be the method to use.
51 * In case only time zone offset is known, there is a decent fallback
52 * that only use the time zone offset to create a TimeZone object.
53 *
54 * @constructor
55 * @final
56 */
57 goog.i18n.TimeZone = function() {
58 /**
59 * The standard time zone id.
60 * @type {string}
61 * @private
62 */
63 this.timeZoneId_;
64
65
66 /**
67 * The standard, non-daylight time zone offset, in minutes WEST of UTC.
68 * @type {number}
69 * @private
70 */
71 this.standardOffset_;
72
73
74 /**
75 * An array of strings that can have 2 or 4 elements. The first two elements
76 * are the long and short names for standard time in this time zone, and the
77 * last two elements (if present) are the long and short names for daylight
78 * time in this time zone.
79 * @type {Array<string>}
80 * @private
81 */
82 this.tzNames_;
83
84
85 /**
86 * An object of 2 to 4 elements. The STD_* are always available, while the
87 * DST_* are only available when daylight saving time is available for this
88 * time zone.
89 * <ul>
90 * <li>STD_LONG_NAME_GMT: long GMT name for standard time</li>
91 * <li>STD_GENERIC_LOCATION: generic location for standard time</li>
92 * <li>DST_LONG_NAME_GMT: long GMT for daylight saving time</li>
93 * <li>DST_GENERIC_LOCATION: generic location for daylight saving time</li>
94 * </ul>
95 * @type { { STD_LONG_NAME_GMT:string, STD_GENERIC_LOCATION:string } |
96 * { STD_LONG_NAME_GMT:string, STD_GENERIC_LOCATION:string,
97 * DST_LONG_NAME_GMT:string, DST_GENERIC_LOCATION:string }
98 * }
99 * @private
100 */
101 this.tzNamesExt_;
102
103
104 /**
105 * This array specifies the Daylight Saving Time transitions for this time
106 * zone. This is a flat array of numbers which are interpreted in pairs:
107 * [time1, adjustment1, time2, adjustment2, ...] where each time is a DST
108 * transition point given as a number of hours since 00:00 UTC, January 1,
109 * 1970, and each adjustment is the adjustment to apply for times after the
110 * DST transition, given as minutes EAST of UTC.
111 * @type {Array<number>}
112 * @private
113 */
114 this.transitions_;
115 };
116
117
118 /**
119 * The number of milliseconds in an hour.
120 * @type {number}
121 * @private
122 */
123 goog.i18n.TimeZone.MILLISECONDS_PER_HOUR_ = 3600 * 1000;
124
125
126 /**
127 * Indices into the array of time zone names.
128 * @enum {number}
129 */
130 goog.i18n.TimeZone.NameType = {
131 STD_SHORT_NAME: 0,
132 STD_LONG_NAME: 1,
133 DLT_SHORT_NAME: 2,
134 DLT_LONG_NAME: 3
135 };
136
137
138 /**
139 * This factory method creates a time zone instance. It takes either an object
140 * containing complete time zone information, or a single number representing a
141 * constant time zone offset. If the latter form is used, DST functionality is
142 * not available.
143 *
144 * @param {number|Object} timeZoneData If this parameter is a number, it should
145 * indicate minutes WEST of UTC to be used as a constant time zone offset.
146 * Otherwise, it should be an object with these four fields:
147 * <ul>
148 * <li>id: A string ID for the time zone.
149 * <li>std_offset: The standard time zone offset in minutes EAST of UTC.
150 * <li>names: An array of four names (standard short name, standard long
151 * name, daylight short name, daylight long, name)
152 * <li>names_ext: A hash of four fields (standard long name gmt, daylight
153 * long name gmt, standard generic location, daylight generic
154 * location)
155 * <li>transitions: An array of numbers which are interpreted in pairs:
156 * [time1, adjustment1, time2, adjustment2, ...] where each time is
157 * a DST transition point given as a number of hours since 00:00 UTC,
158 * January 1, 1970, and each adjustment is the adjustment to apply
159 * for times after the DST transition, given as minutes EAST of UTC.
160 * </ul>
161 * @return {!goog.i18n.TimeZone} A goog.i18n.TimeZone object for the given
162 * time zone data.
163 */
164 goog.i18n.TimeZone.createTimeZone = function(timeZoneData) {
165 if (typeof timeZoneData == 'number') {
166 return goog.i18n.TimeZone.createSimpleTimeZone_(timeZoneData);
167 }
168 var tz = new goog.i18n.TimeZone();
169 tz.timeZoneId_ = timeZoneData['id'];
170 tz.standardOffset_ = -timeZoneData['std_offset'];
171 tz.tzNames_ = timeZoneData['names'];
172 tz.tzNamesExt_ = timeZoneData['names_ext'];
173 tz.transitions_ = timeZoneData['transitions'];
174 return tz;
175 };
176
177
178 /**
179 * This factory method creates a time zone object with a constant offset.
180 * @param {number} timeZoneOffsetInMinutes Offset in minutes WEST of UTC.
181 * @return {!goog.i18n.TimeZone} A time zone object with the given constant
182 * offset. Note that the time zone ID of this object will use the POSIX
183 * convention, which has a reversed sign ("Etc/GMT+8" means UTC-8 or PST).
184 * @private
185 */
186 goog.i18n.TimeZone.createSimpleTimeZone_ = function(timeZoneOffsetInMinutes) {
187 var tz = new goog.i18n.TimeZone();
188 tz.standardOffset_ = timeZoneOffsetInMinutes;
189 tz.timeZoneId_ =
190 goog.i18n.TimeZone.composePosixTimeZoneID_(timeZoneOffsetInMinutes);
191 var str = goog.i18n.TimeZone.composeUTCString_(timeZoneOffsetInMinutes);
192 var strGMT = goog.i18n.TimeZone.composeGMTString_(timeZoneOffsetInMinutes);
193 tz.tzNames_ = [str, str];
194 tz.tzNamesExt_ = {STD_LONG_NAME_GMT: strGMT, STD_GENERIC_LOCATION: strGMT};
195 tz.transitions_ = [];
196 return tz;
197 };
198
199
200 /**
201 * Generate a GMT-relative string for a constant time zone offset.
202 * @param {number} offset The time zone offset in minutes WEST of UTC.
203 * @return {string} The GMT string for this offset, which will indicate
204 * hours EAST of UTC.
205 * @private
206 */
207 goog.i18n.TimeZone.composeGMTString_ = function(offset) {
208 var parts = ['GMT'];
209 parts.push(offset <= 0 ? '+' : '-');
210 offset = Math.abs(offset);
211 parts.push(
212 goog.string.padNumber(Math.floor(offset / 60) % 100, 2), ':',
213 goog.string.padNumber(offset % 60, 2));
214 return parts.join('');
215 };
216
217
218 /**
219 * Generate a POSIX time zone ID for a constant time zone offset.
220 * @param {number} offset The time zone offset in minutes WEST of UTC.
221 * @return {string} The POSIX time zone ID for this offset, which will indicate
222 * hours WEST of UTC.
223 * @private
224 */
225 goog.i18n.TimeZone.composePosixTimeZoneID_ = function(offset) {
226 if (offset == 0) {
227 return 'Etc/GMT';
228 }
229 var parts = ['Etc/GMT', offset < 0 ? '-' : '+'];
230 offset = Math.abs(offset);
231 parts.push(Math.floor(offset / 60) % 100);
232 offset = offset % 60;
233 if (offset != 0) {
234 parts.push(':', goog.string.padNumber(offset, 2));
235 }
236 return parts.join('');
237 };
238
239
240 /**
241 * Generate a UTC-relative string for a constant time zone offset.
242 * @param {number} offset The time zone offset in minutes WEST of UTC.
243 * @return {string} The UTC string for this offset, which will indicate
244 * hours EAST of UTC.
245 * @private
246 */
247 goog.i18n.TimeZone.composeUTCString_ = function(offset) {
248 if (offset == 0) {
249 return 'UTC';
250 }
251 var parts = ['UTC', offset < 0 ? '+' : '-'];
252 offset = Math.abs(offset);
253 parts.push(Math.floor(offset / 60) % 100);
254 offset = offset % 60;
255 if (offset != 0) {
256 parts.push(':', offset);
257 }
258 return parts.join('');
259 };
260
261
262 /**
263 * Convert the contents of time zone object to a timeZoneData object, suitable
264 * for passing to goog.i18n.TimeZone.createTimeZone.
265 * @return {!Object} A timeZoneData object (see the documentation for
266 * goog.i18n.TimeZone.createTimeZone).
267 */
268 goog.i18n.TimeZone.prototype.getTimeZoneData = function() {
269 return {
270 'id': this.timeZoneId_,
271 'std_offset': -this.standardOffset_, // note createTimeZone flips the sign
272 'names': goog.array.clone(this.tzNames_), // avoid aliasing the array
273 'names_ext': goog.object.clone(this.tzNamesExt_), // avoid aliasing
274 'transitions': goog.array.clone(this.transitions_) // avoid aliasing
275 };
276 };
277
278
279 /**
280 * Return the DST adjustment to the time zone offset for a given time.
281 * While Daylight Saving Time is in effect, this number is positive.
282 * Otherwise, it is zero.
283 * @param {goog.date.DateLike} date The time to check.
284 * @return {number} The DST adjustment in minutes EAST of UTC.
285 */
286 goog.i18n.TimeZone.prototype.getDaylightAdjustment = function(date) {
287 var timeInMs = Date.UTC(
288 date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate(),
289 date.getUTCHours(), date.getUTCMinutes());
290 var timeInHours = timeInMs / goog.i18n.TimeZone.MILLISECONDS_PER_HOUR_;
291 var index = 0;
292 while (index < this.transitions_.length &&
293 timeInHours >= this.transitions_[index]) {
294 index += 2;
295 }
296 return (index == 0) ? 0 : this.transitions_[index - 1];
297 };
298
299
300 /**
301 * Return the GMT representation of this time zone object.
302 * @param {goog.date.DateLike} date The date for which time to retrieve
303 * GMT string.
304 * @return {string} GMT representation string.
305 */
306 goog.i18n.TimeZone.prototype.getGMTString = function(date) {
307 return goog.i18n.TimeZone.composeGMTString_(this.getOffset(date));
308 };
309
310
311 /**
312 * Get the long time zone name for a given date/time.
313 * @param {goog.date.DateLike} date The time for which to retrieve
314 * the long time zone name.
315 * @return {string} The long time zone name.
316 */
317 goog.i18n.TimeZone.prototype.getLongName = function(date) {
318 return this.tzNames_[this.isDaylightTime(date) ?
319 goog.i18n.TimeZone.NameType.DLT_LONG_NAME :
320 goog.i18n.TimeZone.NameType.STD_LONG_NAME];
321 };
322
323
324 /**
325 * Get the time zone offset in minutes WEST of UTC for a given date/time.
326 * @param {goog.date.DateLike} date The time for which to retrieve
327 * the time zone offset.
328 * @return {number} The time zone offset in minutes WEST of UTC.
329 */
330 goog.i18n.TimeZone.prototype.getOffset = function(date) {
331 return this.standardOffset_ - this.getDaylightAdjustment(date);
332 };
333
334
335 /**
336 * Get the RFC representation of the time zone for a given date/time.
337 * @param {goog.date.DateLike} date The time for which to retrieve the
338 * RFC time zone string.
339 * @return {string} The RFC time zone string.
340 */
341 goog.i18n.TimeZone.prototype.getRFCTimeZoneString = function(date) {
342 var offset = -this.getOffset(date);
343 var parts = [offset < 0 ? '-' : '+'];
344 offset = Math.abs(offset);
345 parts.push(
346 goog.string.padNumber(Math.floor(offset / 60) % 100, 2),
347 goog.string.padNumber(offset % 60, 2));
348 return parts.join('');
349 };
350
351
352 /**
353 * Get the short time zone name for given date/time.
354 * @param {goog.date.DateLike} date The time for which to retrieve
355 * the short time zone name.
356 * @return {string} The short time zone name.
357 */
358 goog.i18n.TimeZone.prototype.getShortName = function(date) {
359 return this.tzNames_[this.isDaylightTime(date) ?
360 goog.i18n.TimeZone.NameType.DLT_SHORT_NAME :
361 goog.i18n.TimeZone.NameType.STD_SHORT_NAME];
362 };
363
364
365 /**
366 * Return the time zone ID for this time zone.
367 * @return {string} The time zone ID.
368 */
369 goog.i18n.TimeZone.prototype.getTimeZoneId = function() {
370 return this.timeZoneId_;
371 };
372
373
374 /**
375 * Check if Daylight Saving Time is in effect at a given time in this time zone.
376 * @param {goog.date.DateLike} date The time to check.
377 * @return {boolean} True if Daylight Saving Time is in effect.
378 */
379 goog.i18n.TimeZone.prototype.isDaylightTime = function(date) {
380 return this.getDaylightAdjustment(date) > 0;
381 };
382
383
384 /**
385 * Get the long GMT time zone name for a given date/time.
386 * @param {!goog.date.DateLike} date The time for which to retrieve
387 * the long GMT time zone name.
388 * @return {string} The long GMT time zone name.
389 */
390 goog.i18n.TimeZone.prototype.getLongNameGMT = function(date) {
391 if (this.isDaylightTime(date)) {
392 return (goog.isDef(this.tzNamesExt_.DST_LONG_NAME_GMT)) ?
393 this.tzNamesExt_.DST_LONG_NAME_GMT :
394 this.tzNamesExt_['DST_LONG_NAME_GMT'];
395 } else {
396 return (goog.isDef(this.tzNamesExt_.STD_LONG_NAME_GMT)) ?
397 this.tzNamesExt_.STD_LONG_NAME_GMT :
398 this.tzNamesExt_['STD_LONG_NAME_GMT'];
399 }
400 };
401
402
403 /**
404 * Get the generic location time zone name for a given date/time.
405 * @param {!goog.date.DateLike} date The time for which to retrieve
406 * the generic location time zone name.
407 * @return {string} The generic location time zone name.
408 */
409 goog.i18n.TimeZone.prototype.getGenericLocation = function(date) {
410 if (this.isDaylightTime(date)) {
411 return (goog.isDef(this.tzNamesExt_.DST_GENERIC_LOCATION)) ?
412 this.tzNamesExt_.DST_GENERIC_LOCATION :
413 this.tzNamesExt_['DST_GENERIC_LOCATION'];
414 } else {
415 return (goog.isDef(this.tzNamesExt_.STD_GENERIC_LOCATION)) ?
416 this.tzNamesExt_.STD_GENERIC_LOCATION :
417 this.tzNamesExt_['STD_GENERIC_LOCATION'];
418 }
419 };