Dates and times often need to be processed even when they are not fully valid. Calendrical permits that processing to occur, however the cost is a complicated state model. Use this class with care.
Instances of calendrical hold any combination of date and time information. The five pieces of state are date, time, offset, zone and a field-value map. Each piece of state is optional, allowing the calendrical to contain incomplete information.
The state of a calendrical can conflict itself. For example, the date might be '2007-12-03' while the field-value map holds the month as February. This can be checked using {@link #checkConsistent()}. Values that can be derived from other values, such as MonthOfYear from date, can be removed using {@link #removeDerivable()}.
The state in the field-value map can also be merged according to rules. For example, parsing might read in 'HourOfAmPm=9', 'AmPm=PM' and 'MinuteOfHour=25'. Using the {@link #mergeStrict()} and related methods these different fields canbe merged into a LocalTime.
Virtually any two parts of the state can conflict. For example, the offset might be '+01:00' while the time zone is 'Asia/Tokyo'. This is invalid as the offset '+01:00' is never valid for Tokyo. This can be checked manually if desired before calling {@link #toZonedDateTime()}.
Finally, the field-value map may contain values that are outside the normal range for the field. For example, a day of month of -3 or an hour of 1000. The {@link #mergeLenient()} method can be used to interpret these values.
Each method is documented to explain how it handles the possible conflicting cases. A key method is {@link #merge(CalendricalContext)} which takes all the availabledata and attempts to merge it together into meaningful information.
Calendrical is mutable and cannot be shared safely between threads without external synchronization. @author Michael Nascimento Santos @author Stephen Colebourne
| |
| |
| |
| |
| |