001: /*
002: * Copyright 2001-2006 Stephen Colebourne
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.joda.time;
017:
018: import org.joda.time.base.BaseSingleFieldPeriod;
019: import org.joda.time.field.FieldUtils;
020: import org.joda.time.format.ISOPeriodFormat;
021: import org.joda.time.format.PeriodFormatter;
022:
023: /**
024: * An immutable time period representing a number of days.
025: * <p>
026: * <code>Days</code> is an immutable period that can only store days.
027: * It does not store years, months or hours for example. As such it is a
028: * type-safe way of representing a number of days in an application.
029: * <p>
030: * The number of days is set in the constructor, and may be queried using
031: * <code>getDays()</code>. Basic mathematical operations are provided -
032: * <code>plus()</code>, <code>minus()</code>, <code>multipliedBy()</code> and
033: * <code>dividedBy()</code>.
034: * <p>
035: * <code>Days</code> is thread-safe and immutable.
036: *
037: * @author Stephen Colebourne
038: * @since 1.4
039: */
040: public final class Days extends BaseSingleFieldPeriod {
041:
042: /** Constant representing zero days. */
043: public static final Days ZERO = new Days(0);
044: /** Constant representing one day. */
045: public static final Days ONE = new Days(1);
046: /** Constant representing two days. */
047: public static final Days TWO = new Days(2);
048: /** Constant representing three days. */
049: public static final Days THREE = new Days(3);
050: /** Constant representing four days. */
051: public static final Days FOUR = new Days(4);
052: /** Constant representing five days. */
053: public static final Days FIVE = new Days(5);
054: /** Constant representing six days. */
055: public static final Days SIX = new Days(6);
056: /** Constant representing seven days. */
057: public static final Days SEVEN = new Days(7);
058: /** Constant representing the maximum number of days that can be stored in this object. */
059: public static final Days MAX_VALUE = new Days(Integer.MAX_VALUE);
060: /** Constant representing the minimum number of days that can be stored in this object. */
061: public static final Days MIN_VALUE = new Days(Integer.MIN_VALUE);
062:
063: /** The paser to use for this class. */
064: private static final PeriodFormatter PARSER = ISOPeriodFormat
065: .standard().withParseType(PeriodType.days());
066: /** Serialization version. */
067: private static final long serialVersionUID = 87525275727380865L;
068:
069: //-----------------------------------------------------------------------
070: /**
071: * Obtains an instance of <code>Days</code> that may be cached.
072: * <code>Days</code> is immutable, so instances can be cached and shared.
073: * This factory method provides access to shared instances.
074: *
075: * @param days the number of days to obtain an instance for
076: * @return the instance of Days
077: */
078: public static Days days(int days) {
079: switch (days) {
080: case 0:
081: return ZERO;
082: case 1:
083: return ONE;
084: case 2:
085: return TWO;
086: case 3:
087: return THREE;
088: case 4:
089: return FOUR;
090: case 5:
091: return FIVE;
092: case 6:
093: return SIX;
094: case 7:
095: return SEVEN;
096: case Integer.MAX_VALUE:
097: return MAX_VALUE;
098: case Integer.MIN_VALUE:
099: return MIN_VALUE;
100: default:
101: return new Days(days);
102: }
103: }
104:
105: //-----------------------------------------------------------------------
106: /**
107: * Creates a <code>Days</code> representing the number of whole days
108: * between the two specified datetimes. This method corectly handles
109: * any daylight savings time changes that may occur during the interval.
110: *
111: * @param start the start instant, must not be null
112: * @param end the end instant, must not be null
113: * @return the period in days
114: * @throws IllegalArgumentException if the instants are null or invalid
115: */
116: public static Days daysBetween(ReadableInstant start,
117: ReadableInstant end) {
118: int amount = BaseSingleFieldPeriod.between(start, end,
119: DurationFieldType.days());
120: return Days.days(amount);
121: }
122:
123: /**
124: * Creates a <code>Days</code> representing the number of whole days
125: * between the two specified partial datetimes.
126: * <p>
127: * The two partials must contain the same fields, for example you can specify
128: * two <code>LocalDate</code> objects.
129: *
130: * @param start the start partial date, must not be null
131: * @param end the end partial date, must not be null
132: * @return the period in days
133: * @throws IllegalArgumentException if the partials are null or invalid
134: */
135: public static Days daysBetween(ReadablePartial start,
136: ReadablePartial end) {
137: if (start instanceof LocalDate && end instanceof LocalDate) {
138: Chronology chrono = DateTimeUtils.getChronology(start
139: .getChronology());
140: int days = chrono.days().getDifference(
141: ((LocalDate) end).getLocalMillis(),
142: ((LocalDate) start).getLocalMillis());
143: return Days.days(days);
144: }
145: int amount = BaseSingleFieldPeriod.between(start, end, ZERO);
146: return Days.days(amount);
147: }
148:
149: /**
150: * Creates a <code>Days</code> representing the number of whole days
151: * in the specified interval. This method corectly handles any daylight
152: * savings time changes that may occur during the interval.
153: *
154: * @param interval the interval to extract days from, null returns zero
155: * @return the period in days
156: * @throws IllegalArgumentException if the partials are null or invalid
157: */
158: public static Days daysIn(ReadableInterval interval) {
159: if (interval == null) {
160: return Days.ZERO;
161: }
162: int amount = BaseSingleFieldPeriod.between(interval.getStart(),
163: interval.getEnd(), DurationFieldType.days());
164: return Days.days(amount);
165: }
166:
167: /**
168: * Creates a new <code>Days</code> representing the number of complete
169: * standard length days in the specified period.
170: * <p>
171: * This factory method converts all fields from the period to hours using standardised
172: * durations for each field. Only those fields which have a precise duration in
173: * the ISO UTC chronology can be converted.
174: * <ul>
175: * <li>One week consists of 7 days.
176: * <li>One day consists of 24 hours.
177: * <li>One hour consists of 60 minutes.
178: * <li>One minute consists of 60 seconds.
179: * <li>One second consists of 1000 milliseconds.
180: * </ul>
181: * Months and Years are imprecise and periods containing these values cannot be converted.
182: *
183: * @param period the period to get the number of hours from, null returns zero
184: * @return the period in days
185: * @throws IllegalArgumentException if the period contains imprecise duration values
186: */
187: public static Days standardDaysIn(ReadablePeriod period) {
188: int amount = BaseSingleFieldPeriod.standardPeriodIn(period,
189: DateTimeConstants.MILLIS_PER_DAY);
190: return Days.days(amount);
191: }
192:
193: /**
194: * Creates a new <code>Days</code> by parsing a string in the ISO8601 format 'PnD'.
195: * <p>
196: * The parse will accept the full ISO syntax of PnYnMnWnDTnHnMnS however only the
197: * days component may be non-zero. If any other component is non-zero, an exception
198: * will be thrown.
199: *
200: * @param periodStr the period string, null returns zero
201: * @return the period in days
202: * @throws IllegalArgumentException if the string format is invalid
203: */
204: public static Days parseDays(String periodStr) {
205: if (periodStr == null) {
206: return Days.ZERO;
207: }
208: Period p = PARSER.parsePeriod(periodStr);
209: return Days.days(p.getDays());
210: }
211:
212: //-----------------------------------------------------------------------
213: /**
214: * Creates a new instance representing a number of days.
215: * You should consider using the factory method {@link #days(int)}
216: * instead of the constructor.
217: *
218: * @param days the number of days to represent
219: */
220: private Days(int days) {
221: super (days);
222: }
223:
224: /**
225: * Resolves singletons.
226: *
227: * @return the singleton instance
228: */
229: private Object readResolve() {
230: return Days.days(getValue());
231: }
232:
233: //-----------------------------------------------------------------------
234: /**
235: * Gets the duration field type, which is <code>days</code>.
236: *
237: * @return the period type
238: */
239: public DurationFieldType getFieldType() {
240: return DurationFieldType.days();
241: }
242:
243: /**
244: * Gets the period type, which is <code>days</code>.
245: *
246: * @return the period type
247: */
248: public PeriodType getPeriodType() {
249: return PeriodType.days();
250: }
251:
252: //-----------------------------------------------------------------------
253: /**
254: * Converts this period in days to a period in weeks assuming a
255: * 7 day week.
256: * <p>
257: * This method allows you to convert between different types of period.
258: * However to achieve this it makes the assumption that all weeks are
259: * 7 days long.
260: * This may not be true for some unusual chronologies. However, it is included
261: * as it is a useful operation for many applications and business rules.
262: *
263: * @return a period representing the number of weeks for this number of days
264: */
265: public Weeks toStandardWeeks() {
266: return Weeks
267: .weeks(getValue() / DateTimeConstants.DAYS_PER_WEEK);
268: }
269:
270: /**
271: * Converts this period in days to a period in hours assuming a
272: * 24 hour day.
273: * <p>
274: * This method allows you to convert between different types of period.
275: * However to achieve this it makes the assumption that all days are 24 hours long.
276: * This is not true when daylight savings is considered and may also not
277: * be true for some unusual chronologies. However, it is included
278: * as it is a useful operation for many applications and business rules.
279: *
280: * @return a period representing the number of hours for this number of days
281: * @throws ArithmeticException if the number of hours is too large to be represented
282: */
283: public Hours toStandardHours() {
284: return Hours.hours(FieldUtils.safeMultiply(getValue(),
285: DateTimeConstants.HOURS_PER_DAY));
286: }
287:
288: /**
289: * Converts this period in days to a period in minutes assuming a
290: * 24 hour day and 60 minute hour.
291: * <p>
292: * This method allows you to convert between different types of period.
293: * However to achieve this it makes the assumption that all days are 24 hours
294: * long and all hours are 60 minutes long.
295: * This is not true when daylight savings is considered and may also not
296: * be true for some unusual chronologies. However, it is included
297: * as it is a useful operation for many applications and business rules.
298: *
299: * @return a period representing the number of minutes for this number of days
300: * @throws ArithmeticException if the number of minutes is too large to be represented
301: */
302: public Minutes toStandardMinutes() {
303: return Minutes.minutes(FieldUtils.safeMultiply(getValue(),
304: DateTimeConstants.MINUTES_PER_DAY));
305: }
306:
307: /**
308: * Converts this period in days to a period in seconds assuming a
309: * 24 hour day, 60 minute hour and 60 second minute.
310: * <p>
311: * This method allows you to convert between different types of period.
312: * However to achieve this it makes the assumption that all days are 24 hours
313: * long, all hours are 60 minutes long and all minutes are 60 seconds long.
314: * This is not true when daylight savings is considered and may also not
315: * be true for some unusual chronologies. However, it is included
316: * as it is a useful operation for many applications and business rules.
317: *
318: * @return a period representing the number of seconds for this number of days
319: * @throws ArithmeticException if the number of seconds is too large to be represented
320: */
321: public Seconds toStandardSeconds() {
322: return Seconds.seconds(FieldUtils.safeMultiply(getValue(),
323: DateTimeConstants.SECONDS_PER_DAY));
324: }
325:
326: //-----------------------------------------------------------------------
327: /**
328: * Converts this period in days to a duration in milliseconds assuming a
329: * 24 hour day, 60 minute hour and 60 second minute.
330: * <p>
331: * This method allows you to convert from a period to a duration.
332: * However to achieve this it makes the assumption that all days are 24 hours
333: * long, all hours are 60 minutes and all minutes are 60 seconds.
334: * This is not true when daylight savings time is considered, and may also
335: * not be true for some unusual chronologies. However, it is included as it
336: * is a useful operation for many applications and business rules.
337: *
338: * @return a duration equivalent to this number of days
339: */
340: public Duration toStandardDuration() {
341: long days = getValue(); // assign to a long
342: return new Duration(days * DateTimeConstants.MILLIS_PER_DAY);
343: }
344:
345: //-----------------------------------------------------------------------
346: /**
347: * Gets the number of days that this period represents.
348: *
349: * @return the number of days in the period
350: */
351: public int getDays() {
352: return getValue();
353: }
354:
355: //-----------------------------------------------------------------------
356: /**
357: * Returns a new instance with the specified number of days added.
358: * <p>
359: * This instance is immutable and unaffected by this method call.
360: *
361: * @param days the amount of days to add, may be negative
362: * @return the new period plus the specified number of days
363: * @throws ArithmeticException if the result overflows an int
364: */
365: public Days plus(int days) {
366: if (days == 0) {
367: return this ;
368: }
369: return Days.days(FieldUtils.safeAdd(getValue(), days));
370: }
371:
372: /**
373: * Returns a new instance with the specified number of days added.
374: * <p>
375: * This instance is immutable and unaffected by this method call.
376: *
377: * @param days the amount of days to add, may be negative, null means zero
378: * @return the new period plus the specified number of days
379: * @throws ArithmeticException if the result overflows an int
380: */
381: public Days plus(Days days) {
382: if (days == null) {
383: return this ;
384: }
385: return plus(days.getValue());
386: }
387:
388: //-----------------------------------------------------------------------
389: /**
390: * Returns a new instance with the specified number of days taken away.
391: * <p>
392: * This instance is immutable and unaffected by this method call.
393: *
394: * @param days the amount of days to take away, may be negative
395: * @return the new period minus the specified number of days
396: * @throws ArithmeticException if the result overflows an int
397: */
398: public Days minus(int days) {
399: return plus(FieldUtils.safeNegate(days));
400: }
401:
402: /**
403: * Returns a new instance with the specified number of days taken away.
404: * <p>
405: * This instance is immutable and unaffected by this method call.
406: *
407: * @param days the amount of days to take away, may be negative, null means zero
408: * @return the new period minus the specified number of days
409: * @throws ArithmeticException if the result overflows an int
410: */
411: public Days minus(Days days) {
412: if (days == null) {
413: return this ;
414: }
415: return minus(days.getValue());
416: }
417:
418: //-----------------------------------------------------------------------
419: /**
420: * Returns a new instance with the days multiplied by the specified scalar.
421: * <p>
422: * This instance is immutable and unaffected by this method call.
423: *
424: * @param scalar the amount to multiply by, may be negative
425: * @return the new period multiplied by the specified scalar
426: * @throws ArithmeticException if the result overflows an int
427: */
428: public Days multipliedBy(int scalar) {
429: return Days.days(FieldUtils.safeMultiply(getValue(), scalar));
430: }
431:
432: /**
433: * Returns a new instance with the days divided by the specified divisor.
434: * The calculation uses integer division, thus 3 divided by 2 is 1.
435: * <p>
436: * This instance is immutable and unaffected by this method call.
437: *
438: * @param divisor the amount to divide by, may be negative
439: * @return the new period divided by the specified divisor
440: * @throws ArithmeticException if the divisor is zero
441: */
442: public Days dividedBy(int divisor) {
443: if (divisor == 1) {
444: return this ;
445: }
446: return Days.days(getValue() / divisor);
447: }
448:
449: //-----------------------------------------------------------------------
450: /**
451: * Returns a new instance with the days value negated.
452: *
453: * @return the new period with a negated value
454: * @throws ArithmeticException if the result overflows an int
455: */
456: public Days negated() {
457: return Days.days(FieldUtils.safeNegate(getValue()));
458: }
459:
460: //-----------------------------------------------------------------------
461: /**
462: * Is this days instance greater than the specified number of days.
463: *
464: * @param other the other period, null means zero
465: * @return true if this days instance is greater than the specified one
466: */
467: public boolean isGreaterThan(Days other) {
468: if (other == null) {
469: return getValue() > 0;
470: }
471: return getValue() > other.getValue();
472: }
473:
474: /**
475: * Is this days instance less than the specified number of days.
476: *
477: * @param other the other period, null means zero
478: * @return true if this days instance is less than the specified one
479: */
480: public boolean isLessThan(Days other) {
481: if (other == null) {
482: return getValue() < 0;
483: }
484: return getValue() < other.getValue();
485: }
486:
487: //-----------------------------------------------------------------------
488: /**
489: * Gets this instance as a String in the ISO8601 duration format.
490: * <p>
491: * For example, "P4D" represents 4 days.
492: *
493: * @return the value as an ISO8601 string
494: */
495: public String toString() {
496: return "P" + String.valueOf(getValue()) + "D";
497: }
498:
499: }
|