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 * Copyright (c) 2012, Stephen Colebourne & Michael Nascimento Santos 28 * 29 * All rights reserved. 30 * 31 * Redistribution and use in source and binary forms, with or without 32 * modification, are permitted provided that the following conditions are met: 33 * 34 * * Redistributions of source code must retain the above copyright notice, 35 * this list of conditions and the following disclaimer. 36 * 37 * * Redistributions in binary form must reproduce the above copyright notice, 38 * this list of conditions and the following disclaimer in the documentation 39 * and/or other materials provided with the distribution. 40 * 41 * * Neither the name of JSR-310 nor the names of its contributors 42 * may be used to endorse or promote products derived from this software 43 * without specific prior written permission. 44 * 45 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 46 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 47 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 48 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 49 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 50 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 51 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 52 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 53 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 54 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 55 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 56 */ 57 package java.time.temporal; 58 59 import java.time.Duration; 60 61 /** 62 * A standard set of date periods units. 63 * <p> 64 * This set of units provide unit-based access to manipulate a date, time or date-time. 65 * The standard set of units can be extended by implementing {@link TemporalUnit}. 66 * <p> 67 * These units are intended to be applicable in multiple calendar systems. 68 * For example, most non-ISO calendar systems define units of years, months and days, 69 * just with slightly different rules. 70 * The documentation of each unit explains how it operates. 71 * 72 * @implSpec 73 * This is a final, immutable and thread-safe enum. 74 * 75 * @since 1.8 76 */ 77 public enum ChronoUnit implements TemporalUnit { 78 79 /** 80 * Unit that represents the concept of a nanosecond, the smallest supported unit of time. 81 * For the ISO calendar system, it is equal to the 1,000,000,000th part of the second unit. 82 */ 83 NANOS("Nanos", Duration.ofNanos(1)), 84 /** 85 * Unit that represents the concept of a microsecond. 86 * For the ISO calendar system, it is equal to the 1,000,000th part of the second unit. 87 */ 88 MICROS("Micros", Duration.ofNanos(1000)), 89 /** 90 * Unit that represents the concept of a millisecond. 91 * For the ISO calendar system, it is equal to the 1000th part of the second unit. 92 */ 93 MILLIS("Millis", Duration.ofNanos(1000_000)), 94 /** 95 * Unit that represents the concept of a second. 96 * For the ISO calendar system, it is equal to the second in the SI system 97 * of units, except around a leap-second. 98 */ 99 SECONDS("Seconds", Duration.ofSeconds(1)), 100 /** 101 * Unit that represents the concept of a minute. 102 * For the ISO calendar system, it is equal to 60 seconds. 103 */ 104 MINUTES("Minutes", Duration.ofSeconds(60)), 105 /** 106 * Unit that represents the concept of an hour. 107 * For the ISO calendar system, it is equal to 60 minutes. 108 */ 109 HOURS("Hours", Duration.ofSeconds(3600)), 110 /** 111 * Unit that represents the concept of half a day, as used in AM/PM. 112 * For the ISO calendar system, it is equal to 12 hours. 113 */ 114 HALF_DAYS("HalfDays", Duration.ofSeconds(43200)), 115 /** 116 * Unit that represents the concept of a day. 117 * For the ISO calendar system, it is the standard day from midnight to midnight. 118 * The estimated duration of a day is {@code 24 Hours}. 119 * <p> 120 * When used with other calendar systems it must correspond to the day defined by 121 * the rising and setting of the Sun on Earth. It is not required that days begin 122 * at midnight - when converting between calendar systems, the date should be 123 * equivalent at midday. 124 */ 125 DAYS("Days", Duration.ofSeconds(86400)), 126 /** 127 * Unit that represents the concept of a week. 128 * For the ISO calendar system, it is equal to 7 days. 129 * <p> 130 * When used with other calendar systems it must correspond to an integral number of days. 131 */ 132 WEEKS("Weeks", Duration.ofSeconds(7 * 86400L)), 133 /** 134 * Unit that represents the concept of a month. 135 * For the ISO calendar system, the length of the month varies by month-of-year. 136 * The estimated duration of a month is one twelfth of {@code 365.2425 Days}. 137 * <p> 138 * When used with other calendar systems it must correspond to an integral number of days. 139 */ 140 MONTHS("Months", Duration.ofSeconds(31556952L / 12)), 141 /** 142 * Unit that represents the concept of a year. 143 * For the ISO calendar system, it is equal to 12 months. 144 * The estimated duration of a year is {@code 365.2425 Days}. 145 * <p> 146 * When used with other calendar systems it must correspond to an integral number of days 147 * or months roughly equal to a year defined by the passage of the Earth around the Sun. 148 */ 149 YEARS("Years", Duration.ofSeconds(31556952L)), 150 /** 151 * Unit that represents the concept of a decade. 152 * For the ISO calendar system, it is equal to 10 years. 153 * <p> 154 * When used with other calendar systems it must correspond to an integral number of days 155 * and is normally an integral number of years. 156 */ 157 DECADES("Decades", Duration.ofSeconds(31556952L * 10L)), 158 /** 159 * Unit that represents the concept of a century. 160 * For the ISO calendar system, it is equal to 100 years. 161 * <p> 162 * When used with other calendar systems it must correspond to an integral number of days 163 * and is normally an integral number of years. 164 */ 165 CENTURIES("Centuries", Duration.ofSeconds(31556952L * 100L)), 166 /** 167 * Unit that represents the concept of a millennium. 168 * For the ISO calendar system, it is equal to 1000 years. 169 * <p> 170 * When used with other calendar systems it must correspond to an integral number of days 171 * and is normally an integral number of years. 172 */ 173 MILLENNIA("Millennia", Duration.ofSeconds(31556952L * 1000L)), 174 /** 175 * Unit that represents the concept of an era. 176 * The ISO calendar system doesn't have eras thus it is impossible to add 177 * an era to a date or date-time. 178 * The estimated duration of the era is artificially defined as {@code 1,000,000,000 Years}. 179 * <p> 180 * When used with other calendar systems there are no restrictions on the unit. 181 */ 182 ERAS("Eras", Duration.ofSeconds(31556952L * 1000_000_000L)), 183 /** 184 * Artificial unit that represents the concept of forever. 185 * This is primarily used with {@link TemporalField} to represent unbounded fields 186 * such as the year or era. 187 * The estimated duration of the era is artificially defined as the largest duration 188 * supported by {@code Duration}. 189 */ 190 FOREVER("Forever", Duration.ofSeconds(Long.MAX_VALUE, 999_999_999)); 191 192 private final String name; 193 private final Duration duration; 194 ChronoUnit(String name, Duration estimatedDuration)195 private ChronoUnit(String name, Duration estimatedDuration) { 196 this.name = name; 197 this.duration = estimatedDuration; 198 } 199 200 //----------------------------------------------------------------------- 201 /** 202 * Gets the estimated duration of this unit in the ISO calendar system. 203 * <p> 204 * All of the units in this class have an estimated duration. 205 * Days vary due to daylight saving time, while months have different lengths. 206 * 207 * @return the estimated duration of this unit, not null 208 */ 209 @Override getDuration()210 public Duration getDuration() { 211 return duration; 212 } 213 214 /** 215 * Checks if the duration of the unit is an estimate. 216 * <p> 217 * All time units in this class are considered to be accurate, while all date 218 * units in this class are considered to be estimated. 219 * <p> 220 * This definition ignores leap seconds, but considers that Days vary due to 221 * daylight saving time and months have different lengths. 222 * 223 * @return true if the duration is estimated, false if accurate 224 */ 225 @Override isDurationEstimated()226 public boolean isDurationEstimated() { 227 return this.compareTo(DAYS) >= 0; 228 } 229 230 //----------------------------------------------------------------------- 231 /** 232 * Checks if this unit is a date unit. 233 * <p> 234 * All units from days to eras inclusive are date-based. 235 * Time-based units and {@code FOREVER} return false. 236 * 237 * @return true if a date unit, false if a time unit 238 */ 239 @Override isDateBased()240 public boolean isDateBased() { 241 return this.compareTo(DAYS) >= 0 && this != FOREVER; 242 } 243 244 /** 245 * Checks if this unit is a time unit. 246 * <p> 247 * All units from nanos to half-days inclusive are time-based. 248 * Date-based units and {@code FOREVER} return false. 249 * 250 * @return true if a time unit, false if a date unit 251 */ 252 @Override isTimeBased()253 public boolean isTimeBased() { 254 return this.compareTo(DAYS) < 0; 255 } 256 257 //----------------------------------------------------------------------- 258 @Override isSupportedBy(Temporal temporal)259 public boolean isSupportedBy(Temporal temporal) { 260 return temporal.isSupported(this); 261 } 262 263 @SuppressWarnings("unchecked") 264 @Override addTo(R temporal, long amount)265 public <R extends Temporal> R addTo(R temporal, long amount) { 266 return (R) temporal.plus(amount, this); 267 } 268 269 //----------------------------------------------------------------------- 270 @Override between(Temporal temporal1Inclusive, Temporal temporal2Exclusive)271 public long between(Temporal temporal1Inclusive, Temporal temporal2Exclusive) { 272 return temporal1Inclusive.until(temporal2Exclusive, this); 273 } 274 275 //----------------------------------------------------------------------- 276 @Override toString()277 public String toString() { 278 return name; 279 } 280 281 } 282