1 /*
2 * Copyright 2001-2013 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.field;
17
18 import org.joda.time.DateTimeFieldType;
19 import org.joda.time.DurationField;
20
21 /**
22 * Precise datetime field, composed of two precise duration fields.
23 * <p>
24 * This DateTimeField is useful for defining DateTimeFields that are composed
25 * of precise durations, like time of day fields. If either duration field is
26 * imprecise, then an {@link ImpreciseDateTimeField} may be used instead.
27 * <p>
28 * PreciseDateTimeField is thread-safe and immutable.
29 *
30 * @author Brian S O'Neill
31 * @author Stephen Colebourne
32 * @since 1.0
33 * @see ImpreciseDateTimeField
34 */
35 public class PreciseDateTimeField extends PreciseDurationDateTimeField {
36
37 @SuppressWarnings("unused")
38 private static final long serialVersionUID = -5586801265774496376L;
39
40 /** The maximum range in the correct units */
41 private final int iRange;
42
43 private final DurationField iRangeField;
44
45 /**
46 * Constructor.
47 *
48 * @param type the field type this field uses
49 * @param unit precise unit duration, like "seconds()".
50 * @param range precise range duration, preferably a multiple of the unit,
51 * like "minutes()".
52 * @throws IllegalArgumentException if either duration field is imprecise
53 * @throws IllegalArgumentException if unit milliseconds is less than one
54 * or effective value range is less than two.
55 */
56 public PreciseDateTimeField(DateTimeFieldType type,
57 DurationField unit, DurationField range) {
58 super(type, unit);
59
60 if (!range.isPrecise()) {
61 throw new IllegalArgumentException("Range duration field must be precise");
62 }
63
64 long rangeMillis = range.getUnitMillis();
65 iRange = (int)(rangeMillis / getUnitMillis());
66 if (iRange < 2) {
67 throw new IllegalArgumentException("The effective range must be at least 2");
68 }
69
70 iRangeField = range;
71 }
72
73 /**
74 * Get the amount of fractional units from the specified time instant.
75 *
76 * @param instant the milliseconds from 1970-01-01T00:00:00Z to query
77 * @return the amount of fractional units extracted from the input.
78 */
79 public int get(long instant) {
80 if (instant >= 0) {
81 return (int) ((instant / getUnitMillis()) % iRange);
82 } else {
83 return iRange - 1 + (int) (((instant + 1) / getUnitMillis()) % iRange);
84 }
85 }
86
87 /**
88 * Add to the component of the specified time instant, wrapping around
89 * within that component if necessary.
90 *
91 * @param instant the milliseconds from 1970-01-01T00:00:00Z to add to
92 * @param amount the amount of units to add (can be negative).
93 * @return the updated time instant.
94 */
95 public long addWrapField(long instant, int amount) {
96 int thisValue = get(instant);
97 int wrappedValue = FieldUtils.getWrappedValue
98 (thisValue, amount, getMinimumValue(), getMaximumValue());
99 // copy code from set() to avoid repeat call to get()
100 return instant + (wrappedValue - thisValue) * getUnitMillis();
101 }
102
103 /**
104 * Set the specified amount of units to the specified time instant.
105 *
106 * @param instant the milliseconds from 1970-01-01T00:00:00Z to set in
107 * @param value value of units to set.
108 * @return the updated time instant.
109 * @throws IllegalArgumentException if value is too large or too small.
110 */
111 public long set(long instant, int value) {
112 FieldUtils.verifyValueBounds(this, value, getMinimumValue(), getMaximumValue());
113 return instant + (value - get(instant)) * iUnitMillis;
114 }
115
116 /**
117 * Returns the range duration of this field. For example, if this field
118 * represents "minute of hour", then the range duration field is an hours.
119 *
120 * @return the range duration of this field, or null if field has no range
121 */
122 public DurationField getRangeDurationField() {
123 return iRangeField;
124 }
125
126 /**
127 * Get the maximum value for the field.
128 *
129 * @return the maximum value
130 */
131 public int getMaximumValue() {
132 return iRange - 1;
133 }
134
135 /**
136 * Returns the range of the field in the field's units.
137 * <p>
138 * For example, 60 for seconds per minute. The field is allowed values
139 * from 0 to range - 1.
140 *
141 * @return unit range
142 */
143 public int getRange() {
144 return iRange;
145 }
146
147 }
148