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