001/* =========================================================== 002 * JFreeChart : a free chart library for the Java(tm) platform 003 * =========================================================== 004 * 005 * (C) Copyright 2000-2020, by Object Refinery Limited and Contributors. 006 * 007 * Project Info: http://www.jfree.org/jfreechart/index.html 008 * 009 * This library is free software; you can redistribute it and/or modify it 010 * under the terms of the GNU Lesser General Public License as published by 011 * the Free Software Foundation; either version 2.1 of the License, or 012 * (at your option) any later version. 013 * 014 * This library is distributed in the hope that it will be useful, but 015 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 016 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 017 * License for more details. 018 * 019 * You should have received a copy of the GNU Lesser General Public 020 * License along with this library; if not, write to the Free Software 021 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 022 * USA. 023 * 024 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 025 * Other names may be trademarks of their respective owners.] 026 * 027 */ 028 029package org.jfree.chart.date; 030 031import java.io.Serializable; 032import java.text.DateFormatSymbols; 033import java.text.SimpleDateFormat; 034import java.util.Calendar; 035import java.util.GregorianCalendar; 036 037/** 038 * An abstract class that defines our requirements for manipulating dates, 039 * without tying down a particular implementation. 040 * <P> 041 * Requirement 1 : match at least what Excel does for dates; 042 * Requirement 2 : the date represented by the class is immutable; 043 * <P> 044 * Why not just use java.util.Date? We will, when it makes sense. At times, 045 * java.util.Date can be *too* precise - it represents an instant in time, 046 * accurate to 1/1000th of a second (with the date itself depending on the 047 * time-zone). Sometimes we just want to represent a particular day (e.g. 21 048 * January 2015) without concerning ourselves about the time of day, or the 049 * time-zone, or anything else. That's what we've defined SerialDate for. 050 * <P> 051 * You can call getInstance() to get a concrete subclass of SerialDate, 052 * without worrying about the exact implementation. 053 */ 054public abstract class SerialDate implements Comparable, Serializable, 055 MonthConstants { 056 057 /** For serialization. */ 058 private static final long serialVersionUID = -293716040467423637L; 059 060 /** Date format symbols. */ 061 public static final DateFormatSymbols 062 DATE_FORMAT_SYMBOLS = new SimpleDateFormat().getDateFormatSymbols(); 063 064 /** The serial number for 1 January 1900. */ 065 public static final int SERIAL_LOWER_BOUND = 2; 066 067 /** The serial number for 31 December 9999. */ 068 public static final int SERIAL_UPPER_BOUND = 2958465; 069 070 /** The lowest year value supported by this date format. */ 071 public static final int MINIMUM_YEAR_SUPPORTED = 1900; 072 073 /** The highest year value supported by this date format. */ 074 public static final int MAXIMUM_YEAR_SUPPORTED = 9999; 075 076 /** Useful constant for Monday. Equivalent to java.util.Calendar.MONDAY. */ 077 public static final int MONDAY = Calendar.MONDAY; 078 079 /** 080 * Useful constant for Tuesday. Equivalent to java.util.Calendar.TUESDAY. 081 */ 082 public static final int TUESDAY = Calendar.TUESDAY; 083 084 /** 085 * Useful constant for Wednesday. Equivalent to 086 * java.util.Calendar.WEDNESDAY. 087 */ 088 public static final int WEDNESDAY = Calendar.WEDNESDAY; 089 090 /** 091 * Useful constant for Thrusday. Equivalent to java.util.Calendar.THURSDAY. 092 */ 093 public static final int THURSDAY = Calendar.THURSDAY; 094 095 /** Useful constant for Friday. Equivalent to java.util.Calendar.FRIDAY. */ 096 public static final int FRIDAY = Calendar.FRIDAY; 097 098 /** 099 * Useful constant for Saturday. Equivalent to java.util.Calendar.SATURDAY. 100 */ 101 public static final int SATURDAY = Calendar.SATURDAY; 102 103 /** Useful constant for Sunday. Equivalent to java.util.Calendar.SUNDAY. */ 104 public static final int SUNDAY = Calendar.SUNDAY; 105 106 /** The number of days in each month in non leap years. */ 107 static final int[] LAST_DAY_OF_MONTH = 108 {0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31}; 109 110 /** The number of days in a (non-leap) year up to the end of each month. */ 111 static final int[] AGGREGATE_DAYS_TO_END_OF_MONTH = 112 {0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334, 365}; 113 114 /** The number of days in a year up to the end of the preceding month. */ 115 static final int[] AGGREGATE_DAYS_TO_END_OF_PRECEDING_MONTH = 116 {0, 0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334, 365}; 117 118 /** The number of days in a leap year up to the end of each month. */ 119 static final int[] LEAP_YEAR_AGGREGATE_DAYS_TO_END_OF_MONTH = 120 {0, 31, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335, 366}; 121 122 /** 123 * The number of days in a leap year up to the end of the preceding month. 124 */ 125 static final int[] 126 LEAP_YEAR_AGGREGATE_DAYS_TO_END_OF_PRECEDING_MONTH = 127 {0, 0, 31, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335, 366}; 128 129 /** A useful constant for referring to the first week in a month. */ 130 public static final int FIRST_WEEK_IN_MONTH = 1; 131 132 /** A useful constant for referring to the second week in a month. */ 133 public static final int SECOND_WEEK_IN_MONTH = 2; 134 135 /** A useful constant for referring to the third week in a month. */ 136 public static final int THIRD_WEEK_IN_MONTH = 3; 137 138 /** A useful constant for referring to the fourth week in a month. */ 139 public static final int FOURTH_WEEK_IN_MONTH = 4; 140 141 /** A useful constant for referring to the last week in a month. */ 142 public static final int LAST_WEEK_IN_MONTH = 0; 143 144 /** Useful range constant. */ 145 public static final int INCLUDE_NONE = 0; 146 147 /** Useful range constant. */ 148 public static final int INCLUDE_FIRST = 1; 149 150 /** Useful range constant. */ 151 public static final int INCLUDE_SECOND = 2; 152 153 /** Useful range constant. */ 154 public static final int INCLUDE_BOTH = 3; 155 156 /** 157 * Useful constant for specifying a day of the week relative to a fixed 158 * date. 159 */ 160 public static final int PRECEDING = -1; 161 162 /** 163 * Useful constant for specifying a day of the week relative to a fixed 164 * date. 165 */ 166 public static final int NEAREST = 0; 167 168 /** 169 * Useful constant for specifying a day of the week relative to a fixed 170 * date. 171 */ 172 public static final int FOLLOWING = 1; 173 174 /** A description for the date. */ 175 private String description; 176 177 /** 178 * Default constructor. 179 */ 180 protected SerialDate() { 181 } 182 183 /** 184 * Returns {@code true} if the supplied integer code represents a 185 * valid day-of-the-week, and {@code false} otherwise. 186 * 187 * @param code the code being checked for validity. 188 * 189 * @return {@code true} if the supplied integer code represents a 190 * valid day-of-the-week, and {@code false} otherwise. 191 */ 192 public static boolean isValidWeekdayCode(int code) { 193 194 switch(code) { 195 case SUNDAY: 196 case MONDAY: 197 case TUESDAY: 198 case WEDNESDAY: 199 case THURSDAY: 200 case FRIDAY: 201 case SATURDAY: 202 return true; 203 default: 204 return false; 205 } 206 207 } 208 209 /** 210 * Converts the supplied string to a day of the week. 211 * 212 * @param s a string representing the day of the week. 213 * 214 * @return {@code -1} if the string is not convertable, the day of 215 * the week otherwise. 216 */ 217 public static int stringToWeekdayCode(String s) { 218 219 final String[] shortWeekdayNames 220 = DATE_FORMAT_SYMBOLS.getShortWeekdays(); 221 final String[] weekDayNames = DATE_FORMAT_SYMBOLS.getWeekdays(); 222 223 int result = -1; 224 s = s.trim(); 225 for (int i = 0; i < weekDayNames.length; i++) { 226 if (s.equals(shortWeekdayNames[i])) { 227 result = i; 228 break; 229 } 230 if (s.equals(weekDayNames[i])) { 231 result = i; 232 break; 233 } 234 } 235 return result; 236 237 } 238 239 /** 240 * Returns a string representing the supplied day-of-the-week. 241 * <P> 242 * Need to find a better approach. 243 * 244 * @param weekday the day of the week. 245 * 246 * @return a string representing the supplied day-of-the-week. 247 */ 248 public static String weekdayCodeToString(int weekday) { 249 final String[] weekdays = DATE_FORMAT_SYMBOLS.getWeekdays(); 250 return weekdays[weekday]; 251 } 252 253 /** 254 * Returns an array of month names. 255 * 256 * @return an array of month names. 257 */ 258 public static String[] getMonths() { 259 260 return getMonths(false); 261 262 } 263 264 /** 265 * Returns an array of month names. 266 * 267 * @param shortened a flag indicating that shortened month names should 268 * be returned. 269 * 270 * @return an array of month names. 271 */ 272 public static String[] getMonths(boolean shortened) { 273 if (shortened) { 274 return DATE_FORMAT_SYMBOLS.getShortMonths(); 275 } 276 else { 277 return DATE_FORMAT_SYMBOLS.getMonths(); 278 } 279 } 280 281 /** 282 * Returns true if the supplied integer code represents a valid month. 283 * 284 * @param code the code being checked for validity. 285 * 286 * @return {@code true} if the supplied integer code represents a 287 * valid month. 288 */ 289 public static boolean isValidMonthCode(int code) { 290 291 switch(code) { 292 case JANUARY: 293 case FEBRUARY: 294 case MARCH: 295 case APRIL: 296 case MAY: 297 case JUNE: 298 case JULY: 299 case AUGUST: 300 case SEPTEMBER: 301 case OCTOBER: 302 case NOVEMBER: 303 case DECEMBER: 304 return true; 305 default: 306 return false; 307 } 308 309 } 310 311 /** 312 * Returns the quarter for the specified month. 313 * 314 * @param code the month code (1-12). 315 * 316 * @return the quarter that the month belongs to. 317 */ 318 public static int monthCodeToQuarter(int code) { 319 320 switch(code) { 321 case JANUARY: 322 case FEBRUARY: 323 case MARCH: return 1; 324 case APRIL: 325 case MAY: 326 case JUNE: return 2; 327 case JULY: 328 case AUGUST: 329 case SEPTEMBER: return 3; 330 case OCTOBER: 331 case NOVEMBER: 332 case DECEMBER: return 4; 333 default: throw new IllegalArgumentException( 334 "SerialDate.monthCodeToQuarter: invalid month code."); 335 } 336 337 } 338 339 /** 340 * Returns a string representing the supplied month. 341 * <P> 342 * The string returned is the long form of the month name taken from the 343 * default locale. 344 * 345 * @param month the month. 346 * 347 * @return a string representing the supplied month. 348 */ 349 public static String monthCodeToString(int month) { 350 return monthCodeToString(month, false); 351 } 352 353 /** 354 * Returns a string representing the supplied month. 355 * <P> 356 * The string returned is the long or short form of the month name taken 357 * from the default locale. 358 * 359 * @param month the month. 360 * @param shortened if {@code true} return the abbreviation of the month. 361 * 362 * @return a string representing the supplied month. 363 */ 364 public static String monthCodeToString(int month, boolean shortened) { 365 366 // check arguments... 367 if (!isValidMonthCode(month)) { 368 throw new IllegalArgumentException( 369 "SerialDate.monthCodeToString: month outside valid range."); 370 } 371 372 final String[] months; 373 374 if (shortened) { 375 months = DATE_FORMAT_SYMBOLS.getShortMonths(); 376 } 377 else { 378 months = DATE_FORMAT_SYMBOLS.getMonths(); 379 } 380 381 return months[month - 1]; 382 383 } 384 385 /** 386 * Converts a string to a month code. 387 * <P> 388 * This method will return one of the constants JANUARY, FEBRUARY, ..., 389 * DECEMBER that corresponds to the string. If the string is not 390 * recognised, this method returns -1. 391 * 392 * @param s the string to parse. 393 * 394 * @return {@code -1} if the string is not parseable, the month of the 395 * year otherwise. 396 */ 397 public static int stringToMonthCode(String s) { 398 399 final String[] shortMonthNames = DATE_FORMAT_SYMBOLS.getShortMonths(); 400 final String[] monthNames = DATE_FORMAT_SYMBOLS.getMonths(); 401 402 int result = -1; 403 s = s.trim(); 404 405 // first try parsing the string as an integer (1-12)... 406 try { 407 result = Integer.parseInt(s); 408 } 409 catch (NumberFormatException e) { 410 // suppress 411 } 412 413 // now search through the month names... 414 if ((result < 1) || (result > 12)) { 415 for (int i = 0; i < monthNames.length; i++) { 416 if (s.equals(shortMonthNames[i])) { 417 result = i + 1; 418 break; 419 } 420 if (s.equals(monthNames[i])) { 421 result = i + 1; 422 break; 423 } 424 } 425 } 426 427 return result; 428 429 } 430 431 /** 432 * Returns true if the supplied integer code represents a valid 433 * week-in-the-month, and false otherwise. 434 * 435 * @param code the code being checked for validity. 436 * @return {@code true} if the supplied integer code represents a 437 * valid week-in-the-month. 438 */ 439 public static boolean isValidWeekInMonthCode(int code) { 440 switch(code) { 441 case FIRST_WEEK_IN_MONTH: 442 case SECOND_WEEK_IN_MONTH: 443 case THIRD_WEEK_IN_MONTH: 444 case FOURTH_WEEK_IN_MONTH: 445 case LAST_WEEK_IN_MONTH: return true; 446 default: return false; 447 } 448 } 449 450 /** 451 * Determines whether or not the specified year is a leap year. 452 * 453 * @param yyyy the year (in the range 1900 to 9999). 454 * 455 * @return {@code true} if the specified year is a leap year. 456 */ 457 public static boolean isLeapYear(int yyyy) { 458 459 if ((yyyy % 4) != 0) { 460 return false; 461 } 462 else if ((yyyy % 400) == 0) { 463 return true; 464 } 465 else if ((yyyy % 100) == 0) { 466 return false; 467 } 468 else { 469 return true; 470 } 471 472 } 473 474 /** 475 * Returns the number of leap years from 1900 to the specified year 476 * INCLUSIVE. 477 * <P> 478 * Note that 1900 is not a leap year. 479 * 480 * @param yyyy the year (in the range 1900 to 9999). 481 * 482 * @return the number of leap years from 1900 to the specified year. 483 */ 484 public static int leapYearCount(int yyyy) { 485 int leap4 = (yyyy - 1896) / 4; 486 int leap100 = (yyyy - 1800) / 100; 487 int leap400 = (yyyy - 1600) / 400; 488 return leap4 - leap100 + leap400; 489 } 490 491 /** 492 * Returns the number of the last day of the month, taking into account 493 * leap years. 494 * 495 * @param month the month. 496 * @param yyyy the year (in the range 1900 to 9999). 497 * 498 * @return the number of the last day of the month. 499 */ 500 public static int lastDayOfMonth(int month, int yyyy) { 501 502 final int result = LAST_DAY_OF_MONTH[month]; 503 if (month != FEBRUARY) { 504 return result; 505 } 506 else if (isLeapYear(yyyy)) { 507 return result + 1; 508 } 509 else { 510 return result; 511 } 512 513 } 514 515 /** 516 * Creates a new date by adding the specified number of days to the base 517 * date. 518 * 519 * @param days the number of days to add (can be negative). 520 * @param base the base date. 521 * 522 * @return a new date. 523 */ 524 public static SerialDate addDays(int days, SerialDate base) { 525 int serialDayNumber = base.toSerial() + days; 526 return SerialDate.createInstance(serialDayNumber); 527 } 528 529 /** 530 * Creates a new date by adding the specified number of months to the base 531 * date. 532 * <P> 533 * If the base date is close to the end of the month, the day on the result 534 * may be adjusted slightly: 31 May + 1 month = 30 June. 535 * 536 * @param months the number of months to add (can be negative). 537 * @param base the base date. 538 * 539 * @return a new date. 540 */ 541 public static SerialDate addMonths(int months, SerialDate base) { 542 int yy = (12 * base.getYYYY() + base.getMonth() + months - 1) / 12; 543 int mm = (12 * base.getYYYY() + base.getMonth() + months - 1) % 12 + 1; 544 int dd = Math.min(base.getDayOfMonth(), 545 SerialDate.lastDayOfMonth(mm, yy)); 546 return SerialDate.createInstance(dd, mm, yy); 547 } 548 549 /** 550 * Creates a new date by adding the specified number of years to the base 551 * date. 552 * 553 * @param years the number of years to add (can be negative). 554 * @param base the base date. 555 * 556 * @return A new date. 557 */ 558 public static SerialDate addYears(int years, SerialDate base) { 559 int baseY = base.getYYYY(); 560 int baseM = base.getMonth(); 561 int baseD = base.getDayOfMonth(); 562 563 int targetY = baseY + years; 564 int targetD = Math.min(baseD, SerialDate.lastDayOfMonth(baseM, targetY)); 565 return SerialDate.createInstance(targetD, baseM, targetY); 566 } 567 568 /** 569 * Returns the latest date that falls on the specified day-of-the-week and 570 * is BEFORE the base date. 571 * 572 * @param targetWeekday a code for the target day-of-the-week. 573 * @param base the base date. 574 * 575 * @return the latest date that falls on the specified day-of-the-week and 576 * is BEFORE the base date. 577 */ 578 public static SerialDate getPreviousDayOfWeek(int targetWeekday, 579 SerialDate base) { 580 581 // check arguments... 582 if (!SerialDate.isValidWeekdayCode(targetWeekday)) { 583 throw new IllegalArgumentException("Invalid day-of-the-week code."); 584 } 585 586 // find the date... 587 int adjust; 588 int baseDOW = base.getDayOfWeek(); 589 if (baseDOW > targetWeekday) { 590 adjust = Math.min(0, targetWeekday - baseDOW); 591 } else { 592 adjust = -7 + Math.max(0, targetWeekday - baseDOW); 593 } 594 595 return SerialDate.addDays(adjust, base); 596 597 } 598 599 /** 600 * Returns the earliest date that falls on the specified day-of-the-week 601 * and is AFTER the base date. 602 * 603 * @param targetWeekday a code for the target day-of-the-week. 604 * @param base the base date. 605 * 606 * @return the earliest date that falls on the specified day-of-the-week 607 * and is AFTER the base date. 608 */ 609 public static SerialDate getFollowingDayOfWeek(int targetWeekday, 610 SerialDate base) { 611 612 // check arguments... 613 if (!SerialDate.isValidWeekdayCode(targetWeekday)) { 614 throw new IllegalArgumentException( 615 "Invalid day-of-the-week code." 616 ); 617 } 618 619 // find the date... 620 int adjust; 621 int baseDOW = base.getDayOfWeek(); 622 if (baseDOW > targetWeekday) { 623 adjust = 7 + Math.min(0, targetWeekday - baseDOW); 624 } else { 625 adjust = Math.max(0, targetWeekday - baseDOW); 626 } 627 628 return SerialDate.addDays(adjust, base); 629 } 630 631 /** 632 * Returns the date that falls on the specified day-of-the-week and is 633 * CLOSEST to the base date. 634 * 635 * @param targetDOW a code for the target day-of-the-week. 636 * @param base the base date. 637 * 638 * @return the date that falls on the specified day-of-the-week and is 639 * CLOSEST to the base date. 640 */ 641 public static SerialDate getNearestDayOfWeek(int targetDOW, SerialDate base) { 642 643 // check arguments... 644 if (!SerialDate.isValidWeekdayCode(targetDOW)) { 645 throw new IllegalArgumentException("Invalid day-of-the-week code."); 646 } 647 648 // find the date... 649 final int baseDOW = base.getDayOfWeek(); 650 int adjust = -Math.abs(targetDOW - baseDOW); 651 if (adjust >= 4) { 652 adjust = 7 - adjust; 653 } 654 if (adjust <= -4) { 655 adjust = 7 + adjust; 656 } 657 return SerialDate.addDays(adjust, base); 658 659 } 660 661 /** 662 * Rolls the date forward to the last day of the month. 663 * 664 * @param base the base date. 665 * 666 * @return a new serial date. 667 */ 668 public SerialDate getEndOfCurrentMonth(SerialDate base) { 669 int last = SerialDate.lastDayOfMonth(base.getMonth(), base.getYYYY()); 670 return SerialDate.createInstance(last, base.getMonth(), base.getYYYY()); 671 } 672 673 /** 674 * Returns a string corresponding to the week-in-the-month code. 675 * <P> 676 * Need to find a better approach. 677 * 678 * @param count an integer code representing the week-in-the-month. 679 * 680 * @return a string corresponding to the week-in-the-month code. 681 */ 682 public static String weekInMonthToString(int count) { 683 684 switch (count) { 685 case SerialDate.FIRST_WEEK_IN_MONTH : return "First"; 686 case SerialDate.SECOND_WEEK_IN_MONTH : return "Second"; 687 case SerialDate.THIRD_WEEK_IN_MONTH : return "Third"; 688 case SerialDate.FOURTH_WEEK_IN_MONTH : return "Fourth"; 689 case SerialDate.LAST_WEEK_IN_MONTH : return "Last"; 690 default : 691 return "SerialDate.weekInMonthToString(): invalid code."; 692 } 693 694 } 695 696 /** 697 * Returns a string representing the supplied 'relative'. 698 * <P> 699 * Need to find a better approach. 700 * 701 * @param relative a constant representing the 'relative'. 702 * 703 * @return a string representing the supplied 'relative'. 704 */ 705 public static String relativeToString(int relative) { 706 707 switch (relative) { 708 case SerialDate.PRECEDING : return "Preceding"; 709 case SerialDate.NEAREST : return "Nearest"; 710 case SerialDate.FOLLOWING : return "Following"; 711 default : return "ERROR : Relative To String"; 712 } 713 714 } 715 716 /** 717 * Factory method that returns an instance of some concrete subclass of 718 * {@link SerialDate}. 719 * 720 * @param day the day (1-31). 721 * @param month the month (1-12). 722 * @param yyyy the year (in the range 1900 to 9999). 723 * 724 * @return An instance of {@link SerialDate}. 725 */ 726 public static SerialDate createInstance(int day, int month, int yyyy) { 727 return new SpreadsheetDate(day, month, yyyy); 728 } 729 730 /** 731 * Factory method that returns an instance of some concrete subclass of 732 * {@link SerialDate}. 733 * 734 * @param serial the serial number for the day (1 January 1900 = 2). 735 * 736 * @return a instance of SerialDate. 737 */ 738 public static SerialDate createInstance(int serial) { 739 return new SpreadsheetDate(serial); 740 } 741 742 /** 743 * Factory method that returns an instance of a subclass of SerialDate. 744 * 745 * @param date A Java date object. 746 * 747 * @return a instance of SerialDate. 748 */ 749 public static SerialDate createInstance(java.util.Date date) { 750 751 GregorianCalendar calendar = new GregorianCalendar(); 752 calendar.setTime(date); 753 return new SpreadsheetDate(calendar.get(Calendar.DATE), 754 calendar.get(Calendar.MONTH) + 1, calendar.get(Calendar.YEAR)); 755 756 } 757 758 /** 759 * Returns the serial number for the date, where 1 January 1900 = 2 (this 760 * corresponds, almost, to the numbering system used in Microsoft Excel for 761 * Windows and Lotus 1-2-3). 762 * 763 * @return the serial number for the date. 764 */ 765 public abstract int toSerial(); 766 767 /** 768 * Returns a java.util.Date. Since java.util.Date has more precision than 769 * SerialDate, we need to define a convention for the 'time of day'. 770 * 771 * @return this as {@code java.util.Date}. 772 */ 773 public abstract java.util.Date toDate(); 774 775 /** 776 * Returns the description that is attached to the date. It is not 777 * required that a date have a description, but for some applications it 778 * is useful. 779 * 780 * @return The description (possibly {@code null}). 781 */ 782 public String getDescription() { 783 return this.description; 784 } 785 786 /** 787 * Sets the description for the date. 788 * 789 * @param description the description for this date ({@code null} 790 * permitted). 791 */ 792 public void setDescription(String description) { 793 this.description = description; 794 } 795 796 /** 797 * Converts the date to a string. 798 * 799 * @return a string representation of the date. 800 */ 801 @Override 802 public String toString() { 803 return getDayOfMonth() + "-" + SerialDate.monthCodeToString(getMonth()) 804 + "-" + getYYYY(); 805 } 806 807 /** 808 * Returns the year (assume a valid range of 1900 to 9999). 809 * 810 * @return the year. 811 */ 812 public abstract int getYYYY(); 813 814 /** 815 * Returns the month (January = 1, February = 2, March = 3). 816 * 817 * @return the month of the year. 818 */ 819 public abstract int getMonth(); 820 821 /** 822 * Returns the day of the month. 823 * 824 * @return the day of the month. 825 */ 826 public abstract int getDayOfMonth(); 827 828 /** 829 * Returns the day of the week. 830 * 831 * @return the day of the week. 832 */ 833 public abstract int getDayOfWeek(); 834 835 /** 836 * Returns the difference (in days) between this date and the specified 837 * 'other' date. 838 * <P> 839 * The result is positive if this date is after the 'other' date and 840 * negative if it is before the 'other' date. 841 * 842 * @param other the date being compared to. 843 * 844 * @return the difference between this and the other date. 845 */ 846 public abstract int compare(SerialDate other); 847 848 /** 849 * Returns true if this SerialDate represents the same date as the 850 * specified SerialDate. 851 * 852 * @param other the date being compared to. 853 * 854 * @return {@code true} if this SerialDate represents the same date as 855 * the specified SerialDate. 856 */ 857 public abstract boolean isOn(SerialDate other); 858 859 /** 860 * Returns true if this SerialDate represents an earlier date compared to 861 * the specified SerialDate. 862 * 863 * @param other The date being compared to. 864 * 865 * @return {@code true} if this SerialDate represents an earlier date 866 * compared to the specified SerialDate. 867 */ 868 public abstract boolean isBefore(SerialDate other); 869 870 /** 871 * Returns true if this SerialDate represents the same date as the 872 * specified SerialDate. 873 * 874 * @param other the date being compared to. 875 * 876 * @return {@code true} if this SerialDate represents the same date 877 * as the specified SerialDate. 878 */ 879 public abstract boolean isOnOrBefore(SerialDate other); 880 881 /** 882 * Returns true if this SerialDate represents the same date as the 883 * specified SerialDate. 884 * 885 * @param other the date being compared to. 886 * 887 * @return {@code true} if this SerialDate represents the same date 888 * as the specified SerialDate. 889 */ 890 public abstract boolean isAfter(SerialDate other); 891 892 /** 893 * Returns true if this SerialDate represents the same date as the 894 * specified SerialDate. 895 * 896 * @param other the date being compared to. 897 * 898 * @return {@code true} if this SerialDate represents the same date 899 * as the specified SerialDate. 900 */ 901 public abstract boolean isOnOrAfter(SerialDate other); 902 903 /** 904 * Returns {@code true} if this {@link SerialDate} is within the 905 * specified range (INCLUSIVE). The date order of d1 and d2 is not 906 * important. 907 * 908 * @param d1 a boundary date for the range. 909 * @param d2 the other boundary date for the range. 910 * 911 * @return A boolean. 912 */ 913 public abstract boolean isInRange(SerialDate d1, SerialDate d2); 914 915 /** 916 * Returns {@code true} if this {@link SerialDate} is within the 917 * specified range (caller specifies whether or not the end-points are 918 * included). The date order of d1 and d2 is not important. 919 * 920 * @param d1 a boundary date for the range. 921 * @param d2 the other boundary date for the range. 922 * @param include a code that controls whether or not the start and end 923 * dates are included in the range. 924 * 925 * @return A boolean. 926 */ 927 public abstract boolean isInRange(SerialDate d1, SerialDate d2, 928 int include); 929 930 /** 931 * Returns the latest date that falls on the specified day-of-the-week and 932 * is BEFORE this date. 933 * 934 * @param targetDOW a code for the target day-of-the-week. 935 * 936 * @return the latest date that falls on the specified day-of-the-week and 937 * is BEFORE this date. 938 */ 939 public SerialDate getPreviousDayOfWeek(int targetDOW) { 940 return getPreviousDayOfWeek(targetDOW, this); 941 } 942 943 /** 944 * Returns the earliest date that falls on the specified day-of-the-week 945 * and is AFTER this date. 946 * 947 * @param targetDOW a code for the target day-of-the-week. 948 * 949 * @return the earliest date that falls on the specified day-of-the-week 950 * and is AFTER this date. 951 */ 952 public SerialDate getFollowingDayOfWeek(int targetDOW) { 953 return getFollowingDayOfWeek(targetDOW, this); 954 } 955 956 /** 957 * Returns the nearest date that falls on the specified day-of-the-week. 958 * 959 * @param targetDOW a code for the target day-of-the-week. 960 * 961 * @return the nearest date that falls on the specified day-of-the-week. 962 */ 963 public SerialDate getNearestDayOfWeek(int targetDOW) { 964 return getNearestDayOfWeek(targetDOW, this); 965 } 966 967} 968