1 /*
2 * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 /*
27 * This file is available under and governed by the GNU General Public
28 * License version 2 only, as published by the Free Software Foundation.
29 * However, the following notice accompanied the original version of this
30 * file:
31 *
32 * Copyright (c) 2007-2012, Stephen Colebourne & Michael Nascimento Santos
33 *
34 * All rights reserved.
35 *
36 * Redistribution and use in source and binary forms, with or without
37 * modification, are permitted provided that the following conditions are met:
38 *
39 * * Redistributions of source code must retain the above copyright notice,
40 * this list of conditions and the following disclaimer.
41 *
42 * * Redistributions in binary form must reproduce the above copyright notice,
43 * this list of conditions and the following disclaimer in the documentation
44 * and/or other materials provided with the distribution.
45 *
46 * * Neither the name of JSR-310 nor the names of its contributors
47 * may be used to endorse or promote products derived from this software
48 * without specific prior written permission.
49 *
50 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
51 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
52 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
53 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
54 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
55 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
56 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
57 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
58 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
59 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
60 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
61 */
62 package build.tools.tzdb;
63
64 import java.util.Objects;
65 import java.util.concurrent.ConcurrentHashMap;
66 import java.util.concurrent.ConcurrentMap;
67
68 /**
69 * A time-zone offset from Greenwich/UTC, such as {@code +02:00}.
70 * <p>
71 * A time-zone offset is the period of time that a time-zone differs from Greenwich/UTC.
72 * This is usually a fixed number of hours and minutes.
73 *
74 * @since 1.8
75 */
76 final class ZoneOffset implements Comparable<ZoneOffset> {
77
78 /** Cache of time-zone offset by offset in seconds. */
79 private static final ConcurrentMap<Integer, ZoneOffset> SECONDS_CACHE = new ConcurrentHashMap<>(16, 0.75f, 4);
80 /** Cache of time-zone offset by ID. */
81 private static final ConcurrentMap<String, ZoneOffset> ID_CACHE = new ConcurrentHashMap<>(16, 0.75f, 4);
82
83 /**
84 * The number of seconds per hour.
85 */
86 private static final int SECONDS_PER_HOUR = 60 * 60;
87 /**
88 * The number of seconds per minute.
89 */
90 private static final int SECONDS_PER_MINUTE = 60;
91 /**
92 * The number of minutes per hour.
93 */
94 private static final int MINUTES_PER_HOUR = 60;
95 /**
96 * The abs maximum seconds.
97 */
98 private static final int MAX_SECONDS = 18 * SECONDS_PER_HOUR;
99 /**
100 * Serialization version.
101 */
102 private static final long serialVersionUID = 2357656521762053153L;
103
104 /**
105 * The time-zone offset for UTC, with an ID of 'Z'.
106 */
107 public static final ZoneOffset UTC = ZoneOffset.ofTotalSeconds(0);
108 /**
109 * Constant for the maximum supported offset.
110 */
111 public static final ZoneOffset MIN = ZoneOffset.ofTotalSeconds(-MAX_SECONDS);
112 /**
113 * Constant for the maximum supported offset.
114 */
115 public static final ZoneOffset MAX = ZoneOffset.ofTotalSeconds(MAX_SECONDS);
116
117 /**
118 * The total offset in seconds.
119 */
120 private final int totalSeconds;
121 /**
122 * The string form of the time-zone offset.
123 */
124 private final transient String id;
125
126 //-----------------------------------------------------------------------
127 /**
128 * Obtains an instance of {@code ZoneOffset} using the ID.
129 * <p>
130 * This method parses the string ID of a {@code ZoneOffset} to
131 * return an instance. The parsing accepts all the formats generated by
132 * {@link #getId()}, plus some additional formats:
133 * <p><ul>
134 * <li>{@code Z} - for UTC
135 * <li>{@code +h}
136 * <li>{@code +hh}
137 * <li>{@code +hh:mm}
138 * <li>{@code -hh:mm}
139 * <li>{@code +hhmm}
140 * <li>{@code -hhmm}
141 * <li>{@code +hh:mm:ss}
142 * <li>{@code -hh:mm:ss}
143 * <li>{@code +hhmmss}
144 * <li>{@code -hhmmss}
145 * </ul><p>
146 * Note that ± means either the plus or minus symbol.
147 * <p>
148 * The ID of the returned offset will be normalized to one of the formats
149 * described by {@link #getId()}.
150 * <p>
151 * The maximum supported range is from +18:00 to -18:00 inclusive.
152 *
153 * @param offsetId the offset ID, not null
154 * @return the zone-offset, not null
155 * @throws DateTimeException if the offset ID is invalid
156 */
157 @SuppressWarnings("fallthrough")
158 public static ZoneOffset of(String offsetId) {
159 Objects.requireNonNull(offsetId, "offsetId");
160 // "Z" is always in the cache
161 ZoneOffset offset = ID_CACHE.get(offsetId);
162 if (offset != null) {
163 return offset;
164 }
165
166 // parse - +h, +hh, +hhmm, +hh:mm, +hhmmss, +hh:mm:ss
167 final int hours, minutes, seconds;
168 switch (offsetId.length()) {
169 case 2:
170 offsetId = offsetId.charAt(0) + "0" + offsetId.charAt(1); // fallthru
171 case 3:
172 hours = parseNumber(offsetId, 1, false);
173 minutes = 0;
174 seconds = 0;
175 break;
176 case 5:
177 hours = parseNumber(offsetId, 1, false);
178 minutes = parseNumber(offsetId, 3, false);
179 seconds = 0;
180 break;
181 case 6:
182 hours = parseNumber(offsetId, 1, false);
183 minutes = parseNumber(offsetId, 4, true);
184 seconds = 0;
185 break;
186 case 7:
187 hours = parseNumber(offsetId, 1, false);
188 minutes = parseNumber(offsetId, 3, false);
189 seconds = parseNumber(offsetId, 5, false);
190 break;
191 case 9:
192 hours = parseNumber(offsetId, 1, false);
193 minutes = parseNumber(offsetId, 4, true);
194 seconds = parseNumber(offsetId, 7, true);
195 break;
196 default:
197 throw new DateTimeException("Zone offset ID '" + offsetId + "' is invalid");
198 }
199 char first = offsetId.charAt(0);
200 if (first != '+' && first != '-') {
201 throw new DateTimeException("Zone offset ID '" + offsetId + "' is invalid: Plus/minus not found when expected");
202 }
203 if (first == '-') {
204 return ofHoursMinutesSeconds(-hours, -minutes, -seconds);
205 } else {
206 return ofHoursMinutesSeconds(hours, minutes, seconds);
207 }
208 }
209
210 /**
211 * Parse a two digit zero-prefixed number.
212 *
213 * @param offsetId the offset ID, not null
214 * @param pos the position to parse, valid
215 * @param precededByColon should this number be prefixed by a precededByColon
216 * @return the parsed number, from 0 to 99
217 */
218 private static int parseNumber(CharSequence offsetId, int pos, boolean precededByColon) {
219 if (precededByColon && offsetId.charAt(pos - 1) != ':') {
220 throw new DateTimeException("Zone offset ID '" + offsetId + "' is invalid: Colon not found when expected");
221 }
222 char ch1 = offsetId.charAt(pos);
223 char ch2 = offsetId.charAt(pos + 1);
224 if (ch1 < '0' || ch1 > '9' || ch2 < '0' || ch2 > '9') {
225 throw new DateTimeException("Zone offset ID '" + offsetId + "' is invalid: Non numeric characters found");
226 }
227 return (ch1 - 48) * 10 + (ch2 - 48);
228 }
229
230 //-----------------------------------------------------------------------
231 /**
232 * Obtains an instance of {@code ZoneOffset} using an offset in hours.
233 *
234 * @param hours the time-zone offset in hours, from -18 to +18
235 * @return the zone-offset, not null
236 * @throws DateTimeException if the offset is not in the required range
237 */
238 public static ZoneOffset ofHours(int hours) {
239 return ofHoursMinutesSeconds(hours, 0, 0);
240 }
241
242 /**
243 * Obtains an instance of {@code ZoneOffset} using an offset in
244 * hours and minutes.
245 * <p>
246 * The sign of the hours and minutes components must match.
247 * Thus, if the hours is negative, the minutes must be negative or zero.
248 * If the hours is zero, the minutes may be positive, negative or zero.
249 *
250 * @param hours the time-zone offset in hours, from -18 to +18
251 * @param minutes the time-zone offset in minutes, from 0 to ±59, sign matches hours
252 * @return the zone-offset, not null
253 * @throws DateTimeException if the offset is not in the required range
254 */
255 public static ZoneOffset ofHoursMinutes(int hours, int minutes) {
256 return ofHoursMinutesSeconds(hours, minutes, 0);
257 }
258
259 /**
260 * Obtains an instance of {@code ZoneOffset} using an offset in
261 * hours, minutes and seconds.
262 * <p>
263 * The sign of the hours, minutes and seconds components must match.
264 * Thus, if the hours is negative, the minutes and seconds must be negative or zero.
265 *
266 * @param hours the time-zone offset in hours, from -18 to +18
267 * @param minutes the time-zone offset in minutes, from 0 to ±59, sign matches hours and seconds
268 * @param seconds the time-zone offset in seconds, from 0 to ±59, sign matches hours and minutes
269 * @return the zone-offset, not null
270 * @throws DateTimeException if the offset is not in the required range
271 */
272 public static ZoneOffset ofHoursMinutesSeconds(int hours, int minutes, int seconds) {
273 validate(hours, minutes, seconds);
274 int totalSeconds = totalSeconds(hours, minutes, seconds);
275 return ofTotalSeconds(totalSeconds);
276 }
277
278 /**
279 * Validates the offset fields.
280 *
281 * @param hours the time-zone offset in hours, from -18 to +18
282 * @param minutes the time-zone offset in minutes, from 0 to ±59
283 * @param seconds the time-zone offset in seconds, from 0 to ±59
284 * @throws DateTimeException if the offset is not in the required range
285 */
286 private static void validate(int hours, int minutes, int seconds) {
287 if (hours < -18 || hours > 18) {
288 throw new DateTimeException("Zone offset hours not in valid range: value " + hours +
289 " is not in the range -18 to 18");
290 }
291 if (hours > 0) {
292 if (minutes < 0 || seconds < 0) {
293 throw new DateTimeException("Zone offset minutes and seconds must be positive because hours is positive");
294 }
295 } else if (hours < 0) {
296 if (minutes > 0 || seconds > 0) {
297 throw new DateTimeException("Zone offset minutes and seconds must be negative because hours is negative");
298 }
299 } else if ((minutes > 0 && seconds < 0) || (minutes < 0 && seconds > 0)) {
300 throw new DateTimeException("Zone offset minutes and seconds must have the same sign");
301 }
302 if (Math.abs(minutes) > 59) {
303 throw new DateTimeException("Zone offset minutes not in valid range: abs(value) " +
304 Math.abs(minutes) + " is not in the range 0 to 59");
305 }
306 if (Math.abs(seconds) > 59) {
307 throw new DateTimeException("Zone offset seconds not in valid range: abs(value) " +
308 Math.abs(seconds) + " is not in the range 0 to 59");
309 }
310 if (Math.abs(hours) == 18 && (Math.abs(minutes) > 0 || Math.abs(seconds) > 0)) {
311 throw new DateTimeException("Zone offset not in valid range: -18:00 to +18:00");
312 }
313 }
314
315 /**
316 * Calculates the total offset in seconds.
317 *
318 * @param hours the time-zone offset in hours, from -18 to +18
319 * @param minutes the time-zone offset in minutes, from 0 to ±59, sign matches hours and seconds
320 * @param seconds the time-zone offset in seconds, from 0 to ±59, sign matches hours and minutes
321 * @return the total in seconds
322 */
323 private static int totalSeconds(int hours, int minutes, int seconds) {
324 return hours * SECONDS_PER_HOUR + minutes * SECONDS_PER_MINUTE + seconds;
325 }
326
327 //-----------------------------------------------------------------------
328 /**
329 * Obtains an instance of {@code ZoneOffset} specifying the total offset in seconds
330 * <p>
331 * The offset must be in the range {@code -18:00} to {@code +18:00}, which corresponds to -64800 to +64800.
332 *
333 * @param totalSeconds the total time-zone offset in seconds, from -64800 to +64800
334 * @return the ZoneOffset, not null
335 * @throws DateTimeException if the offset is not in the required range
336 */
337 public static ZoneOffset ofTotalSeconds(int totalSeconds) {
338 if (Math.abs(totalSeconds) > MAX_SECONDS) {
339 throw new DateTimeException("Zone offset not in valid range: -18:00 to +18:00");
340 }
341 if (totalSeconds % (15 * SECONDS_PER_MINUTE) == 0) {
342 Integer totalSecs = totalSeconds;
343 ZoneOffset result = SECONDS_CACHE.get(totalSecs);
344 if (result == null) {
345 result = new ZoneOffset(totalSeconds);
346 SECONDS_CACHE.putIfAbsent(totalSecs, result);
347 result = SECONDS_CACHE.get(totalSecs);
348 ID_CACHE.putIfAbsent(result.getId(), result);
349 }
350 return result;
351 } else {
352 return new ZoneOffset(totalSeconds);
353 }
354 }
355
356 /**
357 * Constructor.
358 *
359 * @param totalSeconds the total time-zone offset in seconds, from -64800 to +64800
360 */
361 private ZoneOffset(int totalSeconds) {
362 super();
363 this.totalSeconds = totalSeconds;
364 id = buildId(totalSeconds);
365 }
366
367 private static String buildId(int totalSeconds) {
368 if (totalSeconds == 0) {
369 return "Z";
370 } else {
371 int absTotalSeconds = Math.abs(totalSeconds);
372 StringBuilder buf = new StringBuilder();
373 int absHours = absTotalSeconds / SECONDS_PER_HOUR;
374 int absMinutes = (absTotalSeconds / SECONDS_PER_MINUTE) % MINUTES_PER_HOUR;
375 buf.append(totalSeconds < 0 ? "-" : "+")
376 .append(absHours < 10 ? "0" : "").append(absHours)
377 .append(absMinutes < 10 ? ":0" : ":").append(absMinutes);
378 int absSeconds = absTotalSeconds % SECONDS_PER_MINUTE;
379 if (absSeconds != 0) {
380 buf.append(absSeconds < 10 ? ":0" : ":").append(absSeconds);
381 }
382 return buf.toString();
383 }
384 }
385
386 /**
387 * Gets the total zone offset in seconds.
388 * <p>
389 * This is the primary way to access the offset amount.
390 * It returns the total of the hours, minutes and seconds fields as a
391 * single offset that can be added to a time.
392 *
393 * @return the total zone offset amount in seconds
394 */
395 public int getTotalSeconds() {
396 return totalSeconds;
397 }
398
399 /**
400 * Gets the normalized zone offset ID.
401 * <p>
402 * The ID is minor variation to the standard ISO-8601 formatted string
403 * for the offset. There are three formats:
404 * <p><ul>
405 * <li>{@code Z} - for UTC (ISO-8601)
406 * <li>{@code +hh:mm} or {@code -hh:mm} - if the seconds are zero (ISO-8601)
407 * <li>{@code +hh:mm:ss} or {@code -hh:mm:ss} - if the seconds are non-zero (not ISO-8601)
408 * </ul><p>
409 *
410 * @return the zone offset ID, not null
411 */
412 public String getId() {
413 return id;
414 }
415
416 /**
417 * Compares this offset to another offset in descending order.
418 * <p>
419 * The offsets are compared in the order that they occur for the same time
420 * of day around the world. Thus, an offset of {@code +10:00} comes before an
421 * offset of {@code +09:00} and so on down to {@code -18:00}.
422 * <p>
423 * The comparison is "consistent with equals", as defined by {@link Comparable}.
424 *
425 * @param other the other date to compare to, not null
426 * @return the comparator value, negative if less, postive if greater
427 * @throws NullPointerException if {@code other} is null
428 */
429 @Override
430 public int compareTo(ZoneOffset other) {
431 return other.totalSeconds - totalSeconds;
432 }
433
434 /**
435 * Checks if this offset is equal to another offset.
436 * <p>
437 * The comparison is based on the amount of the offset in seconds.
438 * This is equivalent to a comparison by ID.
439 *
440 * @param obj the object to check, null returns false
441 * @return true if this is equal to the other offset
442 */
443 @Override
444 public boolean equals(Object obj) {
445 if (this == obj) {
446 return true;
447 }
448 if (obj instanceof ZoneOffset) {
449 return totalSeconds == ((ZoneOffset) obj).totalSeconds;
450 }
451 return false;
452 }
453
454 /**
455 * A hash code for this offset.
456 *
457 * @return a suitable hash code
458 */
459 @Override
460 public int hashCode() {
461 return totalSeconds;
462 }
463
464 /**
465 * Outputs this offset as a {@code String}, using the normalized ID.
466 *
467 * @return a string representation of this offset, not null
468 */
469 @Override
470 public String toString() {
471 return id;
472 }
473
474 }