Years


1   /*
2    *  Copyright 2001-2006 Stephen Colebourne
3    *
4    *  Licensed under the Apache License, Version 2.0 (the "License");
5    *  you may not use this file except in compliance with the License.
6    *  You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   *  Unless required by applicable law or agreed to in writing, software
11   *  distributed under the License is distributed on an "AS IS" BASIS,
12   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   *  See the License for the specific language governing permissions and
14   *  limitations under the License.
15   */
16  package org.joda.time;
17  
18  import org.joda.time.base.BaseSingleFieldPeriod;
19  import org.joda.time.field.FieldUtils;
20  import org.joda.time.format.ISOPeriodFormat;
21  import org.joda.time.format.PeriodFormatter;
22  
23  /**
24   * An immutable time period representing a number of years.
25   * <p>
26   * <code>Years</code> is an immutable period that can only store years.
27   * It does not store years, days or hours for example. As such it is a
28   * type-safe way of representing a number of years in an application.
29   * <p>
30   * The number of years is set in the constructor, and may be queried using
31   * <code>getYears()</code>. Basic mathematical operations are provided -
32   * <code>plus()</code>, <code>minus()</code>, <code>multipliedBy()</code> and
33   * <code>dividedBy()</code>.
34   * <p>
35   * <code>Years</code> is thread-safe and immutable.
36   *
37   * @author Stephen Colebourne
38   * @since 1.4
39   */
40  public final class Years extends BaseSingleFieldPeriod {
41  
42      /** Constant representing zero years. */
43      public static final Years ZERO = new Years(0);
44      /** Constant representing one day. */
45      public static final Years ONE = new Years(1);
46      /** Constant representing two years. */
47      public static final Years TWO = new Years(2);
48      /** Constant representing three years. */
49      public static final Years THREE = new Years(3);
50      /** Constant representing the maximum nuber of years that can be stored in this object. */
51      public static final Years MAX_VALUE = new Years(Integer.MAX_VALUE);
52      /** Constant representing the minimum nuber of years that can be stored in this object. */
53      public static final Years MIN_VALUE = new Years(Integer.MIN_VALUE);
54  
55      /** The paser to use for this class. */
56      private static final PeriodFormatter PARSER = ISOPeriodFormat.standard().withParseType(PeriodType.years());
57      /** Serialization version. */
58      private static final long serialVersionUID = 87525275727380868L;
59  
60      //-----------------------------------------------------------------------
61      /**
62       * Obtains an instance of <code>Years</code> that may be cached.
63       * <code>Years</code> is immutable, so instances can be cached and shared.
64       * This factory method provides access to shared instances.
65       *
66       * @param years  the number of years to obtain an instance for
67       * @return the instance of Years
68       */
69      public static Years years(int years) {
70          switch (years) {
71              case 0:
72                  return ZERO;
73              case 1:
74                  return ONE;
75              case 2:
76                  return TWO;
77              case 3:
78                  return THREE;
79              case Integer.MAX_VALUE:
80                  return MAX_VALUE;
81              case Integer.MIN_VALUE:
82                  return MIN_VALUE;
83              default:
84                  return new Years(years);
85          }
86      }
87  
88      //-----------------------------------------------------------------------
89      /**
90       * Creates a <code>Years</code> representing the number of whole years
91       * between the two specified datetimes. This method corectly handles
92       * any daylight savings time changes that may occur during the interval.
93       *
94       * @param start  the start instant, must not be null
95       * @param end  the end instant, must not be null
96       * @return the period in years
97       * @throws IllegalArgumentException if the instants are null or invalid
98       */
99      public static Years yearsBetween(ReadableInstant start, ReadableInstant end) {
100         int amount = BaseSingleFieldPeriod.between(start, end, DurationFieldType.years());
101         return Years.years(amount);
102     }
103 
104     /**
105      * Creates a <code>Years</code> representing the number of whole years
106      * between the two specified partial datetimes.
107      * <p>
108      * The two partials must contain the same fields, for example you can specify
109      * two <code>LocalDate</code> objects.
110      *
111      * @param start  the start partial date, must not be null
112      * @param end  the end partial date, must not be null
113      * @return the period in years
114      * @throws IllegalArgumentException if the partials are null or invalid
115      */
116     public static Years yearsBetween(ReadablePartial start, ReadablePartial end) {
117         if (start instanceof LocalDate && end instanceof LocalDate)   {
118             Chronology chrono = DateTimeUtils.getChronology(start.getChronology());
119             int years = chrono.years().getDifference(
120                     ((LocalDate) end).getLocalMillis(), ((LocalDate) start).getLocalMillis());
121             return Years.years(years);
122         }
123         int amount = BaseSingleFieldPeriod.between(start, end, ZERO);
124         return Years.years(amount);
125     }
126 
127     /**
128      * Creates a <code>Years</code> representing the number of whole years
129      * in the specified interval. This method corectly handles any daylight
130      * savings time changes that may occur during the interval.
131      *
132      * @param interval  the interval to extract years from, null returns zero
133      * @return the period in years
134      * @throws IllegalArgumentException if the partials are null or invalid
135      */
136     public static Years yearsIn(ReadableInterval interval) {
137         if (interval == null)   {
138             return Years.ZERO;
139         }
140         int amount = BaseSingleFieldPeriod.between(interval.getStart(), interval.getEnd(), DurationFieldType.years());
141         return Years.years(amount);
142     }
143 
144     /**
145      * Creates a new <code>Years</code> by parsing a string in the ISO8601 format 'PnY'.
146      * <p>
147      * The parse will accept the full ISO syntax of PnYnMnWnDTnHnMnS however only the
148      * years component may be non-zero. If any other component is non-zero, an exception
149      * will be thrown.
150      *
151      * @param periodStr  the period string, null returns zero
152      * @return the period in years
153      * @throws IllegalArgumentException if the string format is invalid
154      */
155     public static Years parseYears(String   periodStr) {
156         if (periodStr == null) {
157             return Years.ZERO;
158         }
159         Period p = PARSER.parsePeriod(periodStr);
160         return Years.years(p.getYears());
161     }
162 
163     //-----------------------------------------------------------------------
164     /**
165      * Creates a new instance representing a number of years.
166      * You should consider using the factory method {@link #years(int)}
167      * instead of the constructor.
168      *
169      * @param years  the number of years to represent
170      */
171     private Years(int years) {
172         super(years);
173     }
174 
175     /**
176      * Resolves singletons.
177      * 
178      * @return the singleton instance
179      */
180     private Object   readResolve() {
181         return Years.years(getValue());
182     }
183 
184     //-----------------------------------------------------------------------
185     /**
186      * Gets the duration field type, which is <code>years</code>.
187      *
188      * @return the period type
189      */
190     public DurationFieldType getFieldType() {
191         return DurationFieldType.years();
192     }
193 
194     /**
195      * Gets the period type, which is <code>years</code>.
196      *
197      * @return the period type
198      */
199     public PeriodType getPeriodType() {
200         return PeriodType.years();
201     }
202 
203     //-----------------------------------------------------------------------
204     /**
205      * Gets the number of years that this period represents.
206      *
207      * @return the number of years in the period
208      */
209     public int getYears() {
210         return getValue();
211     }
212 
213     //-----------------------------------------------------------------------
214     /**
215      * Returns a new instance with the specified number of years added.
216      * <p>
217      * This instance is immutable and unaffected by this method call.
218      *
219      * @param years  the amount of years to add, may be negative
220      * @return the new period plus the specified number of years
221      * @throws ArithmeticException if the result overflows an int
222      */
223     public Years plus(int years) {
224         if (years == 0) {
225             return this;
226         }
227         return Years.years(FieldUtils.safeAdd(getValue(), years));
228     }
229 
230     /**
231      * Returns a new instance with the specified number of years added.
232      * <p>
233      * This instance is immutable and unaffected by this method call.
234      *
235      * @param years  the amount of years to add, may be negative, null means zero
236      * @return the new period plus the specified number of years
237      * @throws ArithmeticException if the result overflows an int
238      */
239     public Years plus(Years years) {
240         if (years == null) {
241             return this;
242         }
243         return plus(years.getValue());
244     }
245 
246     //-----------------------------------------------------------------------
247     /**
248      * Returns a new instance with the specified number of years taken away.
249      * <p>
250      * This instance is immutable and unaffected by this method call.
251      *
252      * @param years  the amount of years to take away, may be negative
253      * @return the new period minus the specified number of years
254      * @throws ArithmeticException if the result overflows an int
255      */
256     public Years minus(int years) {
257         return plus(FieldUtils.safeNegate(years));
258     }
259 
260     /**
261      * Returns a new instance with the specified number of years taken away.
262      * <p>
263      * This instance is immutable and unaffected by this method call.
264      *
265      * @param years  the amount of years to take away, may be negative, null means zero
266      * @return the new period minus the specified number of years
267      * @throws ArithmeticException if the result overflows an int
268      */
269     public Years minus(Years years) {
270         if (years == null) {
271             return this;
272         }
273         return minus(years.getValue());
274     }
275 
276     //-----------------------------------------------------------------------
277     /**
278      * Returns a new instance with the years multiplied by the specified scalar.
279      * <p>
280      * This instance is immutable and unaffected by this method call.
281      *
282      * @param scalar  the amount to multiply by, may be negative
283      * @return the new period multiplied by the specified scalar
284      * @throws ArithmeticException if the result overflows an int
285      */
286     public Years multipliedBy(int scalar) {
287         return Years.years(FieldUtils.safeMultiply(getValue(), scalar));
288     }
289 
290     /**
291      * Returns a new instance with the years divided by the specified divisor.
292      * The calculation uses integer division, thus 3 divided by 2 is 1.
293      * <p>
294      * This instance is immutable and unaffected by this method call.
295      *
296      * @param divisor  the amount to divide by, may be negative
297      * @return the new period divided by the specified divisor
298      * @throws ArithmeticException if the divisor is zero
299      */
300     public Years dividedBy(int divisor) {
301         if (divisor == 1) {
302             return this;
303         }
304         return Years.years(getValue() / divisor);
305     }
306 
307     //-----------------------------------------------------------------------
308     /**
309      * Returns a new instance with the years value negated.
310      *
311      * @return the new period with a negated value
312      * @throws ArithmeticException if the result overflows an int
313      */
314     public Years negated() {
315         return Years.years(FieldUtils.safeNegate(getValue()));
316     }
317 
318     //-----------------------------------------------------------------------
319     /**
320      * Is this years instance greater than the specified number of years.
321      *
322      * @param other  the other period, null means zero
323      * @return true if this years instance is greater than the specified one
324      */
325     public boolean isGreaterThan(Years other) {
326         if (other == null) {
327             return getValue() > 0;
328         }
329         return getValue() > other.getValue();
330     }
331 
332     /**
333      * Is this years instance less than the specified number of years.
334      *
335      * @param other  the other period, null means zero
336      * @return true if this years instance is less than the specified one
337      */
338     public boolean isLessThan(Years other) {
339         if (other == null) {
340             return getValue() < 0;
341         }
342         return getValue() < other.getValue();
343     }
344 
345     //-----------------------------------------------------------------------
346     /**
347      * Gets this instance as a String in the ISO8601 duration format.
348      * <p>
349      * For example, "P4Y" represents 4 years.
350      *
351      * @return the value as an ISO8601 string
352      */
353     public String   toString() {
354         return "P" + String.valueOf(getValue()) + "Y";
355     }
356 
357 }
358
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags