[kaffe] CVS kaffe (robilad): Resynced with GNU Classpath: Improved GregorianCalendar documentation
Kaffe CVS
cvs-commits at kaffe.org
Sun Nov 7 06:39:03 PST 2004
PatchSet 5411
Date: 2004/11/07 14:34:00
Author: robilad
Branch: HEAD
Tag: (none)
Log:
Resynced with GNU Classpath: Improved GregorianCalendar documentation
2004-11-07 Dalibor Topic <robilad at kaffe.org>
* libraries/javalib/java/util/GregorianCalendar.java:
Resynced with GNU Classpath.
2004-11-01 Andrew John Hughes <gnu_andrew at member.fsf.org>
* java/util/GregorianCalendar.java
Added/amended documentation.
Members:
ChangeLog:1.2960->1.2961
libraries/javalib/java/util/GregorianCalendar.java:1.26->1.27
Index: kaffe/ChangeLog
diff -u kaffe/ChangeLog:1.2960 kaffe/ChangeLog:1.2961
--- kaffe/ChangeLog:1.2960 Sun Nov 7 14:23:18 2004
+++ kaffe/ChangeLog Sun Nov 7 14:34:00 2004
@@ -1,5 +1,15 @@
2004-11-07 Dalibor Topic <robilad at kaffe.org>
+ * libraries/javalib/java/util/GregorianCalendar.java:
+ Resynced with GNU Classpath.
+
+ 2004-11-01 Andrew John Hughes <gnu_andrew at member.fsf.org>
+
+ * java/util/GregorianCalendar.java
+ Added/amended documentation.
+
+2004-11-07 Dalibor Topic <robilad at kaffe.org>
+
* libraries/javalib/java/beans/PropertyEditorSupport.java:
Resynced with GNU Classpath.
Index: kaffe/libraries/javalib/java/util/GregorianCalendar.java
diff -u kaffe/libraries/javalib/java/util/GregorianCalendar.java:1.26 kaffe/libraries/javalib/java/util/GregorianCalendar.java:1.27
--- kaffe/libraries/javalib/java/util/GregorianCalendar.java:1.26 Mon Oct 18 13:04:32 2004
+++ kaffe/libraries/javalib/java/util/GregorianCalendar.java Sun Nov 7 14:34:03 2004
@@ -39,27 +39,104 @@
package java.util;
+import java.io.IOException;
+import java.io.ObjectInputStream;
+
/**
+ * <p>
* This class represents the Gregorian calendar, that is used in most
* countries all over the world. It does also handle the Julian calendar
* for dates smaller than the date of the change to the Gregorian calendar.
- * This change date is different from country to country, you can set it with
- * <code>setGregorianChange</code>
- *
* The Gregorian calendar differs from the Julian calendar by a different
* leap year rule (no leap year every 100 years, except if year is divisible
- * by 400). The non existing days that were omited when the change took
- * place are interpreted as gregorian date
- *
- * There are to eras available for the Gregorian calendar, namely BC and AD.
+ * by 400).
+ * </p>
+ * <p>
+ * This change date is different from country to country, and can be changed with
+ * <code>setGregorianChange</code>. The first countries to adopt the Gregorian
+ * calendar did so on the 15th of October, 1582. This date followed October
+ * the 4th, 1582 in the Julian calendar system. The non-existant days that were
+ * omitted when the change took place are interpreted as Gregorian dates.
+ * </p>
+ * <p>
+ * Prior to the changeover date, New Year's Day occurred on the 25th of March.
+ * However, this class always takes New Year's Day as being the 1st of January.
+ * Client code should manually adapt the year value, if required, for dates
+ * between January the 1st and March the 24th in years prior to the changeover.
+ * </p>
+ * <p>
+ * Any date infinitely forwards or backwards in time can be represented by
+ * this class. A <em>proleptic</em> calendar system is used, which allows
+ * future dates to be created via the existing rules. This allows meaningful
+ * and consistent dates to be produced for all years. However, dates are only
+ * historically accurate following March the 1st, 4AD when the Julian calendar
+ * system was adopted. Prior to this, leap year rules were applied erraticly.
+ * </p>
+ * <p>
+ * There are two eras available for the Gregorian calendar, namely BC and AD.
+ * </p>
+ * <p>
+ * Weeks are defined as a period of seven days, beginning on the first day
+ * of the week, as returned by <code>getFirstDayOfWeek()</code>, and ending
+ * on the day prior to this.
+ * </p>
+ * <p>
+ * The weeks of the year are numbered from 1 to a possible 53. The first week
+ * of the year is defined as the first week that contains at least the minimum
+ * number of days of the first week in the new year (retrieved via
+ * <code>getMinimalDaysInFirstWeek()</code>). All weeks after this are numbered
+ * from 2 onwards.
+ * </p>
+ * <p>
+ * For example, take the year 2004. It began on a Thursday. The first week
+ * of 2004 depends both on where a week begins and how long it must minimally
+ * last. Let's say that the week begins on a Monday and must have a minimum
+ * of 5 days. In this case, the first week begins on Monday, the 5th of January.
+ * The first 4 days (Thursday to Sunday) are not eligible, as they are too few
+ * to make up the minimum number of days of the first week which must be in
+ * the new year. If the minimum was lowered to 4 days, then the first week
+ * would instead begin on Monday, the 29th of December, 2003. This first week
+ * has 4 of its days in the new year, and is now eligible.
+ * </p>
+ * <p>
+ * The weeks of the month are numbered from 0 to a possible 6. The first week
+ * of the month (numbered 1) is a set of days, prior to the first day of the week,
+ * which number at least the minimum number of days in a week. Unlike the first
+ * week of the year, the first week of the month only uses days from that particular
+ * month. As a consequence, it may have a variable number of days (from the minimum
+ * number required up to a full week of 7) and it need not start on the first day of
+ * the week. It must, however, be following by the first day of the week, as this
+ * marks the beginning of week 2. Any days of the month which occur prior to the
+ * first week (because the first day of the week occurs before the minimum number
+ * of days is met) are seen as week 0.
+ * </p>
+ * <p>
+ * Again, we will take the example of the year 2004 to demonstrate this. September
+ * 2004 begins on a Wednesday. Taking our first day of the week as Monday, and the
+ * minimum length of the first week as 6, we find that week 1 runs from Monday,
+ * the 6th of September to Sunday the 12th. Prior to the 6th, there are only
+ * 5 days (Wednesday through to Sunday). This is too small a number to meet the
+ * minimum, so these are classed as being days in week 0. Week 2 begins on the
+ * 13th, and so on. This changes if we reduce the minimum to 5. In this case,
+ * week 1 is a truncated week from Wednesday the 1st to Sunday the 5th, and week
+ * 0 doesn't exist. The first seven day week is week 2, starting on the 6th.
+ * </p>
+ * <p>
+ * On using the <code>clear()</code> method, the Gregorian calendar returns
+ * to its default value of the 1st of January, 1970 AD 00:00:00 (the epoch).
+ * The day of the week is set to the correct day for that particular time.
+ * The day is also the first of the month, and the date is in week 0.
+ * </p>
*
* @see Calendar
* @see TimeZone
+ * @see Calendar#getFirstDayOfWeek()
+ * @see Calendar#getMinimalDaysInFirstWeek()
*/
public class GregorianCalendar extends Calendar
{
/**
- * Constant representing the era BC (before Christ).
+ * Constant representing the era BC (Before Christ).
*/
public static final int BC = 0;
@@ -73,9 +150,15 @@
* This is locale dependent; the default for most catholic
* countries is midnight (UTC) on October 5, 1582 (Julian),
* or October 15, 1582 (Gregorian).
+ *
+ * @serial the changeover point from the Julian calendar
+ * system to the Gregorian.
*/
private long gregorianCutover;
+ /**
+ * For compatability with Sun's JDK.
+ */
static final long serialVersionUID = -8125100834729963327L;
/**
@@ -84,9 +167,12 @@
private static final String bundleName = "gnu.java.locale.Calendar";
/**
- * get resource bundle:
- * The resources should be loaded via this method only. Iff an application
- * uses this method, the resourcebundle is required. --Fridi.
+ * Retrieves the resource bundle. The resources should be loaded
+ * via this method only. Iff an application uses this method, the
+ * resourcebundle is required.
+ *
+ * @param locale the locale in use for this calendar.
+ * @return A resource bundle for the calendar for the specified locale.
*/
private static ResourceBundle getBundle(Locale locale)
{
@@ -105,7 +191,8 @@
/**
* Constructs a new GregorianCalender representing the current
- * time, using the specified time zone and the default locale.
+ * time, using the specified time zone and the default locale.
+ *
* @param zone a time zone.
*/
public GregorianCalendar(TimeZone zone)
@@ -115,7 +202,8 @@
/**
* Constructs a new GregorianCalender representing the current
- * time, using the default time zone and the specified locale.
+ * time, using the default time zone and the specified locale.
+ *
* @param locale a locale.
*/
public GregorianCalendar(Locale locale)
@@ -126,6 +214,7 @@
/**
* Constructs a new GregorianCalender representing the current
* time with the given time zone and the given locale.
+ *
* @param zone a time zone.
* @param locale a locale.
*/
@@ -152,6 +241,7 @@
/**
* Constructs a new GregorianCalendar representing midnight on the
* given date with the default time zone and locale.
+ *
* @param year corresponds to the YEAR time field.
* @param month corresponds to the MONTH time field.
* @param day corresponds to the DAY time field.
@@ -165,6 +255,7 @@
/**
* Constructs a new GregorianCalendar representing midnight on the
* given date with the default time zone and locale.
+ *
* @param year corresponds to the YEAR time field.
* @param month corresponds to the MONTH time field.
* @param day corresponds to the DAY time field.
@@ -180,6 +271,7 @@
/**
* Constructs a new GregorianCalendar representing midnight on the
* given date with the default time zone and locale.
+ *
* @param year corresponds to the YEAR time field.
* @param month corresponds to the MONTH time field.
* @param day corresponds to the DAY time field.
@@ -199,6 +291,7 @@
* You can use <code>new Date(Long.MAX_VALUE)</code> to use a pure
* Julian calendar, or <code>Long.MIN_VALUE</code> for a pure Gregorian
* calendar.
+ *
* @param date the date of the change.
*/
public void setGregorianChange(Date date)
@@ -208,6 +301,7 @@
/**
* Gets the date of the switch from Julian dates to Gregorian dates.
+ *
* @return the date of the change.
*/
public final Date getGregorianChange()
@@ -216,17 +310,21 @@
}
/**
+ * <p>
* Determines if the given year is a leap year. The result is
- * undefined if the gregorian change took place in 1800, so that
- * the end of february is skiped and you give that year
- * (well...).<br>
- *
- * The year should be positive and you can't give an ERA. But
- * remember that before 4 BC there wasn't a consistent leap year
- * rule, so who cares.
+ * undefined if the Gregorian change took place in 1800, so that
+ * the end of February is skipped, and that year is specified.
+ * (well...).
+ * </p>
+ * <p>
+ * To specify a year in the BC era, use a negative value calculated
+ * as 1 - y, where y is the required year in BC. So, 1 BC is 0,
+ * 2 BC is -1, 3 BC is -2, etc.
+ * </p>
*
- * @param year a year use nonnegative value for BC.
- * @return true, if the given year is a leap year, false otherwise. */
+ * @param year a year (use a negative value for BC).
+ * @return true, if the given year is a leap year, false otherwise.
+ */
public boolean isLeapYear(int year)
{
if ((year & 3) != 0)
@@ -256,11 +354,12 @@
* @param year the year of the date.
* @param dayOfYear the day of year of the date; 1 based.
* @param millis the millisecond in that day.
- * @return the days since the epoch, may be negative. */
+ * @return the days since the epoch, may be negative.
+ */
private long getLinearTime(int year, int dayOfYear, int millis)
{
// The 13 is the number of days, that were omitted in the Gregorian
- // Calender until the epoch.
+ // Calendar until the epoch.
// We shift right by 2 instead of dividing by 4, to get correct
// results for negative years (and this is even more efficient).
int julianDay = ((year * (365 * 4 + 1)) >> 2) + dayOfYear -
@@ -288,6 +387,14 @@
return time;
}
+ /**
+ * Retrieves the day of the week corresponding to the specified
+ * day of the specified year.
+ *
+ * @param year the year in which the dayOfYear occurs.
+ * @param dayOfYear the day of the year (an integer between 0 and
+ * and 366)
+ */
private int getWeekDay(int year, int dayOfYear)
{
int day =
@@ -301,20 +408,24 @@
}
/**
+ * <p>
* Calculate the dayOfYear from the fields array.
* The relativeDays is used, to account for weeks that begin before
- * the gregorian change and end after it.<br>
- *
- * We return two values, the first is used to determine, if we
- * should use Gregorian calendar or Julian calendar, in case of
- * the change year, the second is a relative day after the given
+ * the Gregorian change and end after it.
+ * </p>
+ * <p>
+ * We return two values. The first is used to determine, if we
+ * should use the Gregorian calendar or the Julian calendar, in order
+ * to handle the change year. The second is a relative day after the given
* day. This is necessary for week calculation in the year in
- * which gregorian change occurs. <br>
- *
+ * which the Gregorian change occurs.
+ * </p>
+ *
* @param year the year, negative for BC.
- * @return an array of two int values, the first containing a reference
- * day of current year, the second a relative count since this reference
- * day. */
+ * @return an array of two integer values, the first containing a reference
+ * day in the current year, the second a relative count since this reference
+ * day.
+ */
private int[] getDayOfYear(int year)
{
if (isSet[MONTH])
@@ -399,6 +510,9 @@
/**
* Converts the time field values (<code>fields</code>) to
* milliseconds since the epoch UTC (<code>time</code>).
+ *
+ * @throws IllegalArgumentException if any calendar fields
+ * are invalid.
*/
protected synchronized void computeTime()
{
@@ -493,15 +607,19 @@
}
/**
+ * <p>
* Determines if the given year is a leap year.
+ * </p>
+ * <p>
+ * To specify a year in the BC era, use a negative value calculated
+ * as 1 - y, where y is the required year in BC. So, 1 BC is 0,
+ * 2 BC is -1, 3 BC is -2, etc.
+ * </p>
*
- * The year should be positive and you can't give an ERA. But
- * remember that before 4 BC there wasn't a consistent leap year
- * rule, so who cares.
- *
- * @param year a year use nonnegative value for BC.
- * @param gregorian if true, use gregorian leap year rule.
- * @return true, if the given year is a leap year, false otherwise. */
+ * @param year a year (use a negative value for BC).
+ * @param gregorian if true, use the gregorian leap year rule.
+ * @return true, if the given year is a leap year, false otherwise.
+ */
private boolean isLeapYear(int year, boolean gregorian)
{
if ((year & 3) != 0)
@@ -523,8 +641,9 @@
*
* @param year the year of the date.
* @param dayOfYear the day of year of the date; 1 based.
- * @param gregorian True, if we should use Gregorian rules.
- * @return the days since the epoch, may be negative. */
+ * @param gregorian <code>true</code>, if we should use the Gregorian rules.
+ * @return the days since the epoch, may be negative.
+ */
private long getLinearDay(int year, int dayOfYear, boolean gregorian)
{
// The 13 is the number of days, that were omitted in the Gregorian
@@ -557,7 +676,9 @@
* Converts the given linear day into era, year, month,
* day_of_year, day_of_month, day_of_week, and writes the result
* into the fields array.
+ *
* @param day the linear day.
+ * @param gregorian true, if we should use Gregorian rules.
*/
private void calculateDay(int[] fields, long day, boolean gregorian)
{
@@ -616,7 +737,7 @@
/**
* Converts the milliseconds since the epoch UTC
* (<code>time</code>) to time fields
- * (<code>fields</code>).
+ * (<code>fields</code>).
*/
protected synchronized void computeFields()
{
@@ -688,11 +809,19 @@
}
/**
- * Compares the given calender with this.
+ * Compares the given calendar with this. An object, o, is
+ * equivalent to this if it is also a <code>GregorianCalendar</code>
+ * with the same time since the epoch under the same conditions
+ * (same change date and same time zone).
+ *
* @param o the object to that we should compare.
* @return true, if the given object is a calendar, that represents
- * the same time (but doesn't necessary have the same fields).
- * @XXX Should we check if time zones, locale, cutover etc. are equal?
+ * the same time (but doesn't necessarily have the same fields).
+ * @throws IllegalArgumentException if one of the fields
+ * <code>ZONE_OFFSET</code> or <code>DST_OFFSET</code> is
+ * specified, if an unknown field is specified or if one
+ * of the calendar fields receives an illegal value when
+ * leniancy is not enabled.
*/
public boolean equals(Object o)
{
@@ -735,8 +864,8 @@
* Adds the specified amount of time to the given time field. The
* amount may be negative to subtract the time. If the field overflows
* it does what you expect: Jan, 25 + 10 Days is Feb, 4.
- * @param field the time field. One of the time field constants.
- * @param amount the amount of time.
+ * @param field one of the time field constants.
+ * @param amount the amount of time to add.
* @exception IllegalArgumentException if <code>field</code> is
* <code>ZONE_OFFSET</code>, <code>DST_OFFSET</code>, or invalid; or
* if <code>amount</code> contains an out-of-range value and the calendar
@@ -837,12 +966,26 @@
*
* @param field the time field. One of the time field constants.
* @param up the direction, true for up, false for down.
+ * @throws IllegalArgumentException if one of the fields
+ * <code>ZONE_OFFSET</code> or <code>DST_OFFSET</code> is
+ * specified, if an unknown field is specified or if one
+ * of the calendar fields receives an illegal value when
+ * leniancy is not enabled.
*/
public void roll(int field, boolean up)
{
roll(field, up ? 1 : -1);
}
+ /**
+ * Checks that the fields are still within their legal bounds,
+ * following use of the <code>roll()</code> method.
+ *
+ * @param field the field to check.
+ * @param delta multipler for alterations to the <code>time</code>.
+ * @see #roll(int, boolean)
+ * @see #roll(int, int)
+ */
private void cleanUpAfterRoll(int field, int delta)
{
switch (field)
@@ -940,6 +1083,11 @@
*
* @param field the time field. One of the time field constants.
* @param amount the amount by which we should roll.
+ * @throws IllegalArgumentException if one of the fields
+ * <code>ZONE_OFFSET</code> or <code>DST_OFFSET</code> is
+ * specified, if an unknown field is specified or if one
+ * of the calendar fields receives an illegal value when
+ * leniancy is not enabled.
*/
public void roll(int field, int amount)
{
@@ -964,18 +1112,25 @@
cleanUpAfterRoll(field, newval - oldval);
}
+ /**
+ * The minimum values for the calendar fields.
+ */
private static final int[] minimums =
{ BC, 1, 0, 0, 1, 1, 1, SUNDAY, 1,
AM, 1, 0, 1, 1, 1, -(12*60*60*1000), 0 };
+ /**
+ * The maximum values for the calendar fields.
+ */
private static final int[] maximums =
{ AD, 5000000, 11, 53, 5, 31, 366, SATURDAY, 5,
PM, 12, 23, 59, 59, 999, +(12*60*60*1000), (12*60*60*1000) };
/**
* Gets the smallest value that is allowed for the specified field.
- * @param field the time field. One of the time field constants.
- * @return the smallest value.
+ *
+ * @param field one of the time field constants.
+ * @return the smallest value for the specified field.
*/
public int getMinimum(int field)
{
@@ -984,7 +1139,8 @@
/**
* Gets the biggest value that is allowed for the specified field.
- * @param field the time field. One of the time field constants.
+ *
+ * @param field one of the time field constants.
* @return the biggest value.
*/
public int getMaximum(int field)
@@ -995,8 +1151,12 @@
/**
* Gets the greatest minimum value that is allowed for the specified field.
+ * This is the largest value returned by the <code>getActualMinimum(int)</code>
+ * method.
+ *
* @param field the time field. One of the time field constants.
* @return the greatest minimum value.
+ * @see #getActualMinimum(int)
*/
public int getGreatestMinimum(int field)
{
@@ -1007,10 +1167,15 @@
/**
* Gets the smallest maximum value that is allowed for the
- * specified field. For example this is 28 for DAY_OF_MONTH.
+ * specified field. This is the smallest value returned
+ * by the <code>getActualMaximum(int)</code>. For example,
+ * this is 28 for DAY_OF_MONTH (as all months have at least
+ * 28 days).
+ *
* @param field the time field. One of the time field constants.
* @return the least maximum value.
- * @since jdk1.2
+ * @see #getActualMaximum(int)
+ * @since 1.2
*/
public int getLeastMaximum(int field)
{
@@ -1034,10 +1199,12 @@
* Gets the actual minimum value that is allowed for the specified field.
* This value is dependent on the values of the other fields. Note that
* this calls <code>complete()</code> if not enough fields are set. This
- * can have ugly side effects.
+ * can have ugly side effects. The value given depends on the current
+ * time used by this instance.
+ *
* @param field the time field. One of the time field constants.
* @return the actual minimum value.
- * @since jdk1.2
+ * @since 1.2
*/
public int getActualMinimum(int field)
{
@@ -1062,7 +1229,10 @@
* Gets the actual maximum value that is allowed for the specified field.
* This value is dependent on the values of the other fields. Note that
* this calls <code>complete()</code> if not enough fields are set. This
- * can have ugly side effects.
+ * can have ugly side effects. The value given depends on the current time
+ * used by this instance; thus, leap years have a maximum day of month value of
+ * 29, rather than 28.
+ *
* @param field the time field. One of the time field constants.
* @return the actual maximum value.
*/
@@ -1085,8 +1255,13 @@
int minimalDays = getMinimalDaysInFirstWeek();
int firstWeekday = getWeekDay(year, minimalDays);
+ /*
+ * Is there a set of days at the beginning of the year, before the
+ * first day of the week, equal to or greater than the minimum number
+ * of days required in the first week?
+ */
if (minimalDays - (7 + firstWeekday - getFirstDayOfWeek()) % 7 < 1)
- return week + 1;
+ return week + 1; /* Add week 1: firstWeekday through to firstDayOfWeek */
}
case DAY_OF_MONTH:
{
@@ -1133,4 +1308,6 @@
return maximums[field];
}
}
+
+
}
More information about the kaffe
mailing list