1 /* Copyright 2002-2013 CS Systèmes d'Information
2 * Licensed to CS Systèmes d'Information (CS) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * CS licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.orekit.time;
18
19 import java.io.Serializable;
20 import java.text.DecimalFormat;
21 import java.util.regex.Matcher;
22 import java.util.regex.Pattern;
23
24 import org.orekit.errors.OrekitException;
25 import org.orekit.errors.OrekitMessages;
26
27 /** Class representing a date broken up as year, month and day components.
28 * <p>This class uses the astronomical convention for calendars,
29 * which is also the convention used by <code>java.util.Date</code>:
30 * a year zero is present between years -1 and +1, and 10 days are
31 * missing in 1582. The calendar used around these special dates are:</p>
32 * <ul>
33 * <li>up to 0000-12-31 : proleptic julian calendar</li>
34 * <li>from 0001-01-01 to 1582-10-04: julian calendar</li>
35 * <li>from 1582-10-15: gregorian calendar</li>
36 * </ul>
37 * <p>Instances of this class are guaranteed to be immutable.</p>
38 * @see TimeComponents
39 * @see DateTimeComponents
40 * @author Luc Maisonobe
41 */
42 public class DateComponents implements Serializable, Comparable<DateComponents> {
43
44 /** Reference epoch for julian dates: -4712-01-01.
45 * <p>Both <code>java.util.Date</code> and {@link DateComponents} classes
46 * follow the astronomical conventions and consider a year 0 between
47 * years -1 and +1, hence this reference date lies in year -4712 and not
48 * in year -4713 as can be seen in other documents or programs that obey
49 * a different convention (for example the <code>convcal</code> utility).</p>
50 */
51 public static final DateComponents JULIAN_EPOCH;
52
53 /** Reference epoch for modified julian dates: 1858-11-17. */
54 public static final DateComponents MODIFIED_JULIAN_EPOCH;
55
56 /** Reference epoch for 1950 dates: 1950-01-01. */
57 public static final DateComponents FIFTIES_EPOCH;
58
59 /** Reference epoch for CCSDS Time Code Format (CCSDS 301.0-B-4): 1958-01-01. */
60 public static final DateComponents CCSDS_EPOCH;
61
62 /** Reference epoch for Galileo System Time: 1999-08-22. */
63 public static final DateComponents GALILEO_EPOCH;
64
65 /** Reference epoch for GPS weeks: 1980-01-06. */
66 public static final DateComponents GPS_EPOCH;
67
68 /** J2000.0 Reference epoch: 2000-01-01. */
69 public static final DateComponents J2000_EPOCH;
70
71 /** Java Reference epoch: 1970-01-01. */
72 public static final DateComponents JAVA_EPOCH;
73
74 /** Serializable UID. */
75 private static final long serialVersionUID = -2462694707837970938L;
76
77 /** Factory for proleptic julian calendar (up to 0000-12-31). */
78 private static final YearFactory PROLEPTIC_JULIAN_FACTORY = new ProlepticJulianFactory();
79
80 /** Factory for julian calendar (from 0001-01-01 to 1582-10-04). */
81 private static final YearFactory JULIAN_FACTORY = new JulianFactory();
82
83 /** Factory for gregorian calendar (from 1582-10-15). */
84 private static final YearFactory GREGORIAN_FACTORY = new GregorianFactory();
85
86 /** Factory for leap years. */
87 private static final MonthDayFactory LEAP_YEAR_FACTORY = new LeapYearFactory();
88
89 /** Factory for non-leap years. */
90 private static final MonthDayFactory COMMON_YEAR_FACTORY = new CommonYearFactory();
91
92 /** Format for years. */
93 private static final DecimalFormat FOUR_DIGITS = new DecimalFormat("0000");
94
95 /** Format for months and days. */
96 private static final DecimalFormat TWO_DIGITS = new DecimalFormat("00");
97
98 /** Offset between J2000 epoch and modified julian day epoch. */
99 private static final int MJD_TO_J2000 = 51544;
100
101 /** Basic and extended format calendar date. */
102 private static Pattern CALENDAR_FORMAT = Pattern.compile("^(-?\\d\\d\\d\\d)-?(\\d\\d)-?(\\d\\d)$");
103
104 /** Basic and extended format ordinal date. */
105 private static Pattern ORDINAL_FORMAT = Pattern.compile("^(-?\\d\\d\\d\\d)-?(\\d\\d\\d)$");
106
107 /** Basic and extended format week date. */
108 private static Pattern WEEK_FORMAT = Pattern.compile("^(-?\\d\\d\\d\\d)-?W(\\d\\d)-?(\\d)$");
109
110 static {
111 // this static statement makes sure the reference epoch are initialized
112 // once AFTER the various factories have been set up
113 JULIAN_EPOCH = new DateComponents(-4712, 1, 1);
114 MODIFIED_JULIAN_EPOCH = new DateComponents(1858, 11, 17);
115 FIFTIES_EPOCH = new DateComponents(1950, 1, 1);
116 CCSDS_EPOCH = new DateComponents(1958, 1, 1);
117 GALILEO_EPOCH = new DateComponents(1999, 8, 22);
118 GPS_EPOCH = new DateComponents(1980, 1, 6);
119 J2000_EPOCH = new DateComponents(2000, 1, 1);
120 JAVA_EPOCH = new DateComponents(1970, 1, 1);
121 }
122
123 /** Year number. */
124 private final int year;
125
126 /** Month number. */
127 private final int month;
128
129 /** Day number. */
130 private final int day;
131
132 /** Build a date from its components.
133 * @param year year number (may be 0 or negative for BC years)
134 * @param month month number from 1 to 12
135 * @param day day number from 1 to 31
136 * @exception IllegalArgumentException if inconsistent arguments
137 * are given (parameters out of range, february 29 for non-leap years,
138 * dates during the gregorian leap in 1582 ...)
139 */
140 public DateComponents(final int year, final int month, final int day)
141 throws IllegalArgumentException {
142
143 // very rough range check
144 // (just to avoid ArrayOutOfboundException in MonthDayFactory later)
145 if ((month < 1) || (month > 12)) {
146 throw OrekitException.createIllegalArgumentException(OrekitMessages.NON_EXISTENT_MONTH,
147 month);
148 }
149
150 // start by trusting the parameters
151 this.year = year;
152 this.month = month;
153 this.day = day;
154
155 // build a check date from the J2000 day
156 final DateComponents check = new DateComponents(getJ2000Day());
157
158 // check the parameters for mismatch
159 // (i.e. invalid date components, like 29 february on non-leap years)
160 if ((year != check.year) || (month != check.month) || (day != check.day)) {
161 throw OrekitException.createIllegalArgumentException(OrekitMessages.NON_EXISTENT_YEAR_MONTH_DAY,
162 year, month, day);
163 }
164
165 }
166
167 /** Build a date from its components.
168 * @param year year number (may be 0 or negative for BC years)
169 * @param month month enumerate
170 * @param day day number from 1 to 31
171 * @exception IllegalArgumentException if inconsistent arguments
172 * are given (parameters out of range, february 29 for non-leap years,
173 * dates during the gregorian leap in 1582 ...)
174 */
175 public DateComponents(final int year, final Month month, final int day)
176 throws IllegalArgumentException {
177 this(year, month.getNumber(), day);
178 }
179
180 /** Build a date from a year and day number.
181 * @param year year number (may be 0 or negative for BC years)
182 * @param dayNumber day number in the year from 1 to 366
183 * @exception IllegalArgumentException if dayNumber is out of range
184 * with respect to year
185 */
186 public DateComponents(final int year, final int dayNumber)
187 throws IllegalArgumentException {
188 this(J2000_EPOCH, new DateComponents(year - 1, 12, 31).getJ2000Day() + dayNumber);
189 if (dayNumber != getDayOfYear()) {
190 throw OrekitException.createIllegalArgumentException(OrekitMessages.NON_EXISTENT_DAY_NUMBER_IN_YEAR,
191 dayNumber, year);
192 }
193 }
194
195 /** Build a date from its offset with respect to a {@link #J2000_EPOCH}.
196 * @param offset offset with respect to a {@link #J2000_EPOCH}
197 * @see #getJ2000Day()
198 */
199 public DateComponents(final int offset) {
200
201 // we follow the astronomical convention for calendars:
202 // we consider a year zero and 10 days are missing in 1582
203 // from 1582-10-15: gregorian calendar
204 // from 0001-01-01 to 1582-10-04: julian calendar
205 // up to 0000-12-31 : proleptic julian calendar
206 YearFactory yFactory = GREGORIAN_FACTORY;
207 if (offset < -152384) {
208 if (offset > -730122) {
209 yFactory = JULIAN_FACTORY;
210 } else {
211 yFactory = PROLEPTIC_JULIAN_FACTORY;
212 }
213 }
214 year = yFactory.getYear(offset);
215 final int dayInYear = offset - yFactory.getLastJ2000DayOfYear(year - 1);
216
217 // handle month/day according to the year being a common or leap year
218 final MonthDayFactory mdFactory =
219 yFactory.isLeap(year) ? LEAP_YEAR_FACTORY : COMMON_YEAR_FACTORY;
220 month = mdFactory.getMonth(dayInYear);
221 day = mdFactory.getDay(dayInYear, month);
222
223 }
224
225 /** Build a date from its offset with respect to a reference epoch.
226 * <p>This constructor is mainly useful to build a date from a modified
227 * julian day (using {@link #MODIFIED_JULIAN_EPOCH}) or a GPS week number
228 * (using {@link #GPS_EPOCH}).</p>
229 * @param epoch reference epoch
230 * @param offset offset with respect to a reference epoch
231 * @see #DateComponents(int)
232 * @see #getMJD()
233 */
234 public DateComponents(final DateComponents epoch, final int offset) {
235 this(epoch.getJ2000Day() + offset);
236 }
237
238 /** Build a date from week components.
239 * <p>The calendar week number is a number between 1 and 52 or 53 depending
240 * on the year. Week 1 is defined by ISO as the one that includes the first
241 * Thursday of a year. Week 1 may therefore start the previous year and week
242 * 52 or 53 may end in the next year. As an example calendar date 1995-01-01
243 * corresponds to week date 1994-W52-7 (i.e. Sunday in the last week of 1994
244 * is in fact the first day of year 1995). This date would beAnother example is calendar date
245 * 1996-12-31 which corresponds to week date 1997-W01-2 (i.e. Tuesday in the
246 * first week of 1997 is in fact the last day of year 1996).</p>
247 * @param wYear year associated to week numbering
248 * @param week week number in year,from 1 to 52 or 53
249 * @param dayOfWeek day of week, from 1 (Monday) to 7 (Sunday)
250 * @return a builded date
251 * @exception IllegalArgumentException if inconsistent arguments
252 * are given (parameters out of range, week 53 on a 52 weeks year ...)
253 */
254 public static DateComponents createFromWeekComponents(final int wYear, final int week, final int dayOfWeek)
255 throws IllegalArgumentException {
256
257 final DateComponents firstWeekMonday = new DateComponents(getFirstWeekMonday(wYear));
258 final DateComponents d = new DateComponents(firstWeekMonday, 7 * week + dayOfWeek - 8);
259
260 // check the parameters for invalid date components
261 if ((week != d.getCalendarWeek()) || (dayOfWeek != d.getDayOfWeek())) {
262 throw OrekitException.createIllegalArgumentException(OrekitMessages.NON_EXISTENT_WEEK_DATE,
263 wYear, week, dayOfWeek);
264 }
265
266 return d;
267
268 }
269
270 /** Parse a string in ISO-8601 format to build a date.
271 * <p>The supported formats are:
272 * <ul>
273 * <li>basic format calendar date: YYYYMMDD</li>
274 * <li>extended format calendar date: YYYY-MM-DD</li>
275 * <li>basic format ordinal date: YYYYDDD</li>
276 * <li>extended format ordinal date: YYYY-DDD</li>
277 * <li>basic format week date: YYYYWwwD</li>
278 * <li>extended format week date: YYYY-Www-D</li>
279 * </ul>
280 * As shown by the list above, only the complete representations defined in section 4.1
281 * of ISO-8601 standard are supported, neither expended representations nor representations
282 * with reduced accuracy are supported.
283 * </p>
284 * <p>
285 * Parsing a single integer as a julian day is <em>not</em> supported as it may be ambiguous
286 * with either the basic format calendar date or the basic format ordinal date depending
287 * on the number of digits.
288 * </p>
289 * @param string string to parse
290 * @return a parsed date
291 * @exception IllegalArgumentException if string cannot be parsed
292 */
293 public static DateComponents parseDate(final String string) {
294
295 // is the date a calendar date ?
296 final Matcher calendarMatcher = CALENDAR_FORMAT.matcher(string);
297 if (calendarMatcher.matches()) {
298 return new DateComponents(Integer.parseInt(calendarMatcher.group(1)),
299 Integer.parseInt(calendarMatcher.group(2)),
300 Integer.parseInt(calendarMatcher.group(3)));
301 }
302
303 // is the date an ordinal date ?
304 final Matcher ordinalMatcher = ORDINAL_FORMAT.matcher(string);
305 if (ordinalMatcher.matches()) {
306 return new DateComponents(Integer.parseInt(ordinalMatcher.group(1)),
307 Integer.parseInt(ordinalMatcher.group(2)));
308 }
309
310 // is the date a week date ?
311 final Matcher weekMatcher = WEEK_FORMAT.matcher(string);
312 if (weekMatcher.matches()) {
313 return createFromWeekComponents(Integer.parseInt(weekMatcher.group(1)),
314 Integer.parseInt(weekMatcher.group(2)),
315 Integer.parseInt(weekMatcher.group(3)));
316 }
317
318 throw OrekitException.createIllegalArgumentException(OrekitMessages.NON_EXISTENT_DATE, string);
319
320 }
321
322 /** Get the year number.
323 * @return year number (may be 0 or negative for BC years)
324 */
325 public int getYear() {
326 return year;
327 }
328
329 /** Get the month.
330 * @return month number from 1 to 12
331 */
332 public int getMonth() {
333 return month;
334 }
335
336 /** Get the month as an enumerate.
337 * @return month as an enumerate
338 */
339 public Month getMonthEnum() {
340 return Month.getMonth(month);
341 }
342
343 /** Get the day.
344 * @return day number from 1 to 31
345 */
346 public int getDay() {
347 return day;
348 }
349
350 /** Get the day number with respect to J2000 epoch.
351 * @return day number with respect to J2000 epoch
352 */
353 public int getJ2000Day() {
354 YearFactory yFactory = GREGORIAN_FACTORY;
355 if (year < 1583) {
356 if (year < 1) {
357 yFactory = PROLEPTIC_JULIAN_FACTORY;
358 } else if ((year < 1582) || (month < 10) || ((month < 11) && (day < 5))) {
359 yFactory = JULIAN_FACTORY;
360 }
361 }
362 final MonthDayFactory mdFactory =
363 yFactory.isLeap(year) ? LEAP_YEAR_FACTORY : COMMON_YEAR_FACTORY;
364 return yFactory.getLastJ2000DayOfYear(year - 1) +
365 mdFactory.getDayInYear(month, day);
366 }
367
368 /** Get the modified julian day.
369 * @return modified julian day
370 */
371 public int getMJD() {
372 return MJD_TO_J2000 + getJ2000Day();
373 }
374
375 /** Get the calendar week number.
376 * <p>The calendar week number is a number between 1 and 52 or 53 depending
377 * on the year. Week 1 is defined by ISO as the one that includes the first
378 * Thursday of a year. Week 1 may therefore start the previous year and week
379 * 52 or 53 may end in the next year. As an example calendar date 1995-01-01
380 * corresponds to week date 1994-W52-7 (i.e. Sunday in the last week of 1994
381 * is in fact the first day of year 1995). Another example is calendar date
382 * 1996-12-31 which corresponds to week date 1997-W01-2 (i.e. Tuesday in the
383 * first week of 1997 is in fact the last day of year 1996).</p>
384 * @return calendar week number
385 */
386 public int getCalendarWeek() {
387 final int firstWeekMonday = getFirstWeekMonday(year);
388 int daysSincefirstMonday = getJ2000Day() - firstWeekMonday;
389 if (daysSincefirstMonday < 0) {
390 // we are still in a week from previous year
391 daysSincefirstMonday += firstWeekMonday - getFirstWeekMonday(year - 1);
392 } else if (daysSincefirstMonday > 363) {
393 // up to three days at end of year may belong to first week of next year
394 // (by chance, there is no need for a specific check in year 1582 ...)
395 final int weekYearLength = getFirstWeekMonday(year + 1) - firstWeekMonday;
396 if (daysSincefirstMonday >= weekYearLength) {
397 daysSincefirstMonday -= weekYearLength;
398 }
399 }
400 return 1 + daysSincefirstMonday / 7;
401 }
402
403 /** Get the monday of a year first week.
404 * @param year year to consider
405 * @return day of the monday of the first weak of year
406 */
407 private static int getFirstWeekMonday(final int year) {
408 final int yearFirst = new DateComponents(year, 1, 1).getJ2000Day();
409 final int offsetToMonday = 4 - (yearFirst + 2) % 7;
410 return yearFirst + offsetToMonday + ((offsetToMonday > 3) ? -7 : 0);
411 }
412
413 /** Get the day of week.
414 * <p>Day of week is a number between 1 (Monday) and 7 (Sunday).</p>
415 * @return day of week
416 */
417 public int getDayOfWeek() {
418 final int dow = (getJ2000Day() + 6) % 7; // result is between -6 and +6
419 return (dow < 1) ? (dow + 7) : dow;
420 }
421
422 /** Get the day number in year.
423 * <p>Day number in year is between 1 (January 1st) and either 365 or
424 * 366 inclusive depending on year.</p>
425 * @return day number in year
426 */
427 public int getDayOfYear() {
428 return getJ2000Day() - new DateComponents(year - 1, 12, 31).getJ2000Day();
429 }
430
431 /** Get a string representation (ISO-8601) of the date.
432 * @return string representation of the date.
433 */
434 public String toString() {
435 return new StringBuffer().
436 append(FOUR_DIGITS.format(year)).append('-').
437 append(TWO_DIGITS.format(month)).append('-').
438 append(TWO_DIGITS.format(day)).
439 toString();
440 }
441
442 /** {@inheritDoc} */
443 public int compareTo(final DateComponents other) {
444 final int j2000Day = getJ2000Day();
445 final int otherJ2000Day = other.getJ2000Day();
446 if (j2000Day < otherJ2000Day) {
447 return -1;
448 } else if (j2000Day > otherJ2000Day) {
449 return 1;
450 }
451 return 0;
452 }
453
454 /** {@inheritDoc} */
455 public boolean equals(final Object other) {
456 try {
457 final DateComponents otherDate = (DateComponents) other;
458 return (otherDate != null) && (year == otherDate.year) &&
459 (month == otherDate.month) && (day == otherDate.day);
460 } catch (ClassCastException cce) {
461 return false;
462 }
463 }
464
465 /** {@inheritDoc} */
466 public int hashCode() {
467 return (year << 16) ^ (month << 8) ^ day;
468 }
469
470 /** Interface for dealing with years sequences according to some calendar. */
471 private interface YearFactory {
472
473 /** Get the year number for a given day number with respect to J2000 epoch.
474 * @param j2000Day day number with respect to J2000 epoch
475 * @return year number
476 */
477 int getYear(int j2000Day);
478
479 /** Get the day number with respect to J2000 epoch for new year's Eve.
480 * @param year year number
481 * @return day number with respect to J2000 epoch for new year's Eve
482 */
483 int getLastJ2000DayOfYear(int year);
484
485 /** Check if a year is a leap or common year.
486 * @param year year number
487 * @return true if year is a leap year
488 */
489 boolean isLeap(int year);
490
491 }
492
493 /** Class providing a years sequence compliant with the proleptic julian calendar. */
494 private static class ProlepticJulianFactory implements YearFactory {
495
496 /** {@inheritDoc} */
497 public int getYear(final int j2000Day) {
498 return -((-4 * j2000Day - 2920488) / 1461);
499 }
500
501 /** {@inheritDoc} */
502 public int getLastJ2000DayOfYear(final int year) {
503 return (1461 * year + 1) / 4 - 730123;
504 }
505
506 /** {@inheritDoc} */
507 public boolean isLeap(final int year) {
508 return (year % 4) == 0;
509 }
510
511 }
512
513 /** Class providing a years sequence compliant with the julian calendar. */
514 private static class JulianFactory implements YearFactory {
515
516 /** {@inheritDoc} */
517 public int getYear(final int j2000Day) {
518 return (4 * j2000Day + 2921948) / 1461;
519 }
520
521 /** {@inheritDoc} */
522 public int getLastJ2000DayOfYear(final int year) {
523 return (1461 * year) / 4 - 730122;
524 }
525
526 /** {@inheritDoc} */
527 public boolean isLeap(final int year) {
528 return (year % 4) == 0;
529 }
530
531 }
532
533 /** Class providing a years sequence compliant with the gregorian calendar. */
534 private static class GregorianFactory implements YearFactory {
535
536 /** {@inheritDoc} */
537 public int getYear(final int j2000Day) {
538
539 // year estimate
540 int year = (400 * j2000Day + 292194288) / 146097;
541
542 // the previous estimate is one unit too high in some rare cases
543 // (240 days in the 400 years gregorian cycle, about 0.16%)
544 if (j2000Day <= getLastJ2000DayOfYear(year - 1)) {
545 --year;
546 }
547
548 // exact year
549 return year;
550
551 }
552
553 /** {@inheritDoc} */
554 public int getLastJ2000DayOfYear(final int year) {
555 return (1461 * year) / 4 - year / 100 + year / 400 - 730120;
556 }
557
558 /** {@inheritDoc} */
559 public boolean isLeap(final int year) {
560 return ((year % 4) == 0) && (((year % 400) == 0) || ((year % 100) != 0));
561 }
562
563 }
564
565 /** Interface for dealing with months sequences according to leap/common years. */
566 private interface MonthDayFactory {
567
568 /** Get the month number for a given day number within year.
569 * @param dayInYear day number within year
570 * @return month number
571 */
572 int getMonth(int dayInYear);
573
574 /** Get the day number for given month and day number within year.
575 * @param dayInYear day number within year
576 * @param month month number
577 * @return day number
578 */
579 int getDay(int dayInYear, int month);
580
581 /** Get the day number within year for given month and day numbers.
582 * @param month month number
583 * @param day day number
584 * @return day number within year
585 */
586 int getDayInYear(int month, int day);
587
588 }
589
590 /** Class providing the months sequence for leap years. */
591 private static class LeapYearFactory implements MonthDayFactory {
592
593 /** Months succession definition. */
594 private static final int[] PREVIOUS_MONTH_END_DAY = {
595 0, 0, 31, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335
596 };
597
598 /** {@inheritDoc} */
599 public int getMonth(final int dayInYear) {
600 return (dayInYear < 32) ? 1 : (10 * dayInYear + 313) / 306;
601 }
602
603 /** {@inheritDoc} */
604 public int getDay(final int dayInYear, final int month) {
605 return dayInYear - PREVIOUS_MONTH_END_DAY[month];
606 }
607
608 /** {@inheritDoc} */
609 public int getDayInYear(final int month, final int day) {
610 return day + PREVIOUS_MONTH_END_DAY[month];
611 }
612
613 }
614
615 /** Class providing the months sequence for common years. */
616 private static class CommonYearFactory implements MonthDayFactory {
617
618 /** Months succession definition. */
619 private static final int[] PREVIOUS_MONTH_END_DAY = {
620 0, 0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334
621 };
622
623 /** {@inheritDoc} */
624 public int getMonth(final int dayInYear) {
625 return (dayInYear < 32) ? 1 : (10 * dayInYear + 323) / 306;
626 }
627
628 /** {@inheritDoc} */
629 public int getDay(final int dayInYear, final int month) {
630 return dayInYear - PREVIOUS_MONTH_END_DAY[month];
631 }
632
633 /** {@inheritDoc} */
634 public int getDayInYear(final int month, final int day) {
635 return day + PREVIOUS_MONTH_END_DAY[month];
636 }
637
638 }
639
640 }