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