A suite of utilities surrounding the use of the + * {@link java.util.Calendar} and {@link java.util.Date} object.
+ * + *DateUtils contains a lot of common methods considering manipulations + * of Dates or Calendars. Some methods require some extra explanation. + * The truncate, ceiling and round methods could be considered the Math.floor(), + * Math.ceil() or Math.round versions for dates + * This way date-fields will be ignored in bottom-up order. + * As a complement to these methods we've introduced some fragment-methods. + * With these methods the Date-fields will be ignored in top-down order. + * Since a date without a year is not a valid date, you have to decide in what + * kind of date-field you want your result, for instance milliseconds or days. + *
+ *+ * Several methods are provided for adding to {@code Date} objects, of the form + * {@code addXXX(Date date, int amount)}. It is important to note these methods + * use a {@code Calendar} internally (with default timezone and locale) and may + * be affected by changes to daylight saving time (DST). + *
+ * + * @since 2.0 + */ +public class DateUtils { + + /** + * Number of milliseconds in a standard second. + * @since 2.1 + */ + public static final long MILLIS_PER_SECOND = 1000; + /** + * Number of milliseconds in a standard minute. + * @since 2.1 + */ + public static final long MILLIS_PER_MINUTE = 60 * MILLIS_PER_SECOND; + /** + * Number of milliseconds in a standard hour. + * @since 2.1 + */ + public static final long MILLIS_PER_HOUR = 60 * MILLIS_PER_MINUTE; + /** + * Number of milliseconds in a standard day. + * @since 2.1 + */ + public static final long MILLIS_PER_DAY = 24 * MILLIS_PER_HOUR; + + /** + * This is half a month, so this represents whether a date is in the top + * or bottom half of the month. + */ + public static final int SEMI_MONTH = 1001; + + private static final int[][] fields = { + {Calendar.MILLISECOND}, + {Calendar.SECOND}, + {Calendar.MINUTE}, + {Calendar.HOUR_OF_DAY, Calendar.HOUR}, + {Calendar.DATE, Calendar.DAY_OF_MONTH, Calendar.AM_PM + /* Calendar.DAY_OF_YEAR, Calendar.DAY_OF_WEEK, Calendar.DAY_OF_WEEK_IN_MONTH */ + }, + {Calendar.MONTH, DateUtils.SEMI_MONTH}, + {Calendar.YEAR}, + {Calendar.ERA}}; + + /** + * A week range, starting on Sunday. + */ + public static final int RANGE_WEEK_SUNDAY = 1; + /** + * A week range, starting on Monday. + */ + public static final int RANGE_WEEK_MONDAY = 2; + /** + * A week range, starting on the day focused. + */ + public static final int RANGE_WEEK_RELATIVE = 3; + /** + * A week range, centered around the day focused. + */ + public static final int RANGE_WEEK_CENTER = 4; + /** + * A month range, the week starting on Sunday. + */ + public static final int RANGE_MONTH_SUNDAY = 5; + /** + * A month range, the week starting on Monday. + */ + public static final int RANGE_MONTH_MONDAY = 6; + + /** + * Calendar modification types. + */ + private enum ModifyType { + /** + * Truncation. + */ + TRUNCATE, + + /** + * Rounding. + */ + ROUND, + + /** + * Ceiling. + */ + CEILING + } + + /** + *{@code DateUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code DateUtils.parseDate(str);}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public DateUtils() { + super(); + } + + //----------------------------------------------------------------------- + /** + *Checks if two date objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar cal1 = Calendar.getInstance();
+ cal1.setTime(date1);
+ final Calendar cal2 = Calendar.getInstance();
+ cal2.setTime(date2);
+ return isSameDay(cal1, cal2);
+ }
+
+ /**
+ * Checks if two calendar objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either calendar isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two date objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return date1.getTime() == date2.getTime();
+ }
+
+ /**
+ * Checks if two calendar objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.getTime().getTime() == cal2.getTime().getTime();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two calendar objects represent the same local time.
+ * + *This method compares the values of the fields of the two objects. + * In addition, both calendars must be the same of the same type.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameLocalTime(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.MILLISECOND) == cal2.get(Calendar.MILLISECOND) &&
+ cal1.get(Calendar.SECOND) == cal2.get(Calendar.SECOND) &&
+ cal1.get(Calendar.MINUTE) == cal2.get(Calendar.MINUTE) &&
+ cal1.get(Calendar.HOUR_OF_DAY) == cal2.get(Calendar.HOUR_OF_DAY) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.getClass() == cal2.getClass();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable (or there were none) + */ + public static Date parseDate(final String str, final String... parsePatterns) throws ParseException { + return parseDate(str, null, parsePatterns); + } + + //----------------------------------------------------------------------- + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDate(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable (or there were none)
+ * @since 3.2
+ */
+ public static Date parseDate(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, true);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @since 2.5 + */ + public static Date parseDateStrictly(final String str, final String... parsePatterns) throws ParseException { + return parseDateStrictly(str, null, parsePatterns); + } + + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale..
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDateStrictly(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable
+ * @since 3.2
+ */
+ public static Date parseDateStrictly(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, false);
+ }
+
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * + * @param str the date to parse, not null + * @param locale the locale to use when interpretting the pattern, can be null in which + * case the default system locale is used + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @param lenient Specify whether or not date/time parsing is to be lenient. + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @see java.util.Calendar#isLenient() + */ + private static Date parseDateWithLeniency( + final String str, final Locale locale, final String[] parsePatterns, final boolean lenient) throws ParseException { + if (str == null || parsePatterns == null) { + throw new IllegalArgumentException("Date and Patterns must not be null"); + } + + final TimeZone tz = TimeZone.getDefault(); + final Locale lcl = locale==null ?Locale.getDefault() : locale; + final ParsePosition pos = new ParsePosition(0); + final Calendar calendar = Calendar.getInstance(tz, lcl); + calendar.setLenient(lenient); + + for (final String parsePattern : parsePatterns) { + FastDateParser fdp = new FastDateParser(parsePattern, tz, lcl); + calendar.clear(); + try { + if (fdp.parse(str, pos, calendar) && pos.getIndex()==str.length()) { + return calendar.getTime(); + } + } + catch(IllegalArgumentException ignore) { + // leniency is preventing calendar from being set + } + pos.setIndex(0); + } + throw new ParseException("Unable to parse the date: " + str, -1); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of years to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addYears(final Date date, final int amount) { + return add(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of months to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMonths(final Date date, final int amount) { + return add(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of weeks to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addWeeks(final Date date, final int amount) { + return add(date, Calendar.WEEK_OF_YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of days to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addDays(final Date date, final int amount) { + return add(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of hours to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addHours(final Date date, final int amount) { + return add(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of minutes to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMinutes(final Date date, final int amount) { + return add(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of seconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addSeconds(final Date date, final int amount) { + return add(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of milliseconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMilliseconds(final Date date, final int amount) { + return add(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the calendar field to add to + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + private static Date add(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + final Calendar c = Calendar.getInstance(); + c.setTime(date); + c.add(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Sets the years field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setYears(final Date date, final int amount) { + return set(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the months field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMonths(final Date date, final int amount) { + return set(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the day of month field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setDays(final Date date, final int amount) { + return set(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the hours field to a date returning a new object. Hours range + * from 0-23. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setHours(final Date date, final int amount) { + return set(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the minute field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMinutes(final Date date, final int amount) { + return set(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the seconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setSeconds(final Date date, final int amount) { + return set(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the milliseconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMilliseconds(final Date date, final int amount) { + return set(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the specified field to a date returning a new object. + * This does not use a lenient calendar. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the {@code Calendar} field to set the amount to + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + private static Date set(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + // getInstance() returns a new object, so this method is thread safe. + final Calendar c = Calendar.getInstance(); + c.setLenient(false); + c.setTime(date); + c.set(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} into a {@code Calendar}. + * + * @param date the date to convert to a Calendar + * @return the created Calendar + * @throws NullPointerException if null is passed in + * @since 3.0 + */ + public static Calendar toCalendar(final Date date) { + final Calendar c = Calendar.getInstance(); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} of a given {@code TimeZone} into a {@code Calendar} + * @param date the date to convert to a Calendar + * @param tz the time zone of the @{code date} + * @return the created Calendar + * @throws NullPointerException if {@code date} or {@code tz} is null + */ + public static Calendar toCalendar(final Date date, final TimeZone tz) { + final Calendar c = Calendar.getInstance(tz); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar round(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar rounded = (Calendar) date.clone();
+ modify(rounded, field, ModifyType.ROUND);
+ return rounded;
+ }
+
+ /**
+ * Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date round(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return round((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return round((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not round " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.TRUNCATE);
+ return gval.getTime();
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar truncate(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar truncated = (Calendar) date.clone();
+ modify(truncated, field, ModifyType.TRUNCATE);
+ return truncated;
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return truncate((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return truncate((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not truncate " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.CEILING);
+ return gval.getTime();
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Calendar ceiling(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar ceiled = (Calendar) date.clone();
+ modify(ceiled, field, ModifyType.CEILING);
+ return ceiled;
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return ceiling((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return ceiling((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not find ceiling of for type: " + date.getClass());
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Internal calculation method.
+ * + * @param val the calendar, not null + * @param field the field constant + * @param modType type to truncate, round or ceiling + * @throws ArithmeticException if the year is over 280 million + */ + private static void modify(final Calendar val, final int field, final ModifyType modType) { + if (val.get(Calendar.YEAR) > 280000000) { + throw new ArithmeticException("Calendar value too large for accurate calculations"); + } + + if (field == Calendar.MILLISECOND) { + return; + } + + // ----------------- Fix for LANG-59 ---------------------- START --------------- + // see http://issues.apache.org/jira/browse/LANG-59 + // + // Manually truncate milliseconds, seconds and minutes, rather than using + // Calendar methods. + + final Date date = val.getTime(); + long time = date.getTime(); + boolean done = false; + + // truncate milliseconds + final int millisecs = val.get(Calendar.MILLISECOND); + if (ModifyType.TRUNCATE == modType || millisecs < 500) { + time = time - millisecs; + } + if (field == Calendar.SECOND) { + done = true; + } + + // truncate seconds + final int seconds = val.get(Calendar.SECOND); + if (!done && (ModifyType.TRUNCATE == modType || seconds < 30)) { + time = time - (seconds * 1000L); + } + if (field == Calendar.MINUTE) { + done = true; + } + + // truncate minutes + final int minutes = val.get(Calendar.MINUTE); + if (!done && (ModifyType.TRUNCATE == modType || minutes < 30)) { + time = time - (minutes * 60000L); + } + + // reset time + if (date.getTime() != time) { + date.setTime(time); + val.setTime(date); + } + // ----------------- Fix for LANG-59 ----------------------- END ---------------- + + boolean roundUp = false; + for (final int[] aField : fields) { + for (final int element : aField) { + if (element == field) { + //This is our field... we stop looping + if (modType == ModifyType.CEILING || modType == ModifyType.ROUND && roundUp) { + if (field == DateUtils.SEMI_MONTH) { + //This is a special case that's hard to generalize + //If the date is 1, we round up to 16, otherwise + // we subtract 15 days and add 1 month + if (val.get(Calendar.DATE) == 1) { + val.add(Calendar.DATE, 15); + } else { + val.add(Calendar.DATE, -15); + val.add(Calendar.MONTH, 1); + } +// ----------------- Fix for LANG-440 ---------------------- START --------------- + } else if (field == Calendar.AM_PM) { + // This is a special case + // If the time is 0, we round up to 12, otherwise + // we subtract 12 hours and add 1 day + if (val.get(Calendar.HOUR_OF_DAY) == 0) { + val.add(Calendar.HOUR_OF_DAY, 12); + } else { + val.add(Calendar.HOUR_OF_DAY, -12); + val.add(Calendar.DATE, 1); + } +// ----------------- Fix for LANG-440 ---------------------- END --------------- + } else { + //We need at add one to this field since the + // last number causes us to round up + val.add(aField[0], 1); + } + } + return; + } + } + //We have various fields that are not easy roundings + int offset = 0; + boolean offsetSet = false; + //These are special types of fields that require different rounding rules + switch (field) { + case DateUtils.SEMI_MONTH: + if (aField[0] == Calendar.DATE) { + //If we're going to drop the DATE field's value, + // we want to do this our own way. + //We need to subtrace 1 since the date has a minimum of 1 + offset = val.get(Calendar.DATE) - 1; + //If we're above 15 days adjustment, that means we're in the + // bottom half of the month and should stay accordingly. + if (offset >= 15) { + offset -= 15; + } + //Record whether we're in the top or bottom half of that range + roundUp = offset > 7; + offsetSet = true; + } + break; + case Calendar.AM_PM: + if (aField[0] == Calendar.HOUR_OF_DAY) { + //If we're going to drop the HOUR field's value, + // we want to do this our own way. + offset = val.get(Calendar.HOUR_OF_DAY); + if (offset >= 12) { + offset -= 12; + } + roundUp = offset >= 6; + offsetSet = true; + } + break; + default: + break; + } + if (!offsetSet) { + final int min = val.getActualMinimum(aField[0]); + final int max = val.getActualMaximum(aField[0]); + //Calculate the offset from the minimum allowed value + offset = val.get(aField[0]) - min; + //Set roundUp if this is more than half way between the minimum and maximum + roundUp = offset > ((max - min) / 2); + } + //We need to remove this field + if (offset != 0) { + val.set(aField[0], val.get(aField[0]) - offset); + } + } + throw new IllegalArgumentException("The field " + field + " is not supported"); + + } + + //----------------------------------------------------------------------- + /** + *Constructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+// -----------------------------------------------------------------------
+/**
+ * Constructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus + * the date to work with, not null + * @param rangeStyle + * the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null, not null + * @throws IllegalArgumentException + * if the date isnull
+ * @throws IllegalArgumentException
+ * if the rangeStyle is invalid
+ */
+public static java.util.IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ */
+ public static Iterator iterator(final Object focus, final int rangeStyle) {
+ if (focus == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (focus instanceof Date) {
+ return iterator((Date) focus, rangeStyle);
+ } else if (focus instanceof Calendar) {
+ return iterator((Calendar) focus, rangeStyle);
+ } else {
+ throw new ClassCastException("Could not iterate based on " + focus);
+ }
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of milliseconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all milliseconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MILLISECONDS);
+ }
+
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MILLISECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MILLISECONDS);
+ }
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Gets a Date fragment for any unit.
+ *
+ * @param date the date to work with, not null
+ * @param fragment the Calendar field part of date to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the date
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Date date, final int fragment, final TimeUnit unit) {
+ if(date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar calendar = Calendar.getInstance();
+ calendar.setTime(date);
+ return getFragment(calendar, fragment, unit);
+ }
+
+ /**
+ * Gets a Calendar fragment for any unit.
+ *
+ * @param calendar the calendar to work with, not null
+ * @param fragment the Calendar field part of calendar to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the calendar
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Calendar calendar, final int fragment, final TimeUnit unit) {
+ if(calendar == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+
+ long result = 0;
+
+ final int offset = (unit == TimeUnit.DAYS) ? 0 : 1;
+
+ // Fragments bigger than a day require a breakdown to days
+ switch (fragment) {
+ case Calendar.YEAR:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_YEAR) - offset, TimeUnit.DAYS);
+ break;
+ case Calendar.MONTH:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_MONTH) - offset, TimeUnit.DAYS);
+ break;
+ default:
+ break;
+ }
+
+ switch (fragment) {
+ // Number of days already calculated for these cases
+ case Calendar.YEAR:
+ case Calendar.MONTH:
+
+ // The rest of the valid cases
+ case Calendar.DAY_OF_YEAR:
+ case Calendar.DATE:
+ result += unit.convert(calendar.get(Calendar.HOUR_OF_DAY), TimeUnit.HOURS);
+ //$FALL-THROUGH$
+ case Calendar.HOUR_OF_DAY:
+ result += unit.convert(calendar.get(Calendar.MINUTE), TimeUnit.MINUTES);
+ //$FALL-THROUGH$
+ case Calendar.MINUTE:
+ result += unit.convert(calendar.get(Calendar.SECOND), TimeUnit.SECONDS);
+ //$FALL-THROUGH$
+ case Calendar.SECOND:
+ result += unit.convert(calendar.get(Calendar.MILLISECOND), TimeUnit.MILLISECONDS);
+ break;
+ case Calendar.MILLISECOND: break;//never useful
+ default: throw new IllegalArgumentException("The fragment " + fragment + " is not supported");
+ }
+ return result;
+ }
+
+ /**
+ * Determines if two calendars are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedEquals(Date, Date, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Calendar cal1, final Calendar cal2, final int field) {
+ return truncatedCompareTo(cal1, cal2, field) == 0;
+ }
+
+ /**
+ * Determines if two dates are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Date, int)
+ * @see #truncatedEquals(Calendar, Calendar, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Date date1, final Date date2, final int field) {
+ return truncatedCompareTo(date1, date2, field) == 0;
+ }
+
+ /**
+ * Determines how two calendars compare up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return a negative integer, zero, or a positive integer as the first
+ * calendar is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Calendar cal1, final Calendar cal2, final int field) {
+ final Calendar truncatedCal1 = truncate(cal1, field);
+ final Calendar truncatedCal2 = truncate(cal2, field);
+ return truncatedCal1.compareTo(truncatedCal2);
+ }
+
+ /**
+ * Determines how two dates compare up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from Calendar
+ * @return a negative integer, zero, or a positive integer as the first
+ * date is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Date date1, final Date date2, final int field) {
+ final Date truncatedDate1 = truncate(date1, field);
+ final Date truncatedDate2 = truncate(date2, field);
+ return truncatedDate1.compareTo(truncatedDate2);
+ }
+
+
+ //-----------------------------------------------------------------------
+ /**
+ * Date iterator.
+ */ + static class DateIterator implements Iteratortrue if the iterator has yet to reach the end date
+ */
+ @Override
+ public boolean hasNext() {
+ return spot.before(endFinal);
+ }
+
+ /**
+ * Return the next calendar in the iteration
+ *
+ * @return Object calendar for the next date
+ */
+ @Override
+ public Calendar next() {
+ if (spot.equals(endFinal)) {
+ throw new NoSuchElementException();
+ }
+ spot.add(Calendar.DATE, 1);
+ return (Calendar) spot.clone();
+ }
+
+ /**
+ * Always throws UnsupportedOperationException.
+ *
+ * @throws UnsupportedOperationException
+ * @see java.util.Iterator#remove()
+ */
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+}
diff --git a/Java/commons-lang-DateUtils_1133/metadata.json b/Java/commons-lang-DateUtils_1133/metadata.json
new file mode 100644
index 000000000..a9e377230
--- /dev/null
+++ b/Java/commons-lang-DateUtils_1133/metadata.json
@@ -0,0 +1,21 @@
+{
+ "language": "java",
+ "id": "commons-lang-DateUtils_1133",
+ "buggyPath": ".",
+ "referencePath": null,
+ "buildCommand": "mvn package -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100 -DskipTests=true -DskipITs=true -Dtest=None -DfailIfNoTests=false",
+ "testCommand": "mvn test -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100",
+ "categories": [
+ "safety",
+ "npe"
+ ],
+ "npe": {
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 1165,
+ "npe_method": "iterator",
+ "deref_field": "focus",
+ "npe_class": "DateUtils",
+ "repo": "commons-lang",
+ "bug_id": "DateUtils_1133"
+ }
+}
diff --git a/Java/commons-lang-DateUtils_1133/npe.json b/Java/commons-lang-DateUtils_1133/npe.json
new file mode 100644
index 000000000..a8f105bee
--- /dev/null
+++ b/Java/commons-lang-DateUtils_1133/npe.json
@@ -0,0 +1,7 @@
+{
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 1165,
+ "npe_method": "iterator",
+ "deref_field": "focus",
+ "npe_class": "DateUtils"
+}
\ No newline at end of file
diff --git a/Java/commons-lang-DateUtils_1256/Dockerfile b/Java/commons-lang-DateUtils_1256/Dockerfile
new file mode 100644
index 000000000..7b7fbe349
--- /dev/null
+++ b/Java/commons-lang-DateUtils_1256/Dockerfile
@@ -0,0 +1,18 @@
+FROM ghcr.io/kupl/starlab-benchmarks/java-base:commons-lang
+
+ENV TZ=Asia/Seoul
+
+COPY ./metadata.json .
+COPY ./npe.json .
+COPY ./buggy.java /tmp/buggy.java
+RUN export BUGGY_PATH=$(cat metadata.json | jq -r ".npe.filepath") \
+ && export BUGGY_LINE=$(cat metadata.json | jq -r ".npe.line") \
+ && export BUGGY_MTHD=$(cat metadata.json | jq -r ".npe.npe_method") \
+ && mv /tmp/buggy.java $BUGGY_PATH \
+ && echo "[{\"filepath\": \"$BUGGY_PATH\", \"line\": $BUGGY_LINE, \"method_name\": \"$BUGGY_MTHD\"}]" | jq . > traces.json
+
+RUN git init . && git add -A
+
+RUN $(cat metadata.json | jq -r ".buildCommand")
+
+RUN $(cat metadata.json | jq -r ".testCommand"); if [ $? -eq 0 ]; then exit 1; fi
diff --git a/Java/commons-lang-DateUtils_1256/buggy.java b/Java/commons-lang-DateUtils_1256/buggy.java
new file mode 100644
index 000000000..f62320c84
--- /dev/null
+++ b/Java/commons-lang-DateUtils_1256/buggy.java
@@ -0,0 +1,1875 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3.time;
+
+import java.text.ParseException;
+import java.text.ParsePosition;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.Iterator;
+import java.util.Locale;
+import java.util.NoSuchElementException;
+import java.util.TimeZone;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * A suite of utilities surrounding the use of the + * {@link java.util.Calendar} and {@link java.util.Date} object.
+ * + *DateUtils contains a lot of common methods considering manipulations + * of Dates or Calendars. Some methods require some extra explanation. + * The truncate, ceiling and round methods could be considered the Math.floor(), + * Math.ceil() or Math.round versions for dates + * This way date-fields will be ignored in bottom-up order. + * As a complement to these methods we've introduced some fragment-methods. + * With these methods the Date-fields will be ignored in top-down order. + * Since a date without a year is not a valid date, you have to decide in what + * kind of date-field you want your result, for instance milliseconds or days. + *
+ *+ * Several methods are provided for adding to {@code Date} objects, of the form + * {@code addXXX(Date date, int amount)}. It is important to note these methods + * use a {@code Calendar} internally (with default timezone and locale) and may + * be affected by changes to daylight saving time (DST). + *
+ * + * @since 2.0 + */ +public class DateUtils { + + /** + * Number of milliseconds in a standard second. + * @since 2.1 + */ + public static final long MILLIS_PER_SECOND = 1000; + /** + * Number of milliseconds in a standard minute. + * @since 2.1 + */ + public static final long MILLIS_PER_MINUTE = 60 * MILLIS_PER_SECOND; + /** + * Number of milliseconds in a standard hour. + * @since 2.1 + */ + public static final long MILLIS_PER_HOUR = 60 * MILLIS_PER_MINUTE; + /** + * Number of milliseconds in a standard day. + * @since 2.1 + */ + public static final long MILLIS_PER_DAY = 24 * MILLIS_PER_HOUR; + + /** + * This is half a month, so this represents whether a date is in the top + * or bottom half of the month. + */ + public static final int SEMI_MONTH = 1001; + + private static final int[][] fields = { + {Calendar.MILLISECOND}, + {Calendar.SECOND}, + {Calendar.MINUTE}, + {Calendar.HOUR_OF_DAY, Calendar.HOUR}, + {Calendar.DATE, Calendar.DAY_OF_MONTH, Calendar.AM_PM + /* Calendar.DAY_OF_YEAR, Calendar.DAY_OF_WEEK, Calendar.DAY_OF_WEEK_IN_MONTH */ + }, + {Calendar.MONTH, DateUtils.SEMI_MONTH}, + {Calendar.YEAR}, + {Calendar.ERA}}; + + /** + * A week range, starting on Sunday. + */ + public static final int RANGE_WEEK_SUNDAY = 1; + /** + * A week range, starting on Monday. + */ + public static final int RANGE_WEEK_MONDAY = 2; + /** + * A week range, starting on the day focused. + */ + public static final int RANGE_WEEK_RELATIVE = 3; + /** + * A week range, centered around the day focused. + */ + public static final int RANGE_WEEK_CENTER = 4; + /** + * A month range, the week starting on Sunday. + */ + public static final int RANGE_MONTH_SUNDAY = 5; + /** + * A month range, the week starting on Monday. + */ + public static final int RANGE_MONTH_MONDAY = 6; + + /** + * Calendar modification types. + */ + private enum ModifyType { + /** + * Truncation. + */ + TRUNCATE, + + /** + * Rounding. + */ + ROUND, + + /** + * Ceiling. + */ + CEILING + } + + /** + *{@code DateUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code DateUtils.parseDate(str);}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public DateUtils() { + super(); + } + + //----------------------------------------------------------------------- + /** + *Checks if two date objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar cal1 = Calendar.getInstance();
+ cal1.setTime(date1);
+ final Calendar cal2 = Calendar.getInstance();
+ cal2.setTime(date2);
+ return isSameDay(cal1, cal2);
+ }
+
+ /**
+ * Checks if two calendar objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either calendar isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two date objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return date1.getTime() == date2.getTime();
+ }
+
+ /**
+ * Checks if two calendar objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.getTime().getTime() == cal2.getTime().getTime();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two calendar objects represent the same local time.
+ * + *This method compares the values of the fields of the two objects. + * In addition, both calendars must be the same of the same type.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameLocalTime(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.MILLISECOND) == cal2.get(Calendar.MILLISECOND) &&
+ cal1.get(Calendar.SECOND) == cal2.get(Calendar.SECOND) &&
+ cal1.get(Calendar.MINUTE) == cal2.get(Calendar.MINUTE) &&
+ cal1.get(Calendar.HOUR_OF_DAY) == cal2.get(Calendar.HOUR_OF_DAY) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.getClass() == cal2.getClass();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable (or there were none) + */ + public static Date parseDate(final String str, final String... parsePatterns) throws ParseException { + return parseDate(str, null, parsePatterns); + } + + //----------------------------------------------------------------------- + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDate(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable (or there were none)
+ * @since 3.2
+ */
+ public static Date parseDate(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, true);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @since 2.5 + */ + public static Date parseDateStrictly(final String str, final String... parsePatterns) throws ParseException { + return parseDateStrictly(str, null, parsePatterns); + } + + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale..
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDateStrictly(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable
+ * @since 3.2
+ */
+ public static Date parseDateStrictly(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, false);
+ }
+
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * + * @param str the date to parse, not null + * @param locale the locale to use when interpretting the pattern, can be null in which + * case the default system locale is used + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @param lenient Specify whether or not date/time parsing is to be lenient. + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @see java.util.Calendar#isLenient() + */ + private static Date parseDateWithLeniency( + final String str, final Locale locale, final String[] parsePatterns, final boolean lenient) throws ParseException { + if (str == null || parsePatterns == null) { + throw new IllegalArgumentException("Date and Patterns must not be null"); + } + + final TimeZone tz = TimeZone.getDefault(); + final Locale lcl = locale==null ?Locale.getDefault() : locale; + final ParsePosition pos = new ParsePosition(0); + final Calendar calendar = Calendar.getInstance(tz, lcl); + calendar.setLenient(lenient); + + for (final String parsePattern : parsePatterns) { + FastDateParser fdp = new FastDateParser(parsePattern, tz, lcl); + calendar.clear(); + try { + if (fdp.parse(str, pos, calendar) && pos.getIndex()==str.length()) { + return calendar.getTime(); + } + } + catch(IllegalArgumentException ignore) { + // leniency is preventing calendar from being set + } + pos.setIndex(0); + } + throw new ParseException("Unable to parse the date: " + str, -1); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of years to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addYears(final Date date, final int amount) { + return add(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of months to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMonths(final Date date, final int amount) { + return add(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of weeks to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addWeeks(final Date date, final int amount) { + return add(date, Calendar.WEEK_OF_YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of days to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addDays(final Date date, final int amount) { + return add(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of hours to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addHours(final Date date, final int amount) { + return add(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of minutes to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMinutes(final Date date, final int amount) { + return add(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of seconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addSeconds(final Date date, final int amount) { + return add(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of milliseconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMilliseconds(final Date date, final int amount) { + return add(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the calendar field to add to + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + private static Date add(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + final Calendar c = Calendar.getInstance(); + c.setTime(date); + c.add(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Sets the years field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setYears(final Date date, final int amount) { + return set(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the months field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMonths(final Date date, final int amount) { + return set(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the day of month field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setDays(final Date date, final int amount) { + return set(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the hours field to a date returning a new object. Hours range + * from 0-23. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setHours(final Date date, final int amount) { + return set(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the minute field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMinutes(final Date date, final int amount) { + return set(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the seconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setSeconds(final Date date, final int amount) { + return set(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the milliseconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMilliseconds(final Date date, final int amount) { + return set(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the specified field to a date returning a new object. + * This does not use a lenient calendar. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the {@code Calendar} field to set the amount to + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + private static Date set(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + // getInstance() returns a new object, so this method is thread safe. + final Calendar c = Calendar.getInstance(); + c.setLenient(false); + c.setTime(date); + c.set(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} into a {@code Calendar}. + * + * @param date the date to convert to a Calendar + * @return the created Calendar + * @throws NullPointerException if null is passed in + * @since 3.0 + */ + public static Calendar toCalendar(final Date date) { + final Calendar c = Calendar.getInstance(); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} of a given {@code TimeZone} into a {@code Calendar} + * @param date the date to convert to a Calendar + * @param tz the time zone of the @{code date} + * @return the created Calendar + * @throws NullPointerException if {@code date} or {@code tz} is null + */ + public static Calendar toCalendar(final Date date, final TimeZone tz) { + final Calendar c = Calendar.getInstance(tz); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar round(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar rounded = (Calendar) date.clone();
+ modify(rounded, field, ModifyType.ROUND);
+ return rounded;
+ }
+
+ /**
+ * Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date round(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return round((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return round((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not round " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.TRUNCATE);
+ return gval.getTime();
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar truncate(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar truncated = (Calendar) date.clone();
+ modify(truncated, field, ModifyType.TRUNCATE);
+ return truncated;
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return truncate((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return truncate((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not truncate " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.CEILING);
+ return gval.getTime();
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Calendar ceiling(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar ceiled = (Calendar) date.clone();
+ modify(ceiled, field, ModifyType.CEILING);
+ return ceiled;
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return ceiling((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return ceiling((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not find ceiling of for type: " + date.getClass());
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Internal calculation method.
+ * + * @param val the calendar, not null + * @param field the field constant + * @param modType type to truncate, round or ceiling + * @throws ArithmeticException if the year is over 280 million + */ + private static void modify(final Calendar val, final int field, final ModifyType modType) { + if (val.get(Calendar.YEAR) > 280000000) { + throw new ArithmeticException("Calendar value too large for accurate calculations"); + } + + if (field == Calendar.MILLISECOND) { + return; + } + + // ----------------- Fix for LANG-59 ---------------------- START --------------- + // see http://issues.apache.org/jira/browse/LANG-59 + // + // Manually truncate milliseconds, seconds and minutes, rather than using + // Calendar methods. + + final Date date = val.getTime(); + long time = date.getTime(); + boolean done = false; + + // truncate milliseconds + final int millisecs = val.get(Calendar.MILLISECOND); + if (ModifyType.TRUNCATE == modType || millisecs < 500) { + time = time - millisecs; + } + if (field == Calendar.SECOND) { + done = true; + } + + // truncate seconds + final int seconds = val.get(Calendar.SECOND); + if (!done && (ModifyType.TRUNCATE == modType || seconds < 30)) { + time = time - (seconds * 1000L); + } + if (field == Calendar.MINUTE) { + done = true; + } + + // truncate minutes + final int minutes = val.get(Calendar.MINUTE); + if (!done && (ModifyType.TRUNCATE == modType || minutes < 30)) { + time = time - (minutes * 60000L); + } + + // reset time + if (date.getTime() != time) { + date.setTime(time); + val.setTime(date); + } + // ----------------- Fix for LANG-59 ----------------------- END ---------------- + + boolean roundUp = false; + for (final int[] aField : fields) { + for (final int element : aField) { + if (element == field) { + //This is our field... we stop looping + if (modType == ModifyType.CEILING || modType == ModifyType.ROUND && roundUp) { + if (field == DateUtils.SEMI_MONTH) { + //This is a special case that's hard to generalize + //If the date is 1, we round up to 16, otherwise + // we subtract 15 days and add 1 month + if (val.get(Calendar.DATE) == 1) { + val.add(Calendar.DATE, 15); + } else { + val.add(Calendar.DATE, -15); + val.add(Calendar.MONTH, 1); + } +// ----------------- Fix for LANG-440 ---------------------- START --------------- + } else if (field == Calendar.AM_PM) { + // This is a special case + // If the time is 0, we round up to 12, otherwise + // we subtract 12 hours and add 1 day + if (val.get(Calendar.HOUR_OF_DAY) == 0) { + val.add(Calendar.HOUR_OF_DAY, 12); + } else { + val.add(Calendar.HOUR_OF_DAY, -12); + val.add(Calendar.DATE, 1); + } +// ----------------- Fix for LANG-440 ---------------------- END --------------- + } else { + //We need at add one to this field since the + // last number causes us to round up + val.add(aField[0], 1); + } + } + return; + } + } + //We have various fields that are not easy roundings + int offset = 0; + boolean offsetSet = false; + //These are special types of fields that require different rounding rules + switch (field) { + case DateUtils.SEMI_MONTH: + if (aField[0] == Calendar.DATE) { + //If we're going to drop the DATE field's value, + // we want to do this our own way. + //We need to subtrace 1 since the date has a minimum of 1 + offset = val.get(Calendar.DATE) - 1; + //If we're above 15 days adjustment, that means we're in the + // bottom half of the month and should stay accordingly. + if (offset >= 15) { + offset -= 15; + } + //Record whether we're in the top or bottom half of that range + roundUp = offset > 7; + offsetSet = true; + } + break; + case Calendar.AM_PM: + if (aField[0] == Calendar.HOUR_OF_DAY) { + //If we're going to drop the HOUR field's value, + // we want to do this our own way. + offset = val.get(Calendar.HOUR_OF_DAY); + if (offset >= 12) { + offset -= 12; + } + roundUp = offset >= 6; + offsetSet = true; + } + break; + default: + break; + } + if (!offsetSet) { + final int min = val.getActualMinimum(aField[0]); + final int max = val.getActualMaximum(aField[0]); + //Calculate the offset from the minimum allowed value + offset = val.get(aField[0]) - min; + //Set roundUp if this is more than half way between the minimum and maximum + roundUp = offset > ((max - min) / 2); + } + //We need to remove this field + if (offset != 0) { + val.set(aField[0], val.get(aField[0]) - offset); + } + } + throw new IllegalArgumentException("The field " + field + " is not supported"); + + } + + //----------------------------------------------------------------------- + /** + *Constructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ */
+/**
+ * Constructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
null
+ * @throws ClassCastException
+ * if the object type is not a {@code Date} or {@code Calendar}
+ */
+public static java.util.Iterator iterator(final java.lang.Object focus, final int rangeStyle) {
+ {
+ if (/* NPEX_NULL_EXP */
+ focus instanceof java.util.Date) {
+ return org.apache.commons.lang3.time.DateUtils.iterator(((java.util.Date) (focus)), rangeStyle);
+ } else if (focus instanceof java.util.Calendar) {
+ return org.apache.commons.lang3.time.DateUtils.iterator(((java.util.Calendar) (focus)), rangeStyle);
+ } else {
+ throw new java.lang.ClassCastException("Could not iterate based on " + focus);
+ }
+ }
+}
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of milliseconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all milliseconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MILLISECONDS);
+ }
+
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MILLISECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MILLISECONDS);
+ }
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Gets a Date fragment for any unit.
+ *
+ * @param date the date to work with, not null
+ * @param fragment the Calendar field part of date to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the date
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Date date, final int fragment, final TimeUnit unit) {
+ if(date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar calendar = Calendar.getInstance();
+ calendar.setTime(date);
+ return getFragment(calendar, fragment, unit);
+ }
+
+ /**
+ * Gets a Calendar fragment for any unit.
+ *
+ * @param calendar the calendar to work with, not null
+ * @param fragment the Calendar field part of calendar to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the calendar
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Calendar calendar, final int fragment, final TimeUnit unit) {
+ if(calendar == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+
+ long result = 0;
+
+ final int offset = (unit == TimeUnit.DAYS) ? 0 : 1;
+
+ // Fragments bigger than a day require a breakdown to days
+ switch (fragment) {
+ case Calendar.YEAR:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_YEAR) - offset, TimeUnit.DAYS);
+ break;
+ case Calendar.MONTH:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_MONTH) - offset, TimeUnit.DAYS);
+ break;
+ default:
+ break;
+ }
+
+ switch (fragment) {
+ // Number of days already calculated for these cases
+ case Calendar.YEAR:
+ case Calendar.MONTH:
+
+ // The rest of the valid cases
+ case Calendar.DAY_OF_YEAR:
+ case Calendar.DATE:
+ result += unit.convert(calendar.get(Calendar.HOUR_OF_DAY), TimeUnit.HOURS);
+ //$FALL-THROUGH$
+ case Calendar.HOUR_OF_DAY:
+ result += unit.convert(calendar.get(Calendar.MINUTE), TimeUnit.MINUTES);
+ //$FALL-THROUGH$
+ case Calendar.MINUTE:
+ result += unit.convert(calendar.get(Calendar.SECOND), TimeUnit.SECONDS);
+ //$FALL-THROUGH$
+ case Calendar.SECOND:
+ result += unit.convert(calendar.get(Calendar.MILLISECOND), TimeUnit.MILLISECONDS);
+ break;
+ case Calendar.MILLISECOND: break;//never useful
+ default: throw new IllegalArgumentException("The fragment " + fragment + " is not supported");
+ }
+ return result;
+ }
+
+ /**
+ * Determines if two calendars are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedEquals(Date, Date, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Calendar cal1, final Calendar cal2, final int field) {
+ return truncatedCompareTo(cal1, cal2, field) == 0;
+ }
+
+ /**
+ * Determines if two dates are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Date, int)
+ * @see #truncatedEquals(Calendar, Calendar, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Date date1, final Date date2, final int field) {
+ return truncatedCompareTo(date1, date2, field) == 0;
+ }
+
+ /**
+ * Determines how two calendars compare up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return a negative integer, zero, or a positive integer as the first
+ * calendar is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Calendar cal1, final Calendar cal2, final int field) {
+ final Calendar truncatedCal1 = truncate(cal1, field);
+ final Calendar truncatedCal2 = truncate(cal2, field);
+ return truncatedCal1.compareTo(truncatedCal2);
+ }
+
+ /**
+ * Determines how two dates compare up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from Calendar
+ * @return a negative integer, zero, or a positive integer as the first
+ * date is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Date date1, final Date date2, final int field) {
+ final Date truncatedDate1 = truncate(date1, field);
+ final Date truncatedDate2 = truncate(date2, field);
+ return truncatedDate1.compareTo(truncatedDate2);
+ }
+
+
+ //-----------------------------------------------------------------------
+ /**
+ * Date iterator.
+ */ + static class DateIterator implements Iteratortrue if the iterator has yet to reach the end date
+ */
+ @Override
+ public boolean hasNext() {
+ return spot.before(endFinal);
+ }
+
+ /**
+ * Return the next calendar in the iteration
+ *
+ * @return Object calendar for the next date
+ */
+ @Override
+ public Calendar next() {
+ if (spot.equals(endFinal)) {
+ throw new NoSuchElementException();
+ }
+ spot.add(Calendar.DATE, 1);
+ return (Calendar) spot.clone();
+ }
+
+ /**
+ * Always throws UnsupportedOperationException.
+ *
+ * @throws UnsupportedOperationException
+ * @see java.util.Iterator#remove()
+ */
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+}
diff --git a/Java/commons-lang-DateUtils_1256/metadata.json b/Java/commons-lang-DateUtils_1256/metadata.json
new file mode 100644
index 000000000..fe8793806
--- /dev/null
+++ b/Java/commons-lang-DateUtils_1256/metadata.json
@@ -0,0 +1,21 @@
+{
+ "language": "java",
+ "id": "commons-lang-DateUtils_1256",
+ "buggyPath": ".",
+ "referencePath": null,
+ "buildCommand": "mvn package -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100 -DskipTests=true -DskipITs=true -Dtest=None -DfailIfNoTests=false",
+ "testCommand": "mvn test -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100",
+ "categories": [
+ "safety",
+ "npe"
+ ],
+ "npe": {
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 1278,
+ "npe_method": "iterator",
+ "deref_field": "focus",
+ "npe_class": "DateUtils",
+ "repo": "commons-lang",
+ "bug_id": "DateUtils_1256"
+ }
+}
diff --git a/Java/commons-lang-DateUtils_1256/npe.json b/Java/commons-lang-DateUtils_1256/npe.json
new file mode 100644
index 000000000..c7634dbea
--- /dev/null
+++ b/Java/commons-lang-DateUtils_1256/npe.json
@@ -0,0 +1,7 @@
+{
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 1278,
+ "npe_method": "iterator",
+ "deref_field": "focus",
+ "npe_class": "DateUtils"
+}
\ No newline at end of file
diff --git a/Java/commons-lang-DateUtils_1658/Dockerfile b/Java/commons-lang-DateUtils_1658/Dockerfile
new file mode 100644
index 000000000..7b7fbe349
--- /dev/null
+++ b/Java/commons-lang-DateUtils_1658/Dockerfile
@@ -0,0 +1,18 @@
+FROM ghcr.io/kupl/starlab-benchmarks/java-base:commons-lang
+
+ENV TZ=Asia/Seoul
+
+COPY ./metadata.json .
+COPY ./npe.json .
+COPY ./buggy.java /tmp/buggy.java
+RUN export BUGGY_PATH=$(cat metadata.json | jq -r ".npe.filepath") \
+ && export BUGGY_LINE=$(cat metadata.json | jq -r ".npe.line") \
+ && export BUGGY_MTHD=$(cat metadata.json | jq -r ".npe.npe_method") \
+ && mv /tmp/buggy.java $BUGGY_PATH \
+ && echo "[{\"filepath\": \"$BUGGY_PATH\", \"line\": $BUGGY_LINE, \"method_name\": \"$BUGGY_MTHD\"}]" | jq . > traces.json
+
+RUN git init . && git add -A
+
+RUN $(cat metadata.json | jq -r ".buildCommand")
+
+RUN $(cat metadata.json | jq -r ".testCommand"); if [ $? -eq 0 ]; then exit 1; fi
diff --git a/Java/commons-lang-DateUtils_1658/buggy.java b/Java/commons-lang-DateUtils_1658/buggy.java
new file mode 100644
index 000000000..859188699
--- /dev/null
+++ b/Java/commons-lang-DateUtils_1658/buggy.java
@@ -0,0 +1,1870 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3.time;
+
+import java.text.ParseException;
+import java.text.ParsePosition;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.Iterator;
+import java.util.Locale;
+import java.util.NoSuchElementException;
+import java.util.TimeZone;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * A suite of utilities surrounding the use of the + * {@link java.util.Calendar} and {@link java.util.Date} object.
+ * + *DateUtils contains a lot of common methods considering manipulations + * of Dates or Calendars. Some methods require some extra explanation. + * The truncate, ceiling and round methods could be considered the Math.floor(), + * Math.ceil() or Math.round versions for dates + * This way date-fields will be ignored in bottom-up order. + * As a complement to these methods we've introduced some fragment-methods. + * With these methods the Date-fields will be ignored in top-down order. + * Since a date without a year is not a valid date, you have to decide in what + * kind of date-field you want your result, for instance milliseconds or days. + *
+ *+ * Several methods are provided for adding to {@code Date} objects, of the form + * {@code addXXX(Date date, int amount)}. It is important to note these methods + * use a {@code Calendar} internally (with default timezone and locale) and may + * be affected by changes to daylight saving time (DST). + *
+ * + * @since 2.0 + */ +public class DateUtils { + + /** + * Number of milliseconds in a standard second. + * @since 2.1 + */ + public static final long MILLIS_PER_SECOND = 1000; + /** + * Number of milliseconds in a standard minute. + * @since 2.1 + */ + public static final long MILLIS_PER_MINUTE = 60 * MILLIS_PER_SECOND; + /** + * Number of milliseconds in a standard hour. + * @since 2.1 + */ + public static final long MILLIS_PER_HOUR = 60 * MILLIS_PER_MINUTE; + /** + * Number of milliseconds in a standard day. + * @since 2.1 + */ + public static final long MILLIS_PER_DAY = 24 * MILLIS_PER_HOUR; + + /** + * This is half a month, so this represents whether a date is in the top + * or bottom half of the month. + */ + public static final int SEMI_MONTH = 1001; + + private static final int[][] fields = { + {Calendar.MILLISECOND}, + {Calendar.SECOND}, + {Calendar.MINUTE}, + {Calendar.HOUR_OF_DAY, Calendar.HOUR}, + {Calendar.DATE, Calendar.DAY_OF_MONTH, Calendar.AM_PM + /* Calendar.DAY_OF_YEAR, Calendar.DAY_OF_WEEK, Calendar.DAY_OF_WEEK_IN_MONTH */ + }, + {Calendar.MONTH, DateUtils.SEMI_MONTH}, + {Calendar.YEAR}, + {Calendar.ERA}}; + + /** + * A week range, starting on Sunday. + */ + public static final int RANGE_WEEK_SUNDAY = 1; + /** + * A week range, starting on Monday. + */ + public static final int RANGE_WEEK_MONDAY = 2; + /** + * A week range, starting on the day focused. + */ + public static final int RANGE_WEEK_RELATIVE = 3; + /** + * A week range, centered around the day focused. + */ + public static final int RANGE_WEEK_CENTER = 4; + /** + * A month range, the week starting on Sunday. + */ + public static final int RANGE_MONTH_SUNDAY = 5; + /** + * A month range, the week starting on Monday. + */ + public static final int RANGE_MONTH_MONDAY = 6; + + /** + * Calendar modification types. + */ + private enum ModifyType { + /** + * Truncation. + */ + TRUNCATE, + + /** + * Rounding. + */ + ROUND, + + /** + * Ceiling. + */ + CEILING + } + + /** + *{@code DateUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code DateUtils.parseDate(str);}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public DateUtils() { + super(); + } + + //----------------------------------------------------------------------- + /** + *Checks if two date objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar cal1 = Calendar.getInstance();
+ cal1.setTime(date1);
+ final Calendar cal2 = Calendar.getInstance();
+ cal2.setTime(date2);
+ return isSameDay(cal1, cal2);
+ }
+
+ /**
+ * Checks if two calendar objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either calendar isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two date objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return date1.getTime() == date2.getTime();
+ }
+
+ /**
+ * Checks if two calendar objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.getTime().getTime() == cal2.getTime().getTime();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two calendar objects represent the same local time.
+ * + *This method compares the values of the fields of the two objects. + * In addition, both calendars must be the same of the same type.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameLocalTime(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.MILLISECOND) == cal2.get(Calendar.MILLISECOND) &&
+ cal1.get(Calendar.SECOND) == cal2.get(Calendar.SECOND) &&
+ cal1.get(Calendar.MINUTE) == cal2.get(Calendar.MINUTE) &&
+ cal1.get(Calendar.HOUR_OF_DAY) == cal2.get(Calendar.HOUR_OF_DAY) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.getClass() == cal2.getClass();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable (or there were none) + */ + public static Date parseDate(final String str, final String... parsePatterns) throws ParseException { + return parseDate(str, null, parsePatterns); + } + + //----------------------------------------------------------------------- + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDate(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable (or there were none)
+ * @since 3.2
+ */
+ public static Date parseDate(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, true);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @since 2.5 + */ + public static Date parseDateStrictly(final String str, final String... parsePatterns) throws ParseException { + return parseDateStrictly(str, null, parsePatterns); + } + + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale..
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDateStrictly(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable
+ * @since 3.2
+ */
+ public static Date parseDateStrictly(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, false);
+ }
+
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * + * @param str the date to parse, not null + * @param locale the locale to use when interpretting the pattern, can be null in which + * case the default system locale is used + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @param lenient Specify whether or not date/time parsing is to be lenient. + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @see java.util.Calendar#isLenient() + */ + private static Date parseDateWithLeniency( + final String str, final Locale locale, final String[] parsePatterns, final boolean lenient) throws ParseException { + if (str == null || parsePatterns == null) { + throw new IllegalArgumentException("Date and Patterns must not be null"); + } + + final TimeZone tz = TimeZone.getDefault(); + final Locale lcl = locale==null ?Locale.getDefault() : locale; + final ParsePosition pos = new ParsePosition(0); + final Calendar calendar = Calendar.getInstance(tz, lcl); + calendar.setLenient(lenient); + + for (final String parsePattern : parsePatterns) { + FastDateParser fdp = new FastDateParser(parsePattern, tz, lcl); + calendar.clear(); + try { + if (fdp.parse(str, pos, calendar) && pos.getIndex()==str.length()) { + return calendar.getTime(); + } + } + catch(IllegalArgumentException ignore) { + // leniency is preventing calendar from being set + } + pos.setIndex(0); + } + throw new ParseException("Unable to parse the date: " + str, -1); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of years to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addYears(final Date date, final int amount) { + return add(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of months to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMonths(final Date date, final int amount) { + return add(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of weeks to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addWeeks(final Date date, final int amount) { + return add(date, Calendar.WEEK_OF_YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of days to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addDays(final Date date, final int amount) { + return add(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of hours to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addHours(final Date date, final int amount) { + return add(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of minutes to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMinutes(final Date date, final int amount) { + return add(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of seconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addSeconds(final Date date, final int amount) { + return add(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of milliseconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMilliseconds(final Date date, final int amount) { + return add(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the calendar field to add to + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + private static Date add(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + final Calendar c = Calendar.getInstance(); + c.setTime(date); + c.add(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Sets the years field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setYears(final Date date, final int amount) { + return set(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the months field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMonths(final Date date, final int amount) { + return set(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the day of month field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setDays(final Date date, final int amount) { + return set(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the hours field to a date returning a new object. Hours range + * from 0-23. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setHours(final Date date, final int amount) { + return set(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the minute field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMinutes(final Date date, final int amount) { + return set(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the seconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setSeconds(final Date date, final int amount) { + return set(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the milliseconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMilliseconds(final Date date, final int amount) { + return set(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the specified field to a date returning a new object. + * This does not use a lenient calendar. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the {@code Calendar} field to set the amount to + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + private static Date set(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + // getInstance() returns a new object, so this method is thread safe. + final Calendar c = Calendar.getInstance(); + c.setLenient(false); + c.setTime(date); + c.set(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} into a {@code Calendar}. + * + * @param date the date to convert to a Calendar + * @return the created Calendar + * @throws NullPointerException if null is passed in + * @since 3.0 + */ + public static Calendar toCalendar(final Date date) { + final Calendar c = Calendar.getInstance(); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} of a given {@code TimeZone} into a {@code Calendar} + * @param date the date to convert to a Calendar + * @param tz the time zone of the @{code date} + * @return the created Calendar + * @throws NullPointerException if {@code date} or {@code tz} is null + */ + public static Calendar toCalendar(final Date date, final TimeZone tz) { + final Calendar c = Calendar.getInstance(tz); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar round(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar rounded = (Calendar) date.clone();
+ modify(rounded, field, ModifyType.ROUND);
+ return rounded;
+ }
+
+ /**
+ * Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date round(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return round((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return round((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not round " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.TRUNCATE);
+ return gval.getTime();
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar truncate(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar truncated = (Calendar) date.clone();
+ modify(truncated, field, ModifyType.TRUNCATE);
+ return truncated;
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return truncate((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return truncate((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not truncate " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.CEILING);
+ return gval.getTime();
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Calendar ceiling(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar ceiled = (Calendar) date.clone();
+ modify(ceiled, field, ModifyType.CEILING);
+ return ceiled;
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return ceiling((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return ceiling((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not find ceiling of for type: " + date.getClass());
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Internal calculation method.
+ * + * @param val the calendar, not null + * @param field the field constant + * @param modType type to truncate, round or ceiling + * @throws ArithmeticException if the year is over 280 million + */ + private static void modify(final Calendar val, final int field, final ModifyType modType) { + if (val.get(Calendar.YEAR) > 280000000) { + throw new ArithmeticException("Calendar value too large for accurate calculations"); + } + + if (field == Calendar.MILLISECOND) { + return; + } + + // ----------------- Fix for LANG-59 ---------------------- START --------------- + // see http://issues.apache.org/jira/browse/LANG-59 + // + // Manually truncate milliseconds, seconds and minutes, rather than using + // Calendar methods. + + final Date date = val.getTime(); + long time = date.getTime(); + boolean done = false; + + // truncate milliseconds + final int millisecs = val.get(Calendar.MILLISECOND); + if (ModifyType.TRUNCATE == modType || millisecs < 500) { + time = time - millisecs; + } + if (field == Calendar.SECOND) { + done = true; + } + + // truncate seconds + final int seconds = val.get(Calendar.SECOND); + if (!done && (ModifyType.TRUNCATE == modType || seconds < 30)) { + time = time - (seconds * 1000L); + } + if (field == Calendar.MINUTE) { + done = true; + } + + // truncate minutes + final int minutes = val.get(Calendar.MINUTE); + if (!done && (ModifyType.TRUNCATE == modType || minutes < 30)) { + time = time - (minutes * 60000L); + } + + // reset time + if (date.getTime() != time) { + date.setTime(time); + val.setTime(date); + } + // ----------------- Fix for LANG-59 ----------------------- END ---------------- + + boolean roundUp = false; + for (final int[] aField : fields) { + for (final int element : aField) { + if (element == field) { + //This is our field... we stop looping + if (modType == ModifyType.CEILING || modType == ModifyType.ROUND && roundUp) { + if (field == DateUtils.SEMI_MONTH) { + //This is a special case that's hard to generalize + //If the date is 1, we round up to 16, otherwise + // we subtract 15 days and add 1 month + if (val.get(Calendar.DATE) == 1) { + val.add(Calendar.DATE, 15); + } else { + val.add(Calendar.DATE, -15); + val.add(Calendar.MONTH, 1); + } +// ----------------- Fix for LANG-440 ---------------------- START --------------- + } else if (field == Calendar.AM_PM) { + // This is a special case + // If the time is 0, we round up to 12, otherwise + // we subtract 12 hours and add 1 day + if (val.get(Calendar.HOUR_OF_DAY) == 0) { + val.add(Calendar.HOUR_OF_DAY, 12); + } else { + val.add(Calendar.HOUR_OF_DAY, -12); + val.add(Calendar.DATE, 1); + } +// ----------------- Fix for LANG-440 ---------------------- END --------------- + } else { + //We need at add one to this field since the + // last number causes us to round up + val.add(aField[0], 1); + } + } + return; + } + } + //We have various fields that are not easy roundings + int offset = 0; + boolean offsetSet = false; + //These are special types of fields that require different rounding rules + switch (field) { + case DateUtils.SEMI_MONTH: + if (aField[0] == Calendar.DATE) { + //If we're going to drop the DATE field's value, + // we want to do this our own way. + //We need to subtrace 1 since the date has a minimum of 1 + offset = val.get(Calendar.DATE) - 1; + //If we're above 15 days adjustment, that means we're in the + // bottom half of the month and should stay accordingly. + if (offset >= 15) { + offset -= 15; + } + //Record whether we're in the top or bottom half of that range + roundUp = offset > 7; + offsetSet = true; + } + break; + case Calendar.AM_PM: + if (aField[0] == Calendar.HOUR_OF_DAY) { + //If we're going to drop the HOUR field's value, + // we want to do this our own way. + offset = val.get(Calendar.HOUR_OF_DAY); + if (offset >= 12) { + offset -= 12; + } + roundUp = offset >= 6; + offsetSet = true; + } + break; + default: + break; + } + if (!offsetSet) { + final int min = val.getActualMinimum(aField[0]); + final int max = val.getActualMaximum(aField[0]); + //Calculate the offset from the minimum allowed value + offset = val.get(aField[0]) - min; + //Set roundUp if this is more than half way between the minimum and maximum + roundUp = offset > ((max - min) / 2); + } + //We need to remove this field + if (offset != 0) { + val.set(aField[0], val.get(aField[0]) - offset); + } + } + throw new IllegalArgumentException("The field " + field + " is not supported"); + + } + + //----------------------------------------------------------------------- + /** + *Constructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ */
+ public static Iterator iterator(final Object focus, final int rangeStyle) {
+ if (focus == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (focus instanceof Date) {
+ return iterator((Date) focus, rangeStyle);
+ } else if (focus instanceof Calendar) {
+ return iterator((Calendar) focus, rangeStyle);
+ } else {
+ throw new ClassCastException("Could not iterate based on " + focus);
+ }
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of milliseconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all milliseconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MILLISECONDS);
+ }
+
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MILLISECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MILLISECONDS);
+ }
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Gets a Date fragment for any unit.
+ *
+ * @param date the date to work with, not null
+ * @param fragment the Calendar field part of date to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the date
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+/**
+ * Gets a Date fragment for any unit.
+ *
+ * @param date
+ * the date to work with, not null
+ * @param fragment
+ * the Calendar field part of date to calculate
+ * @param unit
+ * the time unit
+ * @return number of units within the fragment of the date
+ * @throws IllegalArgumentException
+ * if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+private static long getFragment(final java.util.Date date, final int fragment, final java.util.concurrent.TimeUnit unit) {
+ {
+ final java.util.Calendar calendar = java.util.Calendar.getInstance();
+ calendar.setTime(/* NPEX_NULL_EXP */
+ date);
+ return org.apache.commons.lang3.time.DateUtils.getFragment(calendar, fragment, unit);
+ }
+}
+
+ /**
+ * Gets a Calendar fragment for any unit.
+ *
+ * @param calendar the calendar to work with, not null
+ * @param fragment the Calendar field part of calendar to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the calendar
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Calendar calendar, final int fragment, final TimeUnit unit) {
+ if(calendar == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+
+ long result = 0;
+
+ final int offset = (unit == TimeUnit.DAYS) ? 0 : 1;
+
+ // Fragments bigger than a day require a breakdown to days
+ switch (fragment) {
+ case Calendar.YEAR:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_YEAR) - offset, TimeUnit.DAYS);
+ break;
+ case Calendar.MONTH:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_MONTH) - offset, TimeUnit.DAYS);
+ break;
+ default:
+ break;
+ }
+
+ switch (fragment) {
+ // Number of days already calculated for these cases
+ case Calendar.YEAR:
+ case Calendar.MONTH:
+
+ // The rest of the valid cases
+ case Calendar.DAY_OF_YEAR:
+ case Calendar.DATE:
+ result += unit.convert(calendar.get(Calendar.HOUR_OF_DAY), TimeUnit.HOURS);
+ //$FALL-THROUGH$
+ case Calendar.HOUR_OF_DAY:
+ result += unit.convert(calendar.get(Calendar.MINUTE), TimeUnit.MINUTES);
+ //$FALL-THROUGH$
+ case Calendar.MINUTE:
+ result += unit.convert(calendar.get(Calendar.SECOND), TimeUnit.SECONDS);
+ //$FALL-THROUGH$
+ case Calendar.SECOND:
+ result += unit.convert(calendar.get(Calendar.MILLISECOND), TimeUnit.MILLISECONDS);
+ break;
+ case Calendar.MILLISECOND: break;//never useful
+ default: throw new IllegalArgumentException("The fragment " + fragment + " is not supported");
+ }
+ return result;
+ }
+
+ /**
+ * Determines if two calendars are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedEquals(Date, Date, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Calendar cal1, final Calendar cal2, final int field) {
+ return truncatedCompareTo(cal1, cal2, field) == 0;
+ }
+
+ /**
+ * Determines if two dates are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Date, int)
+ * @see #truncatedEquals(Calendar, Calendar, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Date date1, final Date date2, final int field) {
+ return truncatedCompareTo(date1, date2, field) == 0;
+ }
+
+ /**
+ * Determines how two calendars compare up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return a negative integer, zero, or a positive integer as the first
+ * calendar is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Calendar cal1, final Calendar cal2, final int field) {
+ final Calendar truncatedCal1 = truncate(cal1, field);
+ final Calendar truncatedCal2 = truncate(cal2, field);
+ return truncatedCal1.compareTo(truncatedCal2);
+ }
+
+ /**
+ * Determines how two dates compare up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from Calendar
+ * @return a negative integer, zero, or a positive integer as the first
+ * date is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Date date1, final Date date2, final int field) {
+ final Date truncatedDate1 = truncate(date1, field);
+ final Date truncatedDate2 = truncate(date2, field);
+ return truncatedDate1.compareTo(truncatedDate2);
+ }
+
+
+ //-----------------------------------------------------------------------
+ /**
+ * Date iterator.
+ */ + static class DateIterator implements Iteratortrue if the iterator has yet to reach the end date
+ */
+ @Override
+ public boolean hasNext() {
+ return spot.before(endFinal);
+ }
+
+ /**
+ * Return the next calendar in the iteration
+ *
+ * @return Object calendar for the next date
+ */
+ @Override
+ public Calendar next() {
+ if (spot.equals(endFinal)) {
+ throw new NoSuchElementException();
+ }
+ spot.add(Calendar.DATE, 1);
+ return (Calendar) spot.clone();
+ }
+
+ /**
+ * Always throws UnsupportedOperationException.
+ *
+ * @throws UnsupportedOperationException
+ * @see java.util.Iterator#remove()
+ */
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+}
diff --git a/Java/commons-lang-DateUtils_1658/metadata.json b/Java/commons-lang-DateUtils_1658/metadata.json
new file mode 100644
index 000000000..d504b0229
--- /dev/null
+++ b/Java/commons-lang-DateUtils_1658/metadata.json
@@ -0,0 +1,21 @@
+{
+ "language": "java",
+ "id": "commons-lang-DateUtils_1658",
+ "buggyPath": ".",
+ "referencePath": null,
+ "buildCommand": "mvn package -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100 -DskipTests=true -DskipITs=true -Dtest=None -DfailIfNoTests=false",
+ "testCommand": "mvn test -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100",
+ "categories": [
+ "safety",
+ "npe"
+ ],
+ "npe": {
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 1676,
+ "npe_method": "getFragment",
+ "deref_field": "date",
+ "npe_class": "DateUtils",
+ "repo": "commons-lang",
+ "bug_id": "DateUtils_1658"
+ }
+}
diff --git a/Java/commons-lang-DateUtils_1658/npe.json b/Java/commons-lang-DateUtils_1658/npe.json
new file mode 100644
index 000000000..15c2f817f
--- /dev/null
+++ b/Java/commons-lang-DateUtils_1658/npe.json
@@ -0,0 +1,7 @@
+{
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 1676,
+ "npe_method": "getFragment",
+ "deref_field": "date",
+ "npe_class": "DateUtils"
+}
\ No newline at end of file
diff --git a/Java/commons-lang-DateUtils_1678/Dockerfile b/Java/commons-lang-DateUtils_1678/Dockerfile
new file mode 100644
index 000000000..7b7fbe349
--- /dev/null
+++ b/Java/commons-lang-DateUtils_1678/Dockerfile
@@ -0,0 +1,18 @@
+FROM ghcr.io/kupl/starlab-benchmarks/java-base:commons-lang
+
+ENV TZ=Asia/Seoul
+
+COPY ./metadata.json .
+COPY ./npe.json .
+COPY ./buggy.java /tmp/buggy.java
+RUN export BUGGY_PATH=$(cat metadata.json | jq -r ".npe.filepath") \
+ && export BUGGY_LINE=$(cat metadata.json | jq -r ".npe.line") \
+ && export BUGGY_MTHD=$(cat metadata.json | jq -r ".npe.npe_method") \
+ && mv /tmp/buggy.java $BUGGY_PATH \
+ && echo "[{\"filepath\": \"$BUGGY_PATH\", \"line\": $BUGGY_LINE, \"method_name\": \"$BUGGY_MTHD\"}]" | jq . > traces.json
+
+RUN git init . && git add -A
+
+RUN $(cat metadata.json | jq -r ".buildCommand")
+
+RUN $(cat metadata.json | jq -r ".testCommand"); if [ $? -eq 0 ]; then exit 1; fi
diff --git a/Java/commons-lang-DateUtils_1678/buggy.java b/Java/commons-lang-DateUtils_1678/buggy.java
new file mode 100644
index 000000000..5d6c801d0
--- /dev/null
+++ b/Java/commons-lang-DateUtils_1678/buggy.java
@@ -0,0 +1,1868 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3.time;
+
+import java.text.ParseException;
+import java.text.ParsePosition;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.Iterator;
+import java.util.Locale;
+import java.util.NoSuchElementException;
+import java.util.TimeZone;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * A suite of utilities surrounding the use of the + * {@link java.util.Calendar} and {@link java.util.Date} object.
+ * + *DateUtils contains a lot of common methods considering manipulations + * of Dates or Calendars. Some methods require some extra explanation. + * The truncate, ceiling and round methods could be considered the Math.floor(), + * Math.ceil() or Math.round versions for dates + * This way date-fields will be ignored in bottom-up order. + * As a complement to these methods we've introduced some fragment-methods. + * With these methods the Date-fields will be ignored in top-down order. + * Since a date without a year is not a valid date, you have to decide in what + * kind of date-field you want your result, for instance milliseconds or days. + *
+ *+ * Several methods are provided for adding to {@code Date} objects, of the form + * {@code addXXX(Date date, int amount)}. It is important to note these methods + * use a {@code Calendar} internally (with default timezone and locale) and may + * be affected by changes to daylight saving time (DST). + *
+ * + * @since 2.0 + */ +public class DateUtils { + + /** + * Number of milliseconds in a standard second. + * @since 2.1 + */ + public static final long MILLIS_PER_SECOND = 1000; + /** + * Number of milliseconds in a standard minute. + * @since 2.1 + */ + public static final long MILLIS_PER_MINUTE = 60 * MILLIS_PER_SECOND; + /** + * Number of milliseconds in a standard hour. + * @since 2.1 + */ + public static final long MILLIS_PER_HOUR = 60 * MILLIS_PER_MINUTE; + /** + * Number of milliseconds in a standard day. + * @since 2.1 + */ + public static final long MILLIS_PER_DAY = 24 * MILLIS_PER_HOUR; + + /** + * This is half a month, so this represents whether a date is in the top + * or bottom half of the month. + */ + public static final int SEMI_MONTH = 1001; + + private static final int[][] fields = { + {Calendar.MILLISECOND}, + {Calendar.SECOND}, + {Calendar.MINUTE}, + {Calendar.HOUR_OF_DAY, Calendar.HOUR}, + {Calendar.DATE, Calendar.DAY_OF_MONTH, Calendar.AM_PM + /* Calendar.DAY_OF_YEAR, Calendar.DAY_OF_WEEK, Calendar.DAY_OF_WEEK_IN_MONTH */ + }, + {Calendar.MONTH, DateUtils.SEMI_MONTH}, + {Calendar.YEAR}, + {Calendar.ERA}}; + + /** + * A week range, starting on Sunday. + */ + public static final int RANGE_WEEK_SUNDAY = 1; + /** + * A week range, starting on Monday. + */ + public static final int RANGE_WEEK_MONDAY = 2; + /** + * A week range, starting on the day focused. + */ + public static final int RANGE_WEEK_RELATIVE = 3; + /** + * A week range, centered around the day focused. + */ + public static final int RANGE_WEEK_CENTER = 4; + /** + * A month range, the week starting on Sunday. + */ + public static final int RANGE_MONTH_SUNDAY = 5; + /** + * A month range, the week starting on Monday. + */ + public static final int RANGE_MONTH_MONDAY = 6; + + /** + * Calendar modification types. + */ + private enum ModifyType { + /** + * Truncation. + */ + TRUNCATE, + + /** + * Rounding. + */ + ROUND, + + /** + * Ceiling. + */ + CEILING + } + + /** + *{@code DateUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code DateUtils.parseDate(str);}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public DateUtils() { + super(); + } + + //----------------------------------------------------------------------- + /** + *Checks if two date objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar cal1 = Calendar.getInstance();
+ cal1.setTime(date1);
+ final Calendar cal2 = Calendar.getInstance();
+ cal2.setTime(date2);
+ return isSameDay(cal1, cal2);
+ }
+
+ /**
+ * Checks if two calendar objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either calendar isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two date objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return date1.getTime() == date2.getTime();
+ }
+
+ /**
+ * Checks if two calendar objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.getTime().getTime() == cal2.getTime().getTime();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two calendar objects represent the same local time.
+ * + *This method compares the values of the fields of the two objects. + * In addition, both calendars must be the same of the same type.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameLocalTime(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.MILLISECOND) == cal2.get(Calendar.MILLISECOND) &&
+ cal1.get(Calendar.SECOND) == cal2.get(Calendar.SECOND) &&
+ cal1.get(Calendar.MINUTE) == cal2.get(Calendar.MINUTE) &&
+ cal1.get(Calendar.HOUR_OF_DAY) == cal2.get(Calendar.HOUR_OF_DAY) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.getClass() == cal2.getClass();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable (or there were none) + */ + public static Date parseDate(final String str, final String... parsePatterns) throws ParseException { + return parseDate(str, null, parsePatterns); + } + + //----------------------------------------------------------------------- + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDate(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable (or there were none)
+ * @since 3.2
+ */
+ public static Date parseDate(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, true);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @since 2.5 + */ + public static Date parseDateStrictly(final String str, final String... parsePatterns) throws ParseException { + return parseDateStrictly(str, null, parsePatterns); + } + + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale..
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDateStrictly(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable
+ * @since 3.2
+ */
+ public static Date parseDateStrictly(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, false);
+ }
+
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * + * @param str the date to parse, not null + * @param locale the locale to use when interpretting the pattern, can be null in which + * case the default system locale is used + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @param lenient Specify whether or not date/time parsing is to be lenient. + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @see java.util.Calendar#isLenient() + */ + private static Date parseDateWithLeniency( + final String str, final Locale locale, final String[] parsePatterns, final boolean lenient) throws ParseException { + if (str == null || parsePatterns == null) { + throw new IllegalArgumentException("Date and Patterns must not be null"); + } + + final TimeZone tz = TimeZone.getDefault(); + final Locale lcl = locale==null ?Locale.getDefault() : locale; + final ParsePosition pos = new ParsePosition(0); + final Calendar calendar = Calendar.getInstance(tz, lcl); + calendar.setLenient(lenient); + + for (final String parsePattern : parsePatterns) { + FastDateParser fdp = new FastDateParser(parsePattern, tz, lcl); + calendar.clear(); + try { + if (fdp.parse(str, pos, calendar) && pos.getIndex()==str.length()) { + return calendar.getTime(); + } + } + catch(IllegalArgumentException ignore) { + // leniency is preventing calendar from being set + } + pos.setIndex(0); + } + throw new ParseException("Unable to parse the date: " + str, -1); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of years to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addYears(final Date date, final int amount) { + return add(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of months to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMonths(final Date date, final int amount) { + return add(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of weeks to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addWeeks(final Date date, final int amount) { + return add(date, Calendar.WEEK_OF_YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of days to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addDays(final Date date, final int amount) { + return add(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of hours to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addHours(final Date date, final int amount) { + return add(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of minutes to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMinutes(final Date date, final int amount) { + return add(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of seconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addSeconds(final Date date, final int amount) { + return add(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of milliseconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMilliseconds(final Date date, final int amount) { + return add(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the calendar field to add to + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + private static Date add(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + final Calendar c = Calendar.getInstance(); + c.setTime(date); + c.add(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Sets the years field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setYears(final Date date, final int amount) { + return set(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the months field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMonths(final Date date, final int amount) { + return set(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the day of month field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setDays(final Date date, final int amount) { + return set(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the hours field to a date returning a new object. Hours range + * from 0-23. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setHours(final Date date, final int amount) { + return set(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the minute field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMinutes(final Date date, final int amount) { + return set(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the seconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setSeconds(final Date date, final int amount) { + return set(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the milliseconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMilliseconds(final Date date, final int amount) { + return set(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the specified field to a date returning a new object. + * This does not use a lenient calendar. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the {@code Calendar} field to set the amount to + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + private static Date set(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + // getInstance() returns a new object, so this method is thread safe. + final Calendar c = Calendar.getInstance(); + c.setLenient(false); + c.setTime(date); + c.set(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} into a {@code Calendar}. + * + * @param date the date to convert to a Calendar + * @return the created Calendar + * @throws NullPointerException if null is passed in + * @since 3.0 + */ + public static Calendar toCalendar(final Date date) { + final Calendar c = Calendar.getInstance(); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} of a given {@code TimeZone} into a {@code Calendar} + * @param date the date to convert to a Calendar + * @param tz the time zone of the @{code date} + * @return the created Calendar + * @throws NullPointerException if {@code date} or {@code tz} is null + */ + public static Calendar toCalendar(final Date date, final TimeZone tz) { + final Calendar c = Calendar.getInstance(tz); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar round(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar rounded = (Calendar) date.clone();
+ modify(rounded, field, ModifyType.ROUND);
+ return rounded;
+ }
+
+ /**
+ * Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date round(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return round((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return round((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not round " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.TRUNCATE);
+ return gval.getTime();
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar truncate(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar truncated = (Calendar) date.clone();
+ modify(truncated, field, ModifyType.TRUNCATE);
+ return truncated;
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return truncate((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return truncate((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not truncate " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.CEILING);
+ return gval.getTime();
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Calendar ceiling(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar ceiled = (Calendar) date.clone();
+ modify(ceiled, field, ModifyType.CEILING);
+ return ceiled;
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return ceiling((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return ceiling((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not find ceiling of for type: " + date.getClass());
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Internal calculation method.
+ * + * @param val the calendar, not null + * @param field the field constant + * @param modType type to truncate, round or ceiling + * @throws ArithmeticException if the year is over 280 million + */ + private static void modify(final Calendar val, final int field, final ModifyType modType) { + if (val.get(Calendar.YEAR) > 280000000) { + throw new ArithmeticException("Calendar value too large for accurate calculations"); + } + + if (field == Calendar.MILLISECOND) { + return; + } + + // ----------------- Fix for LANG-59 ---------------------- START --------------- + // see http://issues.apache.org/jira/browse/LANG-59 + // + // Manually truncate milliseconds, seconds and minutes, rather than using + // Calendar methods. + + final Date date = val.getTime(); + long time = date.getTime(); + boolean done = false; + + // truncate milliseconds + final int millisecs = val.get(Calendar.MILLISECOND); + if (ModifyType.TRUNCATE == modType || millisecs < 500) { + time = time - millisecs; + } + if (field == Calendar.SECOND) { + done = true; + } + + // truncate seconds + final int seconds = val.get(Calendar.SECOND); + if (!done && (ModifyType.TRUNCATE == modType || seconds < 30)) { + time = time - (seconds * 1000L); + } + if (field == Calendar.MINUTE) { + done = true; + } + + // truncate minutes + final int minutes = val.get(Calendar.MINUTE); + if (!done && (ModifyType.TRUNCATE == modType || minutes < 30)) { + time = time - (minutes * 60000L); + } + + // reset time + if (date.getTime() != time) { + date.setTime(time); + val.setTime(date); + } + // ----------------- Fix for LANG-59 ----------------------- END ---------------- + + boolean roundUp = false; + for (final int[] aField : fields) { + for (final int element : aField) { + if (element == field) { + //This is our field... we stop looping + if (modType == ModifyType.CEILING || modType == ModifyType.ROUND && roundUp) { + if (field == DateUtils.SEMI_MONTH) { + //This is a special case that's hard to generalize + //If the date is 1, we round up to 16, otherwise + // we subtract 15 days and add 1 month + if (val.get(Calendar.DATE) == 1) { + val.add(Calendar.DATE, 15); + } else { + val.add(Calendar.DATE, -15); + val.add(Calendar.MONTH, 1); + } +// ----------------- Fix for LANG-440 ---------------------- START --------------- + } else if (field == Calendar.AM_PM) { + // This is a special case + // If the time is 0, we round up to 12, otherwise + // we subtract 12 hours and add 1 day + if (val.get(Calendar.HOUR_OF_DAY) == 0) { + val.add(Calendar.HOUR_OF_DAY, 12); + } else { + val.add(Calendar.HOUR_OF_DAY, -12); + val.add(Calendar.DATE, 1); + } +// ----------------- Fix for LANG-440 ---------------------- END --------------- + } else { + //We need at add one to this field since the + // last number causes us to round up + val.add(aField[0], 1); + } + } + return; + } + } + //We have various fields that are not easy roundings + int offset = 0; + boolean offsetSet = false; + //These are special types of fields that require different rounding rules + switch (field) { + case DateUtils.SEMI_MONTH: + if (aField[0] == Calendar.DATE) { + //If we're going to drop the DATE field's value, + // we want to do this our own way. + //We need to subtrace 1 since the date has a minimum of 1 + offset = val.get(Calendar.DATE) - 1; + //If we're above 15 days adjustment, that means we're in the + // bottom half of the month and should stay accordingly. + if (offset >= 15) { + offset -= 15; + } + //Record whether we're in the top or bottom half of that range + roundUp = offset > 7; + offsetSet = true; + } + break; + case Calendar.AM_PM: + if (aField[0] == Calendar.HOUR_OF_DAY) { + //If we're going to drop the HOUR field's value, + // we want to do this our own way. + offset = val.get(Calendar.HOUR_OF_DAY); + if (offset >= 12) { + offset -= 12; + } + roundUp = offset >= 6; + offsetSet = true; + } + break; + default: + break; + } + if (!offsetSet) { + final int min = val.getActualMinimum(aField[0]); + final int max = val.getActualMaximum(aField[0]); + //Calculate the offset from the minimum allowed value + offset = val.get(aField[0]) - min; + //Set roundUp if this is more than half way between the minimum and maximum + roundUp = offset > ((max - min) / 2); + } + //We need to remove this field + if (offset != 0) { + val.set(aField[0], val.get(aField[0]) - offset); + } + } + throw new IllegalArgumentException("The field " + field + " is not supported"); + + } + + //----------------------------------------------------------------------- + /** + *Constructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ */
+ public static Iterator iterator(final Object focus, final int rangeStyle) {
+ if (focus == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (focus instanceof Date) {
+ return iterator((Date) focus, rangeStyle);
+ } else if (focus instanceof Calendar) {
+ return iterator((Calendar) focus, rangeStyle);
+ } else {
+ throw new ClassCastException("Could not iterate based on " + focus);
+ }
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of milliseconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all milliseconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MILLISECONDS);
+ }
+
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MILLISECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MILLISECONDS);
+ }
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Gets a Date fragment for any unit.
+ *
+ * @param date the date to work with, not null
+ * @param fragment the Calendar field part of date to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the date
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Date date, final int fragment, final TimeUnit unit) {
+ if(date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar calendar = Calendar.getInstance();
+ calendar.setTime(date);
+ return getFragment(calendar, fragment, unit);
+ }
+
+ /**
+ * Gets a Calendar fragment for any unit.
+ *
+ * @param calendar the calendar to work with, not null
+ * @param fragment the Calendar field part of calendar to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the calendar
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+/**
+ * Gets a Calendar fragment for any unit.
+ *
+ * @param calendar
+ * the calendar to work with, not null
+ * @param fragment
+ * the Calendar field part of calendar to calculate
+ * @param unit
+ * the time unit
+ * @return number of units within the fragment of the calendar
+ * @throws IllegalArgumentException
+ * if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+private static long getFragment(final java.util.Calendar calendar, final int fragment, final java.util.concurrent.TimeUnit unit) {
+ {
+ long result = 0;
+ final int offset = (unit == java.util.concurrent.TimeUnit.DAYS) ? 0 : 1;
+ // Fragments bigger than a day require a breakdown to days
+ switch (fragment) {
+ case java.util.Calendar.YEAR :
+ result += unit.convert(/* NPEX_NULL_EXP */
+ calendar.get(java.util.Calendar.DAY_OF_YEAR) - offset, java.util.concurrent.TimeUnit.DAYS);
+ break;
+ case java.util.Calendar.MONTH :
+ result += unit.convert(calendar.get(java.util.Calendar.DAY_OF_MONTH) - offset, java.util.concurrent.TimeUnit.DAYS);
+ break;
+ default :
+ break;
+ }
+ switch (fragment) {
+ // Number of days already calculated for these cases
+ case java.util.Calendar.YEAR :
+ case java.util.Calendar.MONTH :
+ // The rest of the valid cases
+ case java.util.Calendar.DAY_OF_YEAR :
+ case java.util.Calendar.DATE :
+ result += unit.convert(calendar.get(java.util.Calendar.HOUR_OF_DAY), java.util.concurrent.TimeUnit.HOURS);
+ // $FALL-THROUGH$
+ case java.util.Calendar.HOUR_OF_DAY :
+ result += unit.convert(calendar.get(java.util.Calendar.MINUTE), java.util.concurrent.TimeUnit.MINUTES);
+ // $FALL-THROUGH$
+ case java.util.Calendar.MINUTE :
+ result += unit.convert(calendar.get(java.util.Calendar.SECOND), java.util.concurrent.TimeUnit.SECONDS);
+ // $FALL-THROUGH$
+ case java.util.Calendar.SECOND :
+ result += unit.convert(calendar.get(java.util.Calendar.MILLISECOND), java.util.concurrent.TimeUnit.MILLISECONDS);
+ break;
+ case java.util.Calendar.MILLISECOND :
+ break;// never useful
+
+ default :
+ throw new java.lang.IllegalArgumentException(("The fragment " + fragment) + " is not supported");
+ }
+ return result;
+ }
+}
+
+ /**
+ * Determines if two calendars are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedEquals(Date, Date, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Calendar cal1, final Calendar cal2, final int field) {
+ return truncatedCompareTo(cal1, cal2, field) == 0;
+ }
+
+ /**
+ * Determines if two dates are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Date, int)
+ * @see #truncatedEquals(Calendar, Calendar, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Date date1, final Date date2, final int field) {
+ return truncatedCompareTo(date1, date2, field) == 0;
+ }
+
+ /**
+ * Determines how two calendars compare up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return a negative integer, zero, or a positive integer as the first
+ * calendar is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Calendar cal1, final Calendar cal2, final int field) {
+ final Calendar truncatedCal1 = truncate(cal1, field);
+ final Calendar truncatedCal2 = truncate(cal2, field);
+ return truncatedCal1.compareTo(truncatedCal2);
+ }
+
+ /**
+ * Determines how two dates compare up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from Calendar
+ * @return a negative integer, zero, or a positive integer as the first
+ * date is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Date date1, final Date date2, final int field) {
+ final Date truncatedDate1 = truncate(date1, field);
+ final Date truncatedDate2 = truncate(date2, field);
+ return truncatedDate1.compareTo(truncatedDate2);
+ }
+
+
+ //-----------------------------------------------------------------------
+ /**
+ * Date iterator.
+ */ + static class DateIterator implements Iteratortrue if the iterator has yet to reach the end date
+ */
+ @Override
+ public boolean hasNext() {
+ return spot.before(endFinal);
+ }
+
+ /**
+ * Return the next calendar in the iteration
+ *
+ * @return Object calendar for the next date
+ */
+ @Override
+ public Calendar next() {
+ if (spot.equals(endFinal)) {
+ throw new NoSuchElementException();
+ }
+ spot.add(Calendar.DATE, 1);
+ return (Calendar) spot.clone();
+ }
+
+ /**
+ * Always throws UnsupportedOperationException.
+ *
+ * @throws UnsupportedOperationException
+ * @see java.util.Iterator#remove()
+ */
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+}
diff --git a/Java/commons-lang-DateUtils_1678/metadata.json b/Java/commons-lang-DateUtils_1678/metadata.json
new file mode 100644
index 000000000..3e9d65041
--- /dev/null
+++ b/Java/commons-lang-DateUtils_1678/metadata.json
@@ -0,0 +1,21 @@
+{
+ "language": "java",
+ "id": "commons-lang-DateUtils_1678",
+ "buggyPath": ".",
+ "referencePath": null,
+ "buildCommand": "mvn package -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100 -DskipTests=true -DskipITs=true -Dtest=None -DfailIfNoTests=false",
+ "testCommand": "mvn test -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100",
+ "categories": [
+ "safety",
+ "npe"
+ ],
+ "npe": {
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 1700,
+ "npe_method": "getFragment",
+ "deref_field": "calendar",
+ "npe_class": "DateUtils",
+ "repo": "commons-lang",
+ "bug_id": "DateUtils_1678"
+ }
+}
diff --git a/Java/commons-lang-DateUtils_1678/npe.json b/Java/commons-lang-DateUtils_1678/npe.json
new file mode 100644
index 000000000..2975241f1
--- /dev/null
+++ b/Java/commons-lang-DateUtils_1678/npe.json
@@ -0,0 +1,7 @@
+{
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 1700,
+ "npe_method": "getFragment",
+ "deref_field": "calendar",
+ "npe_class": "DateUtils"
+}
\ No newline at end of file
diff --git a/Java/commons-lang-DateUtils_369/Dockerfile b/Java/commons-lang-DateUtils_369/Dockerfile
new file mode 100644
index 000000000..7b7fbe349
--- /dev/null
+++ b/Java/commons-lang-DateUtils_369/Dockerfile
@@ -0,0 +1,18 @@
+FROM ghcr.io/kupl/starlab-benchmarks/java-base:commons-lang
+
+ENV TZ=Asia/Seoul
+
+COPY ./metadata.json .
+COPY ./npe.json .
+COPY ./buggy.java /tmp/buggy.java
+RUN export BUGGY_PATH=$(cat metadata.json | jq -r ".npe.filepath") \
+ && export BUGGY_LINE=$(cat metadata.json | jq -r ".npe.line") \
+ && export BUGGY_MTHD=$(cat metadata.json | jq -r ".npe.npe_method") \
+ && mv /tmp/buggy.java $BUGGY_PATH \
+ && echo "[{\"filepath\": \"$BUGGY_PATH\", \"line\": $BUGGY_LINE, \"method_name\": \"$BUGGY_MTHD\"}]" | jq . > traces.json
+
+RUN git init . && git add -A
+
+RUN $(cat metadata.json | jq -r ".buildCommand")
+
+RUN $(cat metadata.json | jq -r ".testCommand"); if [ $? -eq 0 ]; then exit 1; fi
diff --git a/Java/commons-lang-DateUtils_369/buggy.java b/Java/commons-lang-DateUtils_369/buggy.java
new file mode 100644
index 000000000..0e1e9f0f0
--- /dev/null
+++ b/Java/commons-lang-DateUtils_369/buggy.java
@@ -0,0 +1,1875 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3.time;
+
+import java.text.ParseException;
+import java.text.ParsePosition;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.Iterator;
+import java.util.Locale;
+import java.util.NoSuchElementException;
+import java.util.TimeZone;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * A suite of utilities surrounding the use of the + * {@link java.util.Calendar} and {@link java.util.Date} object.
+ * + *DateUtils contains a lot of common methods considering manipulations + * of Dates or Calendars. Some methods require some extra explanation. + * The truncate, ceiling and round methods could be considered the Math.floor(), + * Math.ceil() or Math.round versions for dates + * This way date-fields will be ignored in bottom-up order. + * As a complement to these methods we've introduced some fragment-methods. + * With these methods the Date-fields will be ignored in top-down order. + * Since a date without a year is not a valid date, you have to decide in what + * kind of date-field you want your result, for instance milliseconds or days. + *
+ *+ * Several methods are provided for adding to {@code Date} objects, of the form + * {@code addXXX(Date date, int amount)}. It is important to note these methods + * use a {@code Calendar} internally (with default timezone and locale) and may + * be affected by changes to daylight saving time (DST). + *
+ * + * @since 2.0 + */ +public class DateUtils { + + /** + * Number of milliseconds in a standard second. + * @since 2.1 + */ + public static final long MILLIS_PER_SECOND = 1000; + /** + * Number of milliseconds in a standard minute. + * @since 2.1 + */ + public static final long MILLIS_PER_MINUTE = 60 * MILLIS_PER_SECOND; + /** + * Number of milliseconds in a standard hour. + * @since 2.1 + */ + public static final long MILLIS_PER_HOUR = 60 * MILLIS_PER_MINUTE; + /** + * Number of milliseconds in a standard day. + * @since 2.1 + */ + public static final long MILLIS_PER_DAY = 24 * MILLIS_PER_HOUR; + + /** + * This is half a month, so this represents whether a date is in the top + * or bottom half of the month. + */ + public static final int SEMI_MONTH = 1001; + + private static final int[][] fields = { + {Calendar.MILLISECOND}, + {Calendar.SECOND}, + {Calendar.MINUTE}, + {Calendar.HOUR_OF_DAY, Calendar.HOUR}, + {Calendar.DATE, Calendar.DAY_OF_MONTH, Calendar.AM_PM + /* Calendar.DAY_OF_YEAR, Calendar.DAY_OF_WEEK, Calendar.DAY_OF_WEEK_IN_MONTH */ + }, + {Calendar.MONTH, DateUtils.SEMI_MONTH}, + {Calendar.YEAR}, + {Calendar.ERA}}; + + /** + * A week range, starting on Sunday. + */ + public static final int RANGE_WEEK_SUNDAY = 1; + /** + * A week range, starting on Monday. + */ + public static final int RANGE_WEEK_MONDAY = 2; + /** + * A week range, starting on the day focused. + */ + public static final int RANGE_WEEK_RELATIVE = 3; + /** + * A week range, centered around the day focused. + */ + public static final int RANGE_WEEK_CENTER = 4; + /** + * A month range, the week starting on Sunday. + */ + public static final int RANGE_MONTH_SUNDAY = 5; + /** + * A month range, the week starting on Monday. + */ + public static final int RANGE_MONTH_MONDAY = 6; + + /** + * Calendar modification types. + */ + private enum ModifyType { + /** + * Truncation. + */ + TRUNCATE, + + /** + * Rounding. + */ + ROUND, + + /** + * Ceiling. + */ + CEILING + } + + /** + *{@code DateUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code DateUtils.parseDate(str);}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public DateUtils() { + super(); + } + + //----------------------------------------------------------------------- + /** + *Checks if two date objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar cal1 = Calendar.getInstance();
+ cal1.setTime(date1);
+ final Calendar cal2 = Calendar.getInstance();
+ cal2.setTime(date2);
+ return isSameDay(cal1, cal2);
+ }
+
+ /**
+ * Checks if two calendar objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either calendar isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two date objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return date1.getTime() == date2.getTime();
+ }
+
+ /**
+ * Checks if two calendar objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.getTime().getTime() == cal2.getTime().getTime();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two calendar objects represent the same local time.
+ * + *This method compares the values of the fields of the two objects. + * In addition, both calendars must be the same of the same type.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameLocalTime(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.MILLISECOND) == cal2.get(Calendar.MILLISECOND) &&
+ cal1.get(Calendar.SECOND) == cal2.get(Calendar.SECOND) &&
+ cal1.get(Calendar.MINUTE) == cal2.get(Calendar.MINUTE) &&
+ cal1.get(Calendar.HOUR_OF_DAY) == cal2.get(Calendar.HOUR_OF_DAY) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.getClass() == cal2.getClass();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable (or there were none) + */ + public static Date parseDate(final String str, final String... parsePatterns) throws ParseException { + return parseDate(str, null, parsePatterns); + } + + //----------------------------------------------------------------------- + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDate(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable (or there were none)
+ * @since 3.2
+ */
+ public static Date parseDate(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, true);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @since 2.5 + */ + public static Date parseDateStrictly(final String str, final String... parsePatterns) throws ParseException { + return parseDateStrictly(str, null, parsePatterns); + } + + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale..
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDateStrictly(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable
+ * @since 3.2
+ */
+ public static Date parseDateStrictly(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, false);
+ }
+
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * + * @param str the date to parse, not null + * @param locale the locale to use when interpretting the pattern, can be null in which + * case the default system locale is used + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @param lenient Specify whether or not date/time parsing is to be lenient. + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @see java.util.Calendar#isLenient() + */ +/** + *Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * + * @param str + * the date to parse, not null + * @param locale + * the locale to use when interpretting the pattern, can be null in which + * case the default system locale is used + * @param parsePatterns + * the date format patterns to use, see SimpleDateFormat, not null + * @param lenient + * Specify whether or not date/time parsing is to be lenient. + * @return the parsed date + * @throws IllegalArgumentException + * if the date string or pattern array is null + * @throws ParseException + * if none of the date patterns were suitable + * @see java.util.Calendar#isLenient() + */ +private static java.util.Date parseDateWithLeniency(final java.lang.String str, final java.util.Locale locale, final java.lang.String[] parsePatterns, final boolean lenient) throws java.text.ParseException { + if ((str == null) || (parsePatterns == null)) { + throw new java.lang.IllegalArgumentException("Date and Patterns must not be null"); + } + final java.util.TimeZone tz = java.util.TimeZone.getDefault(); + final java.util.Locale lcl = /* NPEX_NULL_EXP */ + locale; + final java.text.ParsePosition pos = new java.text.ParsePosition(0); + final java.util.Calendar calendar = java.util.Calendar.getInstance(tz, lcl); + calendar.setLenient(lenient); + for (final java.lang.String parsePattern : parsePatterns) { + org.apache.commons.lang3.time.FastDateParser fdp = new org.apache.commons.lang3.time.FastDateParser(parsePattern, tz, lcl); + calendar.clear(); + try { + if (fdp.parse(str, pos, calendar) && (pos.getIndex() == str.length())) { + return calendar.getTime(); + } + } catch (java.lang.IllegalArgumentException ignore) { + // leniency is preventing calendar from being set + } + pos.setIndex(0); + } + throw new java.text.ParseException("Unable to parse the date: " + str, -1); +} + + //----------------------------------------------------------------------- + /** + * Adds a number of years to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addYears(final Date date, final int amount) { + return add(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of months to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMonths(final Date date, final int amount) { + return add(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of weeks to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addWeeks(final Date date, final int amount) { + return add(date, Calendar.WEEK_OF_YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of days to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addDays(final Date date, final int amount) { + return add(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of hours to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addHours(final Date date, final int amount) { + return add(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of minutes to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMinutes(final Date date, final int amount) { + return add(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of seconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addSeconds(final Date date, final int amount) { + return add(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of milliseconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMilliseconds(final Date date, final int amount) { + return add(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the calendar field to add to + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + private static Date add(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + final Calendar c = Calendar.getInstance(); + c.setTime(date); + c.add(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Sets the years field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setYears(final Date date, final int amount) { + return set(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the months field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMonths(final Date date, final int amount) { + return set(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the day of month field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setDays(final Date date, final int amount) { + return set(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the hours field to a date returning a new object. Hours range + * from 0-23. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setHours(final Date date, final int amount) { + return set(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the minute field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMinutes(final Date date, final int amount) { + return set(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the seconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setSeconds(final Date date, final int amount) { + return set(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the milliseconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMilliseconds(final Date date, final int amount) { + return set(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the specified field to a date returning a new object. + * This does not use a lenient calendar. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the {@code Calendar} field to set the amount to + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + private static Date set(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + // getInstance() returns a new object, so this method is thread safe. + final Calendar c = Calendar.getInstance(); + c.setLenient(false); + c.setTime(date); + c.set(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} into a {@code Calendar}. + * + * @param date the date to convert to a Calendar + * @return the created Calendar + * @throws NullPointerException if null is passed in + * @since 3.0 + */ + public static Calendar toCalendar(final Date date) { + final Calendar c = Calendar.getInstance(); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} of a given {@code TimeZone} into a {@code Calendar} + * @param date the date to convert to a Calendar + * @param tz the time zone of the @{code date} + * @return the created Calendar + * @throws NullPointerException if {@code date} or {@code tz} is null + */ + public static Calendar toCalendar(final Date date, final TimeZone tz) { + final Calendar c = Calendar.getInstance(tz); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar round(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar rounded = (Calendar) date.clone();
+ modify(rounded, field, ModifyType.ROUND);
+ return rounded;
+ }
+
+ /**
+ * Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date round(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return round((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return round((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not round " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.TRUNCATE);
+ return gval.getTime();
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar truncate(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar truncated = (Calendar) date.clone();
+ modify(truncated, field, ModifyType.TRUNCATE);
+ return truncated;
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return truncate((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return truncate((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not truncate " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.CEILING);
+ return gval.getTime();
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Calendar ceiling(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar ceiled = (Calendar) date.clone();
+ modify(ceiled, field, ModifyType.CEILING);
+ return ceiled;
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return ceiling((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return ceiling((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not find ceiling of for type: " + date.getClass());
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Internal calculation method.
+ * + * @param val the calendar, not null + * @param field the field constant + * @param modType type to truncate, round or ceiling + * @throws ArithmeticException if the year is over 280 million + */ + private static void modify(final Calendar val, final int field, final ModifyType modType) { + if (val.get(Calendar.YEAR) > 280000000) { + throw new ArithmeticException("Calendar value too large for accurate calculations"); + } + + if (field == Calendar.MILLISECOND) { + return; + } + + // ----------------- Fix for LANG-59 ---------------------- START --------------- + // see http://issues.apache.org/jira/browse/LANG-59 + // + // Manually truncate milliseconds, seconds and minutes, rather than using + // Calendar methods. + + final Date date = val.getTime(); + long time = date.getTime(); + boolean done = false; + + // truncate milliseconds + final int millisecs = val.get(Calendar.MILLISECOND); + if (ModifyType.TRUNCATE == modType || millisecs < 500) { + time = time - millisecs; + } + if (field == Calendar.SECOND) { + done = true; + } + + // truncate seconds + final int seconds = val.get(Calendar.SECOND); + if (!done && (ModifyType.TRUNCATE == modType || seconds < 30)) { + time = time - (seconds * 1000L); + } + if (field == Calendar.MINUTE) { + done = true; + } + + // truncate minutes + final int minutes = val.get(Calendar.MINUTE); + if (!done && (ModifyType.TRUNCATE == modType || minutes < 30)) { + time = time - (minutes * 60000L); + } + + // reset time + if (date.getTime() != time) { + date.setTime(time); + val.setTime(date); + } + // ----------------- Fix for LANG-59 ----------------------- END ---------------- + + boolean roundUp = false; + for (final int[] aField : fields) { + for (final int element : aField) { + if (element == field) { + //This is our field... we stop looping + if (modType == ModifyType.CEILING || modType == ModifyType.ROUND && roundUp) { + if (field == DateUtils.SEMI_MONTH) { + //This is a special case that's hard to generalize + //If the date is 1, we round up to 16, otherwise + // we subtract 15 days and add 1 month + if (val.get(Calendar.DATE) == 1) { + val.add(Calendar.DATE, 15); + } else { + val.add(Calendar.DATE, -15); + val.add(Calendar.MONTH, 1); + } +// ----------------- Fix for LANG-440 ---------------------- START --------------- + } else if (field == Calendar.AM_PM) { + // This is a special case + // If the time is 0, we round up to 12, otherwise + // we subtract 12 hours and add 1 day + if (val.get(Calendar.HOUR_OF_DAY) == 0) { + val.add(Calendar.HOUR_OF_DAY, 12); + } else { + val.add(Calendar.HOUR_OF_DAY, -12); + val.add(Calendar.DATE, 1); + } +// ----------------- Fix for LANG-440 ---------------------- END --------------- + } else { + //We need at add one to this field since the + // last number causes us to round up + val.add(aField[0], 1); + } + } + return; + } + } + //We have various fields that are not easy roundings + int offset = 0; + boolean offsetSet = false; + //These are special types of fields that require different rounding rules + switch (field) { + case DateUtils.SEMI_MONTH: + if (aField[0] == Calendar.DATE) { + //If we're going to drop the DATE field's value, + // we want to do this our own way. + //We need to subtrace 1 since the date has a minimum of 1 + offset = val.get(Calendar.DATE) - 1; + //If we're above 15 days adjustment, that means we're in the + // bottom half of the month and should stay accordingly. + if (offset >= 15) { + offset -= 15; + } + //Record whether we're in the top or bottom half of that range + roundUp = offset > 7; + offsetSet = true; + } + break; + case Calendar.AM_PM: + if (aField[0] == Calendar.HOUR_OF_DAY) { + //If we're going to drop the HOUR field's value, + // we want to do this our own way. + offset = val.get(Calendar.HOUR_OF_DAY); + if (offset >= 12) { + offset -= 12; + } + roundUp = offset >= 6; + offsetSet = true; + } + break; + default: + break; + } + if (!offsetSet) { + final int min = val.getActualMinimum(aField[0]); + final int max = val.getActualMaximum(aField[0]); + //Calculate the offset from the minimum allowed value + offset = val.get(aField[0]) - min; + //Set roundUp if this is more than half way between the minimum and maximum + roundUp = offset > ((max - min) / 2); + } + //We need to remove this field + if (offset != 0) { + val.set(aField[0], val.get(aField[0]) - offset); + } + } + throw new IllegalArgumentException("The field " + field + " is not supported"); + + } + + //----------------------------------------------------------------------- + /** + *Constructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ */
+ public static Iterator iterator(final Object focus, final int rangeStyle) {
+ if (focus == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (focus instanceof Date) {
+ return iterator((Date) focus, rangeStyle);
+ } else if (focus instanceof Calendar) {
+ return iterator((Calendar) focus, rangeStyle);
+ } else {
+ throw new ClassCastException("Could not iterate based on " + focus);
+ }
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of milliseconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all milliseconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MILLISECONDS);
+ }
+
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MILLISECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MILLISECONDS);
+ }
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Gets a Date fragment for any unit.
+ *
+ * @param date the date to work with, not null
+ * @param fragment the Calendar field part of date to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the date
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Date date, final int fragment, final TimeUnit unit) {
+ if(date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar calendar = Calendar.getInstance();
+ calendar.setTime(date);
+ return getFragment(calendar, fragment, unit);
+ }
+
+ /**
+ * Gets a Calendar fragment for any unit.
+ *
+ * @param calendar the calendar to work with, not null
+ * @param fragment the Calendar field part of calendar to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the calendar
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Calendar calendar, final int fragment, final TimeUnit unit) {
+ if(calendar == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+
+ long result = 0;
+
+ final int offset = (unit == TimeUnit.DAYS) ? 0 : 1;
+
+ // Fragments bigger than a day require a breakdown to days
+ switch (fragment) {
+ case Calendar.YEAR:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_YEAR) - offset, TimeUnit.DAYS);
+ break;
+ case Calendar.MONTH:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_MONTH) - offset, TimeUnit.DAYS);
+ break;
+ default:
+ break;
+ }
+
+ switch (fragment) {
+ // Number of days already calculated for these cases
+ case Calendar.YEAR:
+ case Calendar.MONTH:
+
+ // The rest of the valid cases
+ case Calendar.DAY_OF_YEAR:
+ case Calendar.DATE:
+ result += unit.convert(calendar.get(Calendar.HOUR_OF_DAY), TimeUnit.HOURS);
+ //$FALL-THROUGH$
+ case Calendar.HOUR_OF_DAY:
+ result += unit.convert(calendar.get(Calendar.MINUTE), TimeUnit.MINUTES);
+ //$FALL-THROUGH$
+ case Calendar.MINUTE:
+ result += unit.convert(calendar.get(Calendar.SECOND), TimeUnit.SECONDS);
+ //$FALL-THROUGH$
+ case Calendar.SECOND:
+ result += unit.convert(calendar.get(Calendar.MILLISECOND), TimeUnit.MILLISECONDS);
+ break;
+ case Calendar.MILLISECOND: break;//never useful
+ default: throw new IllegalArgumentException("The fragment " + fragment + " is not supported");
+ }
+ return result;
+ }
+
+ /**
+ * Determines if two calendars are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedEquals(Date, Date, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Calendar cal1, final Calendar cal2, final int field) {
+ return truncatedCompareTo(cal1, cal2, field) == 0;
+ }
+
+ /**
+ * Determines if two dates are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Date, int)
+ * @see #truncatedEquals(Calendar, Calendar, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Date date1, final Date date2, final int field) {
+ return truncatedCompareTo(date1, date2, field) == 0;
+ }
+
+ /**
+ * Determines how two calendars compare up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return a negative integer, zero, or a positive integer as the first
+ * calendar is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Calendar cal1, final Calendar cal2, final int field) {
+ final Calendar truncatedCal1 = truncate(cal1, field);
+ final Calendar truncatedCal2 = truncate(cal2, field);
+ return truncatedCal1.compareTo(truncatedCal2);
+ }
+
+ /**
+ * Determines how two dates compare up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from Calendar
+ * @return a negative integer, zero, or a positive integer as the first
+ * date is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Date date1, final Date date2, final int field) {
+ final Date truncatedDate1 = truncate(date1, field);
+ final Date truncatedDate2 = truncate(date2, field);
+ return truncatedDate1.compareTo(truncatedDate2);
+ }
+
+
+ //-----------------------------------------------------------------------
+ /**
+ * Date iterator.
+ */ + static class DateIterator implements Iteratortrue if the iterator has yet to reach the end date
+ */
+ @Override
+ public boolean hasNext() {
+ return spot.before(endFinal);
+ }
+
+ /**
+ * Return the next calendar in the iteration
+ *
+ * @return Object calendar for the next date
+ */
+ @Override
+ public Calendar next() {
+ if (spot.equals(endFinal)) {
+ throw new NoSuchElementException();
+ }
+ spot.add(Calendar.DATE, 1);
+ return (Calendar) spot.clone();
+ }
+
+ /**
+ * Always throws UnsupportedOperationException.
+ *
+ * @throws UnsupportedOperationException
+ * @see java.util.Iterator#remove()
+ */
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+}
diff --git a/Java/commons-lang-DateUtils_369/metadata.json b/Java/commons-lang-DateUtils_369/metadata.json
new file mode 100644
index 000000000..b28b61a96
--- /dev/null
+++ b/Java/commons-lang-DateUtils_369/metadata.json
@@ -0,0 +1,21 @@
+{
+ "language": "java",
+ "id": "commons-lang-DateUtils_369",
+ "buggyPath": ".",
+ "referencePath": null,
+ "buildCommand": "mvn package -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100 -DskipTests=true -DskipITs=true -Dtest=None -DfailIfNoTests=false",
+ "testCommand": "mvn test -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100",
+ "categories": [
+ "safety",
+ "npe"
+ ],
+ "npe": {
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 391,
+ "npe_method": "parseDateWithLeniency",
+ "deref_field": "locale",
+ "npe_class": "DateUtils",
+ "repo": "commons-lang",
+ "bug_id": "DateUtils_369"
+ }
+}
diff --git a/Java/commons-lang-DateUtils_369/npe.json b/Java/commons-lang-DateUtils_369/npe.json
new file mode 100644
index 000000000..84bc18806
--- /dev/null
+++ b/Java/commons-lang-DateUtils_369/npe.json
@@ -0,0 +1,7 @@
+{
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 391,
+ "npe_method": "parseDateWithLeniency",
+ "deref_field": "locale",
+ "npe_class": "DateUtils"
+}
\ No newline at end of file
diff --git a/Java/commons-lang-DateUtils_711/Dockerfile b/Java/commons-lang-DateUtils_711/Dockerfile
new file mode 100644
index 000000000..7b7fbe349
--- /dev/null
+++ b/Java/commons-lang-DateUtils_711/Dockerfile
@@ -0,0 +1,18 @@
+FROM ghcr.io/kupl/starlab-benchmarks/java-base:commons-lang
+
+ENV TZ=Asia/Seoul
+
+COPY ./metadata.json .
+COPY ./npe.json .
+COPY ./buggy.java /tmp/buggy.java
+RUN export BUGGY_PATH=$(cat metadata.json | jq -r ".npe.filepath") \
+ && export BUGGY_LINE=$(cat metadata.json | jq -r ".npe.line") \
+ && export BUGGY_MTHD=$(cat metadata.json | jq -r ".npe.npe_method") \
+ && mv /tmp/buggy.java $BUGGY_PATH \
+ && echo "[{\"filepath\": \"$BUGGY_PATH\", \"line\": $BUGGY_LINE, \"method_name\": \"$BUGGY_MTHD\"}]" | jq . > traces.json
+
+RUN git init . && git add -A
+
+RUN $(cat metadata.json | jq -r ".buildCommand")
+
+RUN $(cat metadata.json | jq -r ".testCommand"); if [ $? -eq 0 ]; then exit 1; fi
diff --git a/Java/commons-lang-DateUtils_711/buggy.java b/Java/commons-lang-DateUtils_711/buggy.java
new file mode 100644
index 000000000..8bbbcd057
--- /dev/null
+++ b/Java/commons-lang-DateUtils_711/buggy.java
@@ -0,0 +1,1885 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3.time;
+
+import java.text.ParseException;
+import java.text.ParsePosition;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.Iterator;
+import java.util.Locale;
+import java.util.NoSuchElementException;
+import java.util.TimeZone;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * A suite of utilities surrounding the use of the + * {@link java.util.Calendar} and {@link java.util.Date} object.
+ * + *DateUtils contains a lot of common methods considering manipulations + * of Dates or Calendars. Some methods require some extra explanation. + * The truncate, ceiling and round methods could be considered the Math.floor(), + * Math.ceil() or Math.round versions for dates + * This way date-fields will be ignored in bottom-up order. + * As a complement to these methods we've introduced some fragment-methods. + * With these methods the Date-fields will be ignored in top-down order. + * Since a date without a year is not a valid date, you have to decide in what + * kind of date-field you want your result, for instance milliseconds or days. + *
+ *+ * Several methods are provided for adding to {@code Date} objects, of the form + * {@code addXXX(Date date, int amount)}. It is important to note these methods + * use a {@code Calendar} internally (with default timezone and locale) and may + * be affected by changes to daylight saving time (DST). + *
+ * + * @since 2.0 + */ +public class DateUtils { + + /** + * Number of milliseconds in a standard second. + * @since 2.1 + */ + public static final long MILLIS_PER_SECOND = 1000; + /** + * Number of milliseconds in a standard minute. + * @since 2.1 + */ + public static final long MILLIS_PER_MINUTE = 60 * MILLIS_PER_SECOND; + /** + * Number of milliseconds in a standard hour. + * @since 2.1 + */ + public static final long MILLIS_PER_HOUR = 60 * MILLIS_PER_MINUTE; + /** + * Number of milliseconds in a standard day. + * @since 2.1 + */ + public static final long MILLIS_PER_DAY = 24 * MILLIS_PER_HOUR; + + /** + * This is half a month, so this represents whether a date is in the top + * or bottom half of the month. + */ + public static final int SEMI_MONTH = 1001; + + private static final int[][] fields = { + {Calendar.MILLISECOND}, + {Calendar.SECOND}, + {Calendar.MINUTE}, + {Calendar.HOUR_OF_DAY, Calendar.HOUR}, + {Calendar.DATE, Calendar.DAY_OF_MONTH, Calendar.AM_PM + /* Calendar.DAY_OF_YEAR, Calendar.DAY_OF_WEEK, Calendar.DAY_OF_WEEK_IN_MONTH */ + }, + {Calendar.MONTH, DateUtils.SEMI_MONTH}, + {Calendar.YEAR}, + {Calendar.ERA}}; + + /** + * A week range, starting on Sunday. + */ + public static final int RANGE_WEEK_SUNDAY = 1; + /** + * A week range, starting on Monday. + */ + public static final int RANGE_WEEK_MONDAY = 2; + /** + * A week range, starting on the day focused. + */ + public static final int RANGE_WEEK_RELATIVE = 3; + /** + * A week range, centered around the day focused. + */ + public static final int RANGE_WEEK_CENTER = 4; + /** + * A month range, the week starting on Sunday. + */ + public static final int RANGE_MONTH_SUNDAY = 5; + /** + * A month range, the week starting on Monday. + */ + public static final int RANGE_MONTH_MONDAY = 6; + + /** + * Calendar modification types. + */ + private enum ModifyType { + /** + * Truncation. + */ + TRUNCATE, + + /** + * Rounding. + */ + ROUND, + + /** + * Ceiling. + */ + CEILING + } + + /** + *{@code DateUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code DateUtils.parseDate(str);}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public DateUtils() { + super(); + } + + //----------------------------------------------------------------------- + /** + *Checks if two date objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar cal1 = Calendar.getInstance();
+ cal1.setTime(date1);
+ final Calendar cal2 = Calendar.getInstance();
+ cal2.setTime(date2);
+ return isSameDay(cal1, cal2);
+ }
+
+ /**
+ * Checks if two calendar objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either calendar isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two date objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return date1.getTime() == date2.getTime();
+ }
+
+ /**
+ * Checks if two calendar objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.getTime().getTime() == cal2.getTime().getTime();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two calendar objects represent the same local time.
+ * + *This method compares the values of the fields of the two objects. + * In addition, both calendars must be the same of the same type.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameLocalTime(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.MILLISECOND) == cal2.get(Calendar.MILLISECOND) &&
+ cal1.get(Calendar.SECOND) == cal2.get(Calendar.SECOND) &&
+ cal1.get(Calendar.MINUTE) == cal2.get(Calendar.MINUTE) &&
+ cal1.get(Calendar.HOUR_OF_DAY) == cal2.get(Calendar.HOUR_OF_DAY) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.getClass() == cal2.getClass();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable (or there were none) + */ + public static Date parseDate(final String str, final String... parsePatterns) throws ParseException { + return parseDate(str, null, parsePatterns); + } + + //----------------------------------------------------------------------- + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDate(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable (or there were none)
+ * @since 3.2
+ */
+ public static Date parseDate(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, true);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @since 2.5 + */ + public static Date parseDateStrictly(final String str, final String... parsePatterns) throws ParseException { + return parseDateStrictly(str, null, parsePatterns); + } + + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale..
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDateStrictly(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable
+ * @since 3.2
+ */
+ public static Date parseDateStrictly(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, false);
+ }
+
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * + * @param str the date to parse, not null + * @param locale the locale to use when interpretting the pattern, can be null in which + * case the default system locale is used + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @param lenient Specify whether or not date/time parsing is to be lenient. + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @see java.util.Calendar#isLenient() + */ + private static Date parseDateWithLeniency( + final String str, final Locale locale, final String[] parsePatterns, final boolean lenient) throws ParseException { + if (str == null || parsePatterns == null) { + throw new IllegalArgumentException("Date and Patterns must not be null"); + } + + final TimeZone tz = TimeZone.getDefault(); + final Locale lcl = locale==null ?Locale.getDefault() : locale; + final ParsePosition pos = new ParsePosition(0); + final Calendar calendar = Calendar.getInstance(tz, lcl); + calendar.setLenient(lenient); + + for (final String parsePattern : parsePatterns) { + FastDateParser fdp = new FastDateParser(parsePattern, tz, lcl); + calendar.clear(); + try { + if (fdp.parse(str, pos, calendar) && pos.getIndex()==str.length()) { + return calendar.getTime(); + } + } + catch(IllegalArgumentException ignore) { + // leniency is preventing calendar from being set + } + pos.setIndex(0); + } + throw new ParseException("Unable to parse the date: " + str, -1); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of years to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addYears(final Date date, final int amount) { + return add(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of months to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMonths(final Date date, final int amount) { + return add(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of weeks to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addWeeks(final Date date, final int amount) { + return add(date, Calendar.WEEK_OF_YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of days to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addDays(final Date date, final int amount) { + return add(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of hours to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addHours(final Date date, final int amount) { + return add(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of minutes to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMinutes(final Date date, final int amount) { + return add(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of seconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addSeconds(final Date date, final int amount) { + return add(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of milliseconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMilliseconds(final Date date, final int amount) { + return add(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the calendar field to add to + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + private static Date add(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + final Calendar c = Calendar.getInstance(); + c.setTime(date); + c.add(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Sets the years field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setYears(final Date date, final int amount) { + return set(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the months field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMonths(final Date date, final int amount) { + return set(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the day of month field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setDays(final Date date, final int amount) { + return set(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the hours field to a date returning a new object. Hours range + * from 0-23. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setHours(final Date date, final int amount) { + return set(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the minute field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMinutes(final Date date, final int amount) { + return set(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the seconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setSeconds(final Date date, final int amount) { + return set(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the milliseconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMilliseconds(final Date date, final int amount) { + return set(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the specified field to a date returning a new object. + * This does not use a lenient calendar. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the {@code Calendar} field to set the amount to + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + private static Date set(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + // getInstance() returns a new object, so this method is thread safe. + final Calendar c = Calendar.getInstance(); + c.setLenient(false); + c.setTime(date); + c.set(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} into a {@code Calendar}. + * + * @param date the date to convert to a Calendar + * @return the created Calendar + * @throws NullPointerException if null is passed in + * @since 3.0 + */ + public static Calendar toCalendar(final Date date) { + final Calendar c = Calendar.getInstance(); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} of a given {@code TimeZone} into a {@code Calendar} + * @param date the date to convert to a Calendar + * @param tz the time zone of the @{code date} + * @return the created Calendar + * @throws NullPointerException if {@code date} or {@code tz} is null + */ + public static Calendar toCalendar(final Date date, final TimeZone tz) { + final Calendar c = Calendar.getInstance(tz); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar round(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar rounded = (Calendar) date.clone();
+ modify(rounded, field, ModifyType.ROUND);
+ return rounded;
+ }
+
+ /**
+ * Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date round(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return round((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return round((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not round " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.TRUNCATE);
+ return gval.getTime();
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar truncate(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar truncated = (Calendar) date.clone();
+ modify(truncated, field, ModifyType.TRUNCATE);
+ return truncated;
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return truncate((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return truncate((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not truncate " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.CEILING);
+ return gval.getTime();
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Calendar ceiling(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar ceiled = (Calendar) date.clone();
+ modify(ceiled, field, ModifyType.CEILING);
+ return ceiled;
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return ceiling((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return ceiling((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not find ceiling of for type: " + date.getClass());
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Internal calculation method.
+ * + * @param val the calendar, not null + * @param field the field constant + * @param modType type to truncate, round or ceiling + * @throws ArithmeticException if the year is over 280 million + */ + private static void modify(final Calendar val, final int field, final ModifyType modType) { + if (val.get(Calendar.YEAR) > 280000000) { + throw new ArithmeticException("Calendar value too large for accurate calculations"); + } + + if (field == Calendar.MILLISECOND) { + return; + } + + // ----------------- Fix for LANG-59 ---------------------- START --------------- + // see http://issues.apache.org/jira/browse/LANG-59 + // + // Manually truncate milliseconds, seconds and minutes, rather than using + // Calendar methods. + + final Date date = val.getTime(); + long time = date.getTime(); + boolean done = false; + + // truncate milliseconds + final int millisecs = val.get(Calendar.MILLISECOND); + if (ModifyType.TRUNCATE == modType || millisecs < 500) { + time = time - millisecs; + } + if (field == Calendar.SECOND) { + done = true; + } + + // truncate seconds + final int seconds = val.get(Calendar.SECOND); + if (!done && (ModifyType.TRUNCATE == modType || seconds < 30)) { + time = time - (seconds * 1000L); + } + if (field == Calendar.MINUTE) { + done = true; + } + + // truncate minutes + final int minutes = val.get(Calendar.MINUTE); + if (!done && (ModifyType.TRUNCATE == modType || minutes < 30)) { + time = time - (minutes * 60000L); + } + + // reset time + if (date.getTime() != time) { + date.setTime(time); + val.setTime(date); + } + // ----------------- Fix for LANG-59 ----------------------- END ---------------- + + boolean roundUp = false; + for (final int[] aField : fields) { + for (final int element : aField) { + if (element == field) { + //This is our field... we stop looping + if (modType == ModifyType.CEILING || modType == ModifyType.ROUND && roundUp) { + if (field == DateUtils.SEMI_MONTH) { + //This is a special case that's hard to generalize + //If the date is 1, we round up to 16, otherwise + // we subtract 15 days and add 1 month + if (val.get(Calendar.DATE) == 1) { + val.add(Calendar.DATE, 15); + } else { + val.add(Calendar.DATE, -15); + val.add(Calendar.MONTH, 1); + } +// ----------------- Fix for LANG-440 ---------------------- START --------------- + } else if (field == Calendar.AM_PM) { + // This is a special case + // If the time is 0, we round up to 12, otherwise + // we subtract 12 hours and add 1 day + if (val.get(Calendar.HOUR_OF_DAY) == 0) { + val.add(Calendar.HOUR_OF_DAY, 12); + } else { + val.add(Calendar.HOUR_OF_DAY, -12); + val.add(Calendar.DATE, 1); + } +// ----------------- Fix for LANG-440 ---------------------- END --------------- + } else { + //We need at add one to this field since the + // last number causes us to round up + val.add(aField[0], 1); + } + } + return; + } + } + //We have various fields that are not easy roundings + int offset = 0; + boolean offsetSet = false; + //These are special types of fields that require different rounding rules + switch (field) { + case DateUtils.SEMI_MONTH: + if (aField[0] == Calendar.DATE) { + //If we're going to drop the DATE field's value, + // we want to do this our own way. + //We need to subtrace 1 since the date has a minimum of 1 + offset = val.get(Calendar.DATE) - 1; + //If we're above 15 days adjustment, that means we're in the + // bottom half of the month and should stay accordingly. + if (offset >= 15) { + offset -= 15; + } + //Record whether we're in the top or bottom half of that range + roundUp = offset > 7; + offsetSet = true; + } + break; + case Calendar.AM_PM: + if (aField[0] == Calendar.HOUR_OF_DAY) { + //If we're going to drop the HOUR field's value, + // we want to do this our own way. + offset = val.get(Calendar.HOUR_OF_DAY); + if (offset >= 12) { + offset -= 12; + } + roundUp = offset >= 6; + offsetSet = true; + } + break; + default: + break; + } + if (!offsetSet) { + final int min = val.getActualMinimum(aField[0]); + final int max = val.getActualMaximum(aField[0]); + //Calculate the offset from the minimum allowed value + offset = val.get(aField[0]) - min; + //Set roundUp if this is more than half way between the minimum and maximum + roundUp = offset > ((max - min) / 2); + } + //We need to remove this field + if (offset != 0) { + val.set(aField[0], val.get(aField[0]) - offset); + } + } + throw new IllegalArgumentException("The field " + field + " is not supported"); + + } + + //----------------------------------------------------------------------- + /** + *Constructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ */
+ public static Iterator iterator(final Object focus, final int rangeStyle) {
+ if (focus == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (focus instanceof Date) {
+ return iterator((Date) focus, rangeStyle);
+ } else if (focus instanceof Calendar) {
+ return iterator((Calendar) focus, rangeStyle);
+ } else {
+ throw new ClassCastException("Could not iterate based on " + focus);
+ }
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of milliseconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all milliseconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MILLISECONDS);
+ }
+
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MILLISECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MILLISECONDS);
+ }
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Gets a Date fragment for any unit.
+ *
+ * @param date the date to work with, not null
+ * @param fragment the Calendar field part of date to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the date
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Date date, final int fragment, final TimeUnit unit) {
+ if(date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar calendar = Calendar.getInstance();
+ calendar.setTime(date);
+ return getFragment(calendar, fragment, unit);
+ }
+
+ /**
+ * Gets a Calendar fragment for any unit.
+ *
+ * @param calendar the calendar to work with, not null
+ * @param fragment the Calendar field part of calendar to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the calendar
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Calendar calendar, final int fragment, final TimeUnit unit) {
+ if(calendar == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+
+ long result = 0;
+
+ final int offset = (unit == TimeUnit.DAYS) ? 0 : 1;
+
+ // Fragments bigger than a day require a breakdown to days
+ switch (fragment) {
+ case Calendar.YEAR:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_YEAR) - offset, TimeUnit.DAYS);
+ break;
+ case Calendar.MONTH:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_MONTH) - offset, TimeUnit.DAYS);
+ break;
+ default:
+ break;
+ }
+
+ switch (fragment) {
+ // Number of days already calculated for these cases
+ case Calendar.YEAR:
+ case Calendar.MONTH:
+
+ // The rest of the valid cases
+ case Calendar.DAY_OF_YEAR:
+ case Calendar.DATE:
+ result += unit.convert(calendar.get(Calendar.HOUR_OF_DAY), TimeUnit.HOURS);
+ //$FALL-THROUGH$
+ case Calendar.HOUR_OF_DAY:
+ result += unit.convert(calendar.get(Calendar.MINUTE), TimeUnit.MINUTES);
+ //$FALL-THROUGH$
+ case Calendar.MINUTE:
+ result += unit.convert(calendar.get(Calendar.SECOND), TimeUnit.SECONDS);
+ //$FALL-THROUGH$
+ case Calendar.SECOND:
+ result += unit.convert(calendar.get(Calendar.MILLISECOND), TimeUnit.MILLISECONDS);
+ break;
+ case Calendar.MILLISECOND: break;//never useful
+ default: throw new IllegalArgumentException("The fragment " + fragment + " is not supported");
+ }
+ return result;
+ }
+
+ /**
+ * Determines if two calendars are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedEquals(Date, Date, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Calendar cal1, final Calendar cal2, final int field) {
+ return truncatedCompareTo(cal1, cal2, field) == 0;
+ }
+
+ /**
+ * Determines if two dates are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Date, int)
+ * @see #truncatedEquals(Calendar, Calendar, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Date date1, final Date date2, final int field) {
+ return truncatedCompareTo(date1, date2, field) == 0;
+ }
+
+ /**
+ * Determines how two calendars compare up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return a negative integer, zero, or a positive integer as the first
+ * calendar is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Calendar cal1, final Calendar cal2, final int field) {
+ final Calendar truncatedCal1 = truncate(cal1, field);
+ final Calendar truncatedCal2 = truncate(cal2, field);
+ return truncatedCal1.compareTo(truncatedCal2);
+ }
+
+ /**
+ * Determines how two dates compare up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from Calendar
+ * @return a negative integer, zero, or a positive integer as the first
+ * date is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Date date1, final Date date2, final int field) {
+ final Date truncatedDate1 = truncate(date1, field);
+ final Date truncatedDate2 = truncate(date2, field);
+ return truncatedDate1.compareTo(truncatedDate2);
+ }
+
+
+ //-----------------------------------------------------------------------
+ /**
+ * Date iterator.
+ */ + static class DateIterator implements Iteratortrue if the iterator has yet to reach the end date
+ */
+ @Override
+ public boolean hasNext() {
+ return spot.before(endFinal);
+ }
+
+ /**
+ * Return the next calendar in the iteration
+ *
+ * @return Object calendar for the next date
+ */
+ @Override
+ public Calendar next() {
+ if (spot.equals(endFinal)) {
+ throw new NoSuchElementException();
+ }
+ spot.add(Calendar.DATE, 1);
+ return (Calendar) spot.clone();
+ }
+
+ /**
+ * Always throws UnsupportedOperationException.
+ *
+ * @throws UnsupportedOperationException
+ * @see java.util.Iterator#remove()
+ */
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+}
diff --git a/Java/commons-lang-DateUtils_711/metadata.json b/Java/commons-lang-DateUtils_711/metadata.json
new file mode 100644
index 000000000..00aff0c38
--- /dev/null
+++ b/Java/commons-lang-DateUtils_711/metadata.json
@@ -0,0 +1,21 @@
+{
+ "language": "java",
+ "id": "commons-lang-DateUtils_711",
+ "buggyPath": ".",
+ "referencePath": null,
+ "buildCommand": "mvn package -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100 -DskipTests=true -DskipITs=true -Dtest=None -DfailIfNoTests=false",
+ "testCommand": "mvn test -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100",
+ "categories": [
+ "safety",
+ "npe"
+ ],
+ "npe": {
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 744,
+ "npe_method": "round",
+ "deref_field": "date",
+ "npe_class": "DateUtils",
+ "repo": "commons-lang",
+ "bug_id": "DateUtils_711"
+ }
+}
diff --git a/Java/commons-lang-DateUtils_711/npe.json b/Java/commons-lang-DateUtils_711/npe.json
new file mode 100644
index 000000000..ed73f1bf4
--- /dev/null
+++ b/Java/commons-lang-DateUtils_711/npe.json
@@ -0,0 +1,7 @@
+{
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 744,
+ "npe_method": "round",
+ "deref_field": "date",
+ "npe_class": "DateUtils"
+}
\ No newline at end of file
diff --git a/Java/commons-lang-DateUtils_748/Dockerfile b/Java/commons-lang-DateUtils_748/Dockerfile
new file mode 100644
index 000000000..7b7fbe349
--- /dev/null
+++ b/Java/commons-lang-DateUtils_748/Dockerfile
@@ -0,0 +1,18 @@
+FROM ghcr.io/kupl/starlab-benchmarks/java-base:commons-lang
+
+ENV TZ=Asia/Seoul
+
+COPY ./metadata.json .
+COPY ./npe.json .
+COPY ./buggy.java /tmp/buggy.java
+RUN export BUGGY_PATH=$(cat metadata.json | jq -r ".npe.filepath") \
+ && export BUGGY_LINE=$(cat metadata.json | jq -r ".npe.line") \
+ && export BUGGY_MTHD=$(cat metadata.json | jq -r ".npe.npe_method") \
+ && mv /tmp/buggy.java $BUGGY_PATH \
+ && echo "[{\"filepath\": \"$BUGGY_PATH\", \"line\": $BUGGY_LINE, \"method_name\": \"$BUGGY_MTHD\"}]" | jq . > traces.json
+
+RUN git init . && git add -A
+
+RUN $(cat metadata.json | jq -r ".buildCommand")
+
+RUN $(cat metadata.json | jq -r ".testCommand"); if [ $? -eq 0 ]; then exit 1; fi
diff --git a/Java/commons-lang-DateUtils_748/buggy.java b/Java/commons-lang-DateUtils_748/buggy.java
new file mode 100644
index 000000000..918e4742a
--- /dev/null
+++ b/Java/commons-lang-DateUtils_748/buggy.java
@@ -0,0 +1,1886 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3.time;
+
+import java.text.ParseException;
+import java.text.ParsePosition;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.Iterator;
+import java.util.Locale;
+import java.util.NoSuchElementException;
+import java.util.TimeZone;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * A suite of utilities surrounding the use of the + * {@link java.util.Calendar} and {@link java.util.Date} object.
+ * + *DateUtils contains a lot of common methods considering manipulations + * of Dates or Calendars. Some methods require some extra explanation. + * The truncate, ceiling and round methods could be considered the Math.floor(), + * Math.ceil() or Math.round versions for dates + * This way date-fields will be ignored in bottom-up order. + * As a complement to these methods we've introduced some fragment-methods. + * With these methods the Date-fields will be ignored in top-down order. + * Since a date without a year is not a valid date, you have to decide in what + * kind of date-field you want your result, for instance milliseconds or days. + *
+ *+ * Several methods are provided for adding to {@code Date} objects, of the form + * {@code addXXX(Date date, int amount)}. It is important to note these methods + * use a {@code Calendar} internally (with default timezone and locale) and may + * be affected by changes to daylight saving time (DST). + *
+ * + * @since 2.0 + */ +public class DateUtils { + + /** + * Number of milliseconds in a standard second. + * @since 2.1 + */ + public static final long MILLIS_PER_SECOND = 1000; + /** + * Number of milliseconds in a standard minute. + * @since 2.1 + */ + public static final long MILLIS_PER_MINUTE = 60 * MILLIS_PER_SECOND; + /** + * Number of milliseconds in a standard hour. + * @since 2.1 + */ + public static final long MILLIS_PER_HOUR = 60 * MILLIS_PER_MINUTE; + /** + * Number of milliseconds in a standard day. + * @since 2.1 + */ + public static final long MILLIS_PER_DAY = 24 * MILLIS_PER_HOUR; + + /** + * This is half a month, so this represents whether a date is in the top + * or bottom half of the month. + */ + public static final int SEMI_MONTH = 1001; + + private static final int[][] fields = { + {Calendar.MILLISECOND}, + {Calendar.SECOND}, + {Calendar.MINUTE}, + {Calendar.HOUR_OF_DAY, Calendar.HOUR}, + {Calendar.DATE, Calendar.DAY_OF_MONTH, Calendar.AM_PM + /* Calendar.DAY_OF_YEAR, Calendar.DAY_OF_WEEK, Calendar.DAY_OF_WEEK_IN_MONTH */ + }, + {Calendar.MONTH, DateUtils.SEMI_MONTH}, + {Calendar.YEAR}, + {Calendar.ERA}}; + + /** + * A week range, starting on Sunday. + */ + public static final int RANGE_WEEK_SUNDAY = 1; + /** + * A week range, starting on Monday. + */ + public static final int RANGE_WEEK_MONDAY = 2; + /** + * A week range, starting on the day focused. + */ + public static final int RANGE_WEEK_RELATIVE = 3; + /** + * A week range, centered around the day focused. + */ + public static final int RANGE_WEEK_CENTER = 4; + /** + * A month range, the week starting on Sunday. + */ + public static final int RANGE_MONTH_SUNDAY = 5; + /** + * A month range, the week starting on Monday. + */ + public static final int RANGE_MONTH_MONDAY = 6; + + /** + * Calendar modification types. + */ + private enum ModifyType { + /** + * Truncation. + */ + TRUNCATE, + + /** + * Rounding. + */ + ROUND, + + /** + * Ceiling. + */ + CEILING + } + + /** + *{@code DateUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code DateUtils.parseDate(str);}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public DateUtils() { + super(); + } + + //----------------------------------------------------------------------- + /** + *Checks if two date objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar cal1 = Calendar.getInstance();
+ cal1.setTime(date1);
+ final Calendar cal2 = Calendar.getInstance();
+ cal2.setTime(date2);
+ return isSameDay(cal1, cal2);
+ }
+
+ /**
+ * Checks if two calendar objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either calendar isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two date objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return date1.getTime() == date2.getTime();
+ }
+
+ /**
+ * Checks if two calendar objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.getTime().getTime() == cal2.getTime().getTime();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two calendar objects represent the same local time.
+ * + *This method compares the values of the fields of the two objects. + * In addition, both calendars must be the same of the same type.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameLocalTime(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.MILLISECOND) == cal2.get(Calendar.MILLISECOND) &&
+ cal1.get(Calendar.SECOND) == cal2.get(Calendar.SECOND) &&
+ cal1.get(Calendar.MINUTE) == cal2.get(Calendar.MINUTE) &&
+ cal1.get(Calendar.HOUR_OF_DAY) == cal2.get(Calendar.HOUR_OF_DAY) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.getClass() == cal2.getClass();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable (or there were none) + */ + public static Date parseDate(final String str, final String... parsePatterns) throws ParseException { + return parseDate(str, null, parsePatterns); + } + + //----------------------------------------------------------------------- + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDate(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable (or there were none)
+ * @since 3.2
+ */
+ public static Date parseDate(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, true);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @since 2.5 + */ + public static Date parseDateStrictly(final String str, final String... parsePatterns) throws ParseException { + return parseDateStrictly(str, null, parsePatterns); + } + + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale..
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDateStrictly(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable
+ * @since 3.2
+ */
+ public static Date parseDateStrictly(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, false);
+ }
+
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * + * @param str the date to parse, not null + * @param locale the locale to use when interpretting the pattern, can be null in which + * case the default system locale is used + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @param lenient Specify whether or not date/time parsing is to be lenient. + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @see java.util.Calendar#isLenient() + */ + private static Date parseDateWithLeniency( + final String str, final Locale locale, final String[] parsePatterns, final boolean lenient) throws ParseException { + if (str == null || parsePatterns == null) { + throw new IllegalArgumentException("Date and Patterns must not be null"); + } + + final TimeZone tz = TimeZone.getDefault(); + final Locale lcl = locale==null ?Locale.getDefault() : locale; + final ParsePosition pos = new ParsePosition(0); + final Calendar calendar = Calendar.getInstance(tz, lcl); + calendar.setLenient(lenient); + + for (final String parsePattern : parsePatterns) { + FastDateParser fdp = new FastDateParser(parsePattern, tz, lcl); + calendar.clear(); + try { + if (fdp.parse(str, pos, calendar) && pos.getIndex()==str.length()) { + return calendar.getTime(); + } + } + catch(IllegalArgumentException ignore) { + // leniency is preventing calendar from being set + } + pos.setIndex(0); + } + throw new ParseException("Unable to parse the date: " + str, -1); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of years to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addYears(final Date date, final int amount) { + return add(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of months to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMonths(final Date date, final int amount) { + return add(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of weeks to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addWeeks(final Date date, final int amount) { + return add(date, Calendar.WEEK_OF_YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of days to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addDays(final Date date, final int amount) { + return add(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of hours to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addHours(final Date date, final int amount) { + return add(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of minutes to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMinutes(final Date date, final int amount) { + return add(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of seconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addSeconds(final Date date, final int amount) { + return add(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of milliseconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMilliseconds(final Date date, final int amount) { + return add(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the calendar field to add to + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + private static Date add(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + final Calendar c = Calendar.getInstance(); + c.setTime(date); + c.add(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Sets the years field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setYears(final Date date, final int amount) { + return set(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the months field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMonths(final Date date, final int amount) { + return set(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the day of month field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setDays(final Date date, final int amount) { + return set(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the hours field to a date returning a new object. Hours range + * from 0-23. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setHours(final Date date, final int amount) { + return set(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the minute field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMinutes(final Date date, final int amount) { + return set(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the seconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setSeconds(final Date date, final int amount) { + return set(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the milliseconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMilliseconds(final Date date, final int amount) { + return set(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the specified field to a date returning a new object. + * This does not use a lenient calendar. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the {@code Calendar} field to set the amount to + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + private static Date set(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + // getInstance() returns a new object, so this method is thread safe. + final Calendar c = Calendar.getInstance(); + c.setLenient(false); + c.setTime(date); + c.set(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} into a {@code Calendar}. + * + * @param date the date to convert to a Calendar + * @return the created Calendar + * @throws NullPointerException if null is passed in + * @since 3.0 + */ + public static Calendar toCalendar(final Date date) { + final Calendar c = Calendar.getInstance(); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} of a given {@code TimeZone} into a {@code Calendar} + * @param date the date to convert to a Calendar + * @param tz the time zone of the @{code date} + * @return the created Calendar + * @throws NullPointerException if {@code date} or {@code tz} is null + */ + public static Calendar toCalendar(final Date date, final TimeZone tz) { + final Calendar c = Calendar.getInstance(tz); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+/**
+ * Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException
+ * if the date is null
+ * @throws ArithmeticException
+ * if the year is over 280 million
+ */
+public static java.util.Calendar round(final java.util.Calendar date, final int field) {
+ {
+ final java.util.Calendar rounded = ((java.util.Calendar) (/* NPEX_NULL_EXP */
+ date.clone()));
+ org.apache.commons.lang3.time.DateUtils.modify(rounded, field, org.apache.commons.lang3.time.DateUtils.ModifyType.ROUND);
+ return rounded;
+ }
+}
+
+ /**
+ * Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date round(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return round((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return round((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not round " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.TRUNCATE);
+ return gval.getTime();
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar truncate(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar truncated = (Calendar) date.clone();
+ modify(truncated, field, ModifyType.TRUNCATE);
+ return truncated;
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return truncate((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return truncate((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not truncate " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.CEILING);
+ return gval.getTime();
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Calendar ceiling(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar ceiled = (Calendar) date.clone();
+ modify(ceiled, field, ModifyType.CEILING);
+ return ceiled;
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return ceiling((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return ceiling((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not find ceiling of for type: " + date.getClass());
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Internal calculation method.
+ * + * @param val the calendar, not null + * @param field the field constant + * @param modType type to truncate, round or ceiling + * @throws ArithmeticException if the year is over 280 million + */ + private static void modify(final Calendar val, final int field, final ModifyType modType) { + if (val.get(Calendar.YEAR) > 280000000) { + throw new ArithmeticException("Calendar value too large for accurate calculations"); + } + + if (field == Calendar.MILLISECOND) { + return; + } + + // ----------------- Fix for LANG-59 ---------------------- START --------------- + // see http://issues.apache.org/jira/browse/LANG-59 + // + // Manually truncate milliseconds, seconds and minutes, rather than using + // Calendar methods. + + final Date date = val.getTime(); + long time = date.getTime(); + boolean done = false; + + // truncate milliseconds + final int millisecs = val.get(Calendar.MILLISECOND); + if (ModifyType.TRUNCATE == modType || millisecs < 500) { + time = time - millisecs; + } + if (field == Calendar.SECOND) { + done = true; + } + + // truncate seconds + final int seconds = val.get(Calendar.SECOND); + if (!done && (ModifyType.TRUNCATE == modType || seconds < 30)) { + time = time - (seconds * 1000L); + } + if (field == Calendar.MINUTE) { + done = true; + } + + // truncate minutes + final int minutes = val.get(Calendar.MINUTE); + if (!done && (ModifyType.TRUNCATE == modType || minutes < 30)) { + time = time - (minutes * 60000L); + } + + // reset time + if (date.getTime() != time) { + date.setTime(time); + val.setTime(date); + } + // ----------------- Fix for LANG-59 ----------------------- END ---------------- + + boolean roundUp = false; + for (final int[] aField : fields) { + for (final int element : aField) { + if (element == field) { + //This is our field... we stop looping + if (modType == ModifyType.CEILING || modType == ModifyType.ROUND && roundUp) { + if (field == DateUtils.SEMI_MONTH) { + //This is a special case that's hard to generalize + //If the date is 1, we round up to 16, otherwise + // we subtract 15 days and add 1 month + if (val.get(Calendar.DATE) == 1) { + val.add(Calendar.DATE, 15); + } else { + val.add(Calendar.DATE, -15); + val.add(Calendar.MONTH, 1); + } +// ----------------- Fix for LANG-440 ---------------------- START --------------- + } else if (field == Calendar.AM_PM) { + // This is a special case + // If the time is 0, we round up to 12, otherwise + // we subtract 12 hours and add 1 day + if (val.get(Calendar.HOUR_OF_DAY) == 0) { + val.add(Calendar.HOUR_OF_DAY, 12); + } else { + val.add(Calendar.HOUR_OF_DAY, -12); + val.add(Calendar.DATE, 1); + } +// ----------------- Fix for LANG-440 ---------------------- END --------------- + } else { + //We need at add one to this field since the + // last number causes us to round up + val.add(aField[0], 1); + } + } + return; + } + } + //We have various fields that are not easy roundings + int offset = 0; + boolean offsetSet = false; + //These are special types of fields that require different rounding rules + switch (field) { + case DateUtils.SEMI_MONTH: + if (aField[0] == Calendar.DATE) { + //If we're going to drop the DATE field's value, + // we want to do this our own way. + //We need to subtrace 1 since the date has a minimum of 1 + offset = val.get(Calendar.DATE) - 1; + //If we're above 15 days adjustment, that means we're in the + // bottom half of the month and should stay accordingly. + if (offset >= 15) { + offset -= 15; + } + //Record whether we're in the top or bottom half of that range + roundUp = offset > 7; + offsetSet = true; + } + break; + case Calendar.AM_PM: + if (aField[0] == Calendar.HOUR_OF_DAY) { + //If we're going to drop the HOUR field's value, + // we want to do this our own way. + offset = val.get(Calendar.HOUR_OF_DAY); + if (offset >= 12) { + offset -= 12; + } + roundUp = offset >= 6; + offsetSet = true; + } + break; + default: + break; + } + if (!offsetSet) { + final int min = val.getActualMinimum(aField[0]); + final int max = val.getActualMaximum(aField[0]); + //Calculate the offset from the minimum allowed value + offset = val.get(aField[0]) - min; + //Set roundUp if this is more than half way between the minimum and maximum + roundUp = offset > ((max - min) / 2); + } + //We need to remove this field + if (offset != 0) { + val.set(aField[0], val.get(aField[0]) - offset); + } + } + throw new IllegalArgumentException("The field " + field + " is not supported"); + + } + + //----------------------------------------------------------------------- + /** + *Constructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ */
+ public static Iterator iterator(final Object focus, final int rangeStyle) {
+ if (focus == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (focus instanceof Date) {
+ return iterator((Date) focus, rangeStyle);
+ } else if (focus instanceof Calendar) {
+ return iterator((Calendar) focus, rangeStyle);
+ } else {
+ throw new ClassCastException("Could not iterate based on " + focus);
+ }
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of milliseconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all milliseconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MILLISECONDS);
+ }
+
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MILLISECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MILLISECONDS);
+ }
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Gets a Date fragment for any unit.
+ *
+ * @param date the date to work with, not null
+ * @param fragment the Calendar field part of date to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the date
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Date date, final int fragment, final TimeUnit unit) {
+ if(date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar calendar = Calendar.getInstance();
+ calendar.setTime(date);
+ return getFragment(calendar, fragment, unit);
+ }
+
+ /**
+ * Gets a Calendar fragment for any unit.
+ *
+ * @param calendar the calendar to work with, not null
+ * @param fragment the Calendar field part of calendar to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the calendar
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Calendar calendar, final int fragment, final TimeUnit unit) {
+ if(calendar == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+
+ long result = 0;
+
+ final int offset = (unit == TimeUnit.DAYS) ? 0 : 1;
+
+ // Fragments bigger than a day require a breakdown to days
+ switch (fragment) {
+ case Calendar.YEAR:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_YEAR) - offset, TimeUnit.DAYS);
+ break;
+ case Calendar.MONTH:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_MONTH) - offset, TimeUnit.DAYS);
+ break;
+ default:
+ break;
+ }
+
+ switch (fragment) {
+ // Number of days already calculated for these cases
+ case Calendar.YEAR:
+ case Calendar.MONTH:
+
+ // The rest of the valid cases
+ case Calendar.DAY_OF_YEAR:
+ case Calendar.DATE:
+ result += unit.convert(calendar.get(Calendar.HOUR_OF_DAY), TimeUnit.HOURS);
+ //$FALL-THROUGH$
+ case Calendar.HOUR_OF_DAY:
+ result += unit.convert(calendar.get(Calendar.MINUTE), TimeUnit.MINUTES);
+ //$FALL-THROUGH$
+ case Calendar.MINUTE:
+ result += unit.convert(calendar.get(Calendar.SECOND), TimeUnit.SECONDS);
+ //$FALL-THROUGH$
+ case Calendar.SECOND:
+ result += unit.convert(calendar.get(Calendar.MILLISECOND), TimeUnit.MILLISECONDS);
+ break;
+ case Calendar.MILLISECOND: break;//never useful
+ default: throw new IllegalArgumentException("The fragment " + fragment + " is not supported");
+ }
+ return result;
+ }
+
+ /**
+ * Determines if two calendars are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedEquals(Date, Date, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Calendar cal1, final Calendar cal2, final int field) {
+ return truncatedCompareTo(cal1, cal2, field) == 0;
+ }
+
+ /**
+ * Determines if two dates are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Date, int)
+ * @see #truncatedEquals(Calendar, Calendar, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Date date1, final Date date2, final int field) {
+ return truncatedCompareTo(date1, date2, field) == 0;
+ }
+
+ /**
+ * Determines how two calendars compare up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return a negative integer, zero, or a positive integer as the first
+ * calendar is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Calendar cal1, final Calendar cal2, final int field) {
+ final Calendar truncatedCal1 = truncate(cal1, field);
+ final Calendar truncatedCal2 = truncate(cal2, field);
+ return truncatedCal1.compareTo(truncatedCal2);
+ }
+
+ /**
+ * Determines how two dates compare up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from Calendar
+ * @return a negative integer, zero, or a positive integer as the first
+ * date is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Date date1, final Date date2, final int field) {
+ final Date truncatedDate1 = truncate(date1, field);
+ final Date truncatedDate2 = truncate(date2, field);
+ return truncatedDate1.compareTo(truncatedDate2);
+ }
+
+
+ //-----------------------------------------------------------------------
+ /**
+ * Date iterator.
+ */ + static class DateIterator implements Iteratortrue if the iterator has yet to reach the end date
+ */
+ @Override
+ public boolean hasNext() {
+ return spot.before(endFinal);
+ }
+
+ /**
+ * Return the next calendar in the iteration
+ *
+ * @return Object calendar for the next date
+ */
+ @Override
+ public Calendar next() {
+ if (spot.equals(endFinal)) {
+ throw new NoSuchElementException();
+ }
+ spot.add(Calendar.DATE, 1);
+ return (Calendar) spot.clone();
+ }
+
+ /**
+ * Always throws UnsupportedOperationException.
+ *
+ * @throws UnsupportedOperationException
+ * @see java.util.Iterator#remove()
+ */
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+}
diff --git a/Java/commons-lang-DateUtils_748/metadata.json b/Java/commons-lang-DateUtils_748/metadata.json
new file mode 100644
index 000000000..1ea24f640
--- /dev/null
+++ b/Java/commons-lang-DateUtils_748/metadata.json
@@ -0,0 +1,21 @@
+{
+ "language": "java",
+ "id": "commons-lang-DateUtils_748",
+ "buggyPath": ".",
+ "referencePath": null,
+ "buildCommand": "mvn package -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100 -DskipTests=true -DskipITs=true -Dtest=None -DfailIfNoTests=false",
+ "testCommand": "mvn test -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100",
+ "categories": [
+ "safety",
+ "npe"
+ ],
+ "npe": {
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 781,
+ "npe_method": "round",
+ "deref_field": "date",
+ "npe_class": "DateUtils",
+ "repo": "commons-lang",
+ "bug_id": "DateUtils_748"
+ }
+}
diff --git a/Java/commons-lang-DateUtils_748/npe.json b/Java/commons-lang-DateUtils_748/npe.json
new file mode 100644
index 000000000..de54a7200
--- /dev/null
+++ b/Java/commons-lang-DateUtils_748/npe.json
@@ -0,0 +1,7 @@
+{
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 781,
+ "npe_method": "round",
+ "deref_field": "date",
+ "npe_class": "DateUtils"
+}
\ No newline at end of file
diff --git a/Java/commons-lang-DateUtils_785/Dockerfile b/Java/commons-lang-DateUtils_785/Dockerfile
new file mode 100644
index 000000000..7b7fbe349
--- /dev/null
+++ b/Java/commons-lang-DateUtils_785/Dockerfile
@@ -0,0 +1,18 @@
+FROM ghcr.io/kupl/starlab-benchmarks/java-base:commons-lang
+
+ENV TZ=Asia/Seoul
+
+COPY ./metadata.json .
+COPY ./npe.json .
+COPY ./buggy.java /tmp/buggy.java
+RUN export BUGGY_PATH=$(cat metadata.json | jq -r ".npe.filepath") \
+ && export BUGGY_LINE=$(cat metadata.json | jq -r ".npe.line") \
+ && export BUGGY_MTHD=$(cat metadata.json | jq -r ".npe.npe_method") \
+ && mv /tmp/buggy.java $BUGGY_PATH \
+ && echo "[{\"filepath\": \"$BUGGY_PATH\", \"line\": $BUGGY_LINE, \"method_name\": \"$BUGGY_MTHD\"}]" | jq . > traces.json
+
+RUN git init . && git add -A
+
+RUN $(cat metadata.json | jq -r ".buildCommand")
+
+RUN $(cat metadata.json | jq -r ".testCommand"); if [ $? -eq 0 ]; then exit 1; fi
diff --git a/Java/commons-lang-DateUtils_785/buggy.java b/Java/commons-lang-DateUtils_785/buggy.java
new file mode 100644
index 000000000..28dc71c95
--- /dev/null
+++ b/Java/commons-lang-DateUtils_785/buggy.java
@@ -0,0 +1,1888 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3.time;
+
+import java.text.ParseException;
+import java.text.ParsePosition;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.Iterator;
+import java.util.Locale;
+import java.util.NoSuchElementException;
+import java.util.TimeZone;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * A suite of utilities surrounding the use of the + * {@link java.util.Calendar} and {@link java.util.Date} object.
+ * + *DateUtils contains a lot of common methods considering manipulations + * of Dates or Calendars. Some methods require some extra explanation. + * The truncate, ceiling and round methods could be considered the Math.floor(), + * Math.ceil() or Math.round versions for dates + * This way date-fields will be ignored in bottom-up order. + * As a complement to these methods we've introduced some fragment-methods. + * With these methods the Date-fields will be ignored in top-down order. + * Since a date without a year is not a valid date, you have to decide in what + * kind of date-field you want your result, for instance milliseconds or days. + *
+ *+ * Several methods are provided for adding to {@code Date} objects, of the form + * {@code addXXX(Date date, int amount)}. It is important to note these methods + * use a {@code Calendar} internally (with default timezone and locale) and may + * be affected by changes to daylight saving time (DST). + *
+ * + * @since 2.0 + */ +public class DateUtils { + + /** + * Number of milliseconds in a standard second. + * @since 2.1 + */ + public static final long MILLIS_PER_SECOND = 1000; + /** + * Number of milliseconds in a standard minute. + * @since 2.1 + */ + public static final long MILLIS_PER_MINUTE = 60 * MILLIS_PER_SECOND; + /** + * Number of milliseconds in a standard hour. + * @since 2.1 + */ + public static final long MILLIS_PER_HOUR = 60 * MILLIS_PER_MINUTE; + /** + * Number of milliseconds in a standard day. + * @since 2.1 + */ + public static final long MILLIS_PER_DAY = 24 * MILLIS_PER_HOUR; + + /** + * This is half a month, so this represents whether a date is in the top + * or bottom half of the month. + */ + public static final int SEMI_MONTH = 1001; + + private static final int[][] fields = { + {Calendar.MILLISECOND}, + {Calendar.SECOND}, + {Calendar.MINUTE}, + {Calendar.HOUR_OF_DAY, Calendar.HOUR}, + {Calendar.DATE, Calendar.DAY_OF_MONTH, Calendar.AM_PM + /* Calendar.DAY_OF_YEAR, Calendar.DAY_OF_WEEK, Calendar.DAY_OF_WEEK_IN_MONTH */ + }, + {Calendar.MONTH, DateUtils.SEMI_MONTH}, + {Calendar.YEAR}, + {Calendar.ERA}}; + + /** + * A week range, starting on Sunday. + */ + public static final int RANGE_WEEK_SUNDAY = 1; + /** + * A week range, starting on Monday. + */ + public static final int RANGE_WEEK_MONDAY = 2; + /** + * A week range, starting on the day focused. + */ + public static final int RANGE_WEEK_RELATIVE = 3; + /** + * A week range, centered around the day focused. + */ + public static final int RANGE_WEEK_CENTER = 4; + /** + * A month range, the week starting on Sunday. + */ + public static final int RANGE_MONTH_SUNDAY = 5; + /** + * A month range, the week starting on Monday. + */ + public static final int RANGE_MONTH_MONDAY = 6; + + /** + * Calendar modification types. + */ + private enum ModifyType { + /** + * Truncation. + */ + TRUNCATE, + + /** + * Rounding. + */ + ROUND, + + /** + * Ceiling. + */ + CEILING + } + + /** + *{@code DateUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code DateUtils.parseDate(str);}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public DateUtils() { + super(); + } + + //----------------------------------------------------------------------- + /** + *Checks if two date objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar cal1 = Calendar.getInstance();
+ cal1.setTime(date1);
+ final Calendar cal2 = Calendar.getInstance();
+ cal2.setTime(date2);
+ return isSameDay(cal1, cal2);
+ }
+
+ /**
+ * Checks if two calendar objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either calendar isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two date objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return date1.getTime() == date2.getTime();
+ }
+
+ /**
+ * Checks if two calendar objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.getTime().getTime() == cal2.getTime().getTime();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two calendar objects represent the same local time.
+ * + *This method compares the values of the fields of the two objects. + * In addition, both calendars must be the same of the same type.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameLocalTime(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.MILLISECOND) == cal2.get(Calendar.MILLISECOND) &&
+ cal1.get(Calendar.SECOND) == cal2.get(Calendar.SECOND) &&
+ cal1.get(Calendar.MINUTE) == cal2.get(Calendar.MINUTE) &&
+ cal1.get(Calendar.HOUR_OF_DAY) == cal2.get(Calendar.HOUR_OF_DAY) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.getClass() == cal2.getClass();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable (or there were none) + */ + public static Date parseDate(final String str, final String... parsePatterns) throws ParseException { + return parseDate(str, null, parsePatterns); + } + + //----------------------------------------------------------------------- + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDate(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable (or there were none)
+ * @since 3.2
+ */
+ public static Date parseDate(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, true);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @since 2.5 + */ + public static Date parseDateStrictly(final String str, final String... parsePatterns) throws ParseException { + return parseDateStrictly(str, null, parsePatterns); + } + + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale..
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDateStrictly(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable
+ * @since 3.2
+ */
+ public static Date parseDateStrictly(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, false);
+ }
+
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * + * @param str the date to parse, not null + * @param locale the locale to use when interpretting the pattern, can be null in which + * case the default system locale is used + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @param lenient Specify whether or not date/time parsing is to be lenient. + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @see java.util.Calendar#isLenient() + */ + private static Date parseDateWithLeniency( + final String str, final Locale locale, final String[] parsePatterns, final boolean lenient) throws ParseException { + if (str == null || parsePatterns == null) { + throw new IllegalArgumentException("Date and Patterns must not be null"); + } + + final TimeZone tz = TimeZone.getDefault(); + final Locale lcl = locale==null ?Locale.getDefault() : locale; + final ParsePosition pos = new ParsePosition(0); + final Calendar calendar = Calendar.getInstance(tz, lcl); + calendar.setLenient(lenient); + + for (final String parsePattern : parsePatterns) { + FastDateParser fdp = new FastDateParser(parsePattern, tz, lcl); + calendar.clear(); + try { + if (fdp.parse(str, pos, calendar) && pos.getIndex()==str.length()) { + return calendar.getTime(); + } + } + catch(IllegalArgumentException ignore) { + // leniency is preventing calendar from being set + } + pos.setIndex(0); + } + throw new ParseException("Unable to parse the date: " + str, -1); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of years to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addYears(final Date date, final int amount) { + return add(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of months to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMonths(final Date date, final int amount) { + return add(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of weeks to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addWeeks(final Date date, final int amount) { + return add(date, Calendar.WEEK_OF_YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of days to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addDays(final Date date, final int amount) { + return add(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of hours to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addHours(final Date date, final int amount) { + return add(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of minutes to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMinutes(final Date date, final int amount) { + return add(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of seconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addSeconds(final Date date, final int amount) { + return add(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of milliseconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMilliseconds(final Date date, final int amount) { + return add(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the calendar field to add to + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + private static Date add(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + final Calendar c = Calendar.getInstance(); + c.setTime(date); + c.add(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Sets the years field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setYears(final Date date, final int amount) { + return set(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the months field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMonths(final Date date, final int amount) { + return set(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the day of month field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setDays(final Date date, final int amount) { + return set(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the hours field to a date returning a new object. Hours range + * from 0-23. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setHours(final Date date, final int amount) { + return set(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the minute field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMinutes(final Date date, final int amount) { + return set(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the seconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setSeconds(final Date date, final int amount) { + return set(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the milliseconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMilliseconds(final Date date, final int amount) { + return set(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the specified field to a date returning a new object. + * This does not use a lenient calendar. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the {@code Calendar} field to set the amount to + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + private static Date set(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + // getInstance() returns a new object, so this method is thread safe. + final Calendar c = Calendar.getInstance(); + c.setLenient(false); + c.setTime(date); + c.set(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} into a {@code Calendar}. + * + * @param date the date to convert to a Calendar + * @return the created Calendar + * @throws NullPointerException if null is passed in + * @since 3.0 + */ + public static Calendar toCalendar(final Date date) { + final Calendar c = Calendar.getInstance(); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} of a given {@code TimeZone} into a {@code Calendar} + * @param date the date to convert to a Calendar + * @param tz the time zone of the @{code date} + * @return the created Calendar + * @throws NullPointerException if {@code date} or {@code tz} is null + */ + public static Calendar toCalendar(final Date date, final TimeZone tz) { + final Calendar c = Calendar.getInstance(tz); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar round(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar rounded = (Calendar) date.clone();
+ modify(rounded, field, ModifyType.ROUND);
+ return rounded;
+ }
+
+ /**
+ * Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+/**
+ * Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException
+ * if the date is null
+ * @throws ClassCastException
+ * if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException
+ * if the year is over 280 million
+ */
+public static java.util.Date round(final java.lang.Object date, final int field) {
+ {
+ if (/* NPEX_NULL_EXP */
+ date instanceof java.util.Date) {
+ return org.apache.commons.lang3.time.DateUtils.round(((java.util.Date) (date)), field);
+ } else if (date instanceof java.util.Calendar) {
+ return org.apache.commons.lang3.time.DateUtils.round(((java.util.Calendar) (date)), field).getTime();
+ } else {
+ throw new java.lang.ClassCastException("Could not round " + date);
+ }
+ }
+}
+
+ //-----------------------------------------------------------------------
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.TRUNCATE);
+ return gval.getTime();
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar truncate(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar truncated = (Calendar) date.clone();
+ modify(truncated, field, ModifyType.TRUNCATE);
+ return truncated;
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return truncate((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return truncate((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not truncate " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.CEILING);
+ return gval.getTime();
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Calendar ceiling(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar ceiled = (Calendar) date.clone();
+ modify(ceiled, field, ModifyType.CEILING);
+ return ceiled;
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return ceiling((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return ceiling((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not find ceiling of for type: " + date.getClass());
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Internal calculation method.
+ * + * @param val the calendar, not null + * @param field the field constant + * @param modType type to truncate, round or ceiling + * @throws ArithmeticException if the year is over 280 million + */ + private static void modify(final Calendar val, final int field, final ModifyType modType) { + if (val.get(Calendar.YEAR) > 280000000) { + throw new ArithmeticException("Calendar value too large for accurate calculations"); + } + + if (field == Calendar.MILLISECOND) { + return; + } + + // ----------------- Fix for LANG-59 ---------------------- START --------------- + // see http://issues.apache.org/jira/browse/LANG-59 + // + // Manually truncate milliseconds, seconds and minutes, rather than using + // Calendar methods. + + final Date date = val.getTime(); + long time = date.getTime(); + boolean done = false; + + // truncate milliseconds + final int millisecs = val.get(Calendar.MILLISECOND); + if (ModifyType.TRUNCATE == modType || millisecs < 500) { + time = time - millisecs; + } + if (field == Calendar.SECOND) { + done = true; + } + + // truncate seconds + final int seconds = val.get(Calendar.SECOND); + if (!done && (ModifyType.TRUNCATE == modType || seconds < 30)) { + time = time - (seconds * 1000L); + } + if (field == Calendar.MINUTE) { + done = true; + } + + // truncate minutes + final int minutes = val.get(Calendar.MINUTE); + if (!done && (ModifyType.TRUNCATE == modType || minutes < 30)) { + time = time - (minutes * 60000L); + } + + // reset time + if (date.getTime() != time) { + date.setTime(time); + val.setTime(date); + } + // ----------------- Fix for LANG-59 ----------------------- END ---------------- + + boolean roundUp = false; + for (final int[] aField : fields) { + for (final int element : aField) { + if (element == field) { + //This is our field... we stop looping + if (modType == ModifyType.CEILING || modType == ModifyType.ROUND && roundUp) { + if (field == DateUtils.SEMI_MONTH) { + //This is a special case that's hard to generalize + //If the date is 1, we round up to 16, otherwise + // we subtract 15 days and add 1 month + if (val.get(Calendar.DATE) == 1) { + val.add(Calendar.DATE, 15); + } else { + val.add(Calendar.DATE, -15); + val.add(Calendar.MONTH, 1); + } +// ----------------- Fix for LANG-440 ---------------------- START --------------- + } else if (field == Calendar.AM_PM) { + // This is a special case + // If the time is 0, we round up to 12, otherwise + // we subtract 12 hours and add 1 day + if (val.get(Calendar.HOUR_OF_DAY) == 0) { + val.add(Calendar.HOUR_OF_DAY, 12); + } else { + val.add(Calendar.HOUR_OF_DAY, -12); + val.add(Calendar.DATE, 1); + } +// ----------------- Fix for LANG-440 ---------------------- END --------------- + } else { + //We need at add one to this field since the + // last number causes us to round up + val.add(aField[0], 1); + } + } + return; + } + } + //We have various fields that are not easy roundings + int offset = 0; + boolean offsetSet = false; + //These are special types of fields that require different rounding rules + switch (field) { + case DateUtils.SEMI_MONTH: + if (aField[0] == Calendar.DATE) { + //If we're going to drop the DATE field's value, + // we want to do this our own way. + //We need to subtrace 1 since the date has a minimum of 1 + offset = val.get(Calendar.DATE) - 1; + //If we're above 15 days adjustment, that means we're in the + // bottom half of the month and should stay accordingly. + if (offset >= 15) { + offset -= 15; + } + //Record whether we're in the top or bottom half of that range + roundUp = offset > 7; + offsetSet = true; + } + break; + case Calendar.AM_PM: + if (aField[0] == Calendar.HOUR_OF_DAY) { + //If we're going to drop the HOUR field's value, + // we want to do this our own way. + offset = val.get(Calendar.HOUR_OF_DAY); + if (offset >= 12) { + offset -= 12; + } + roundUp = offset >= 6; + offsetSet = true; + } + break; + default: + break; + } + if (!offsetSet) { + final int min = val.getActualMinimum(aField[0]); + final int max = val.getActualMaximum(aField[0]); + //Calculate the offset from the minimum allowed value + offset = val.get(aField[0]) - min; + //Set roundUp if this is more than half way between the minimum and maximum + roundUp = offset > ((max - min) / 2); + } + //We need to remove this field + if (offset != 0) { + val.set(aField[0], val.get(aField[0]) - offset); + } + } + throw new IllegalArgumentException("The field " + field + " is not supported"); + + } + + //----------------------------------------------------------------------- + /** + *Constructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ */
+ public static Iterator iterator(final Object focus, final int rangeStyle) {
+ if (focus == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (focus instanceof Date) {
+ return iterator((Date) focus, rangeStyle);
+ } else if (focus instanceof Calendar) {
+ return iterator((Calendar) focus, rangeStyle);
+ } else {
+ throw new ClassCastException("Could not iterate based on " + focus);
+ }
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of milliseconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all milliseconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MILLISECONDS);
+ }
+
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MILLISECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MILLISECONDS);
+ }
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Gets a Date fragment for any unit.
+ *
+ * @param date the date to work with, not null
+ * @param fragment the Calendar field part of date to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the date
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Date date, final int fragment, final TimeUnit unit) {
+ if(date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar calendar = Calendar.getInstance();
+ calendar.setTime(date);
+ return getFragment(calendar, fragment, unit);
+ }
+
+ /**
+ * Gets a Calendar fragment for any unit.
+ *
+ * @param calendar the calendar to work with, not null
+ * @param fragment the Calendar field part of calendar to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the calendar
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Calendar calendar, final int fragment, final TimeUnit unit) {
+ if(calendar == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+
+ long result = 0;
+
+ final int offset = (unit == TimeUnit.DAYS) ? 0 : 1;
+
+ // Fragments bigger than a day require a breakdown to days
+ switch (fragment) {
+ case Calendar.YEAR:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_YEAR) - offset, TimeUnit.DAYS);
+ break;
+ case Calendar.MONTH:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_MONTH) - offset, TimeUnit.DAYS);
+ break;
+ default:
+ break;
+ }
+
+ switch (fragment) {
+ // Number of days already calculated for these cases
+ case Calendar.YEAR:
+ case Calendar.MONTH:
+
+ // The rest of the valid cases
+ case Calendar.DAY_OF_YEAR:
+ case Calendar.DATE:
+ result += unit.convert(calendar.get(Calendar.HOUR_OF_DAY), TimeUnit.HOURS);
+ //$FALL-THROUGH$
+ case Calendar.HOUR_OF_DAY:
+ result += unit.convert(calendar.get(Calendar.MINUTE), TimeUnit.MINUTES);
+ //$FALL-THROUGH$
+ case Calendar.MINUTE:
+ result += unit.convert(calendar.get(Calendar.SECOND), TimeUnit.SECONDS);
+ //$FALL-THROUGH$
+ case Calendar.SECOND:
+ result += unit.convert(calendar.get(Calendar.MILLISECOND), TimeUnit.MILLISECONDS);
+ break;
+ case Calendar.MILLISECOND: break;//never useful
+ default: throw new IllegalArgumentException("The fragment " + fragment + " is not supported");
+ }
+ return result;
+ }
+
+ /**
+ * Determines if two calendars are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedEquals(Date, Date, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Calendar cal1, final Calendar cal2, final int field) {
+ return truncatedCompareTo(cal1, cal2, field) == 0;
+ }
+
+ /**
+ * Determines if two dates are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Date, int)
+ * @see #truncatedEquals(Calendar, Calendar, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Date date1, final Date date2, final int field) {
+ return truncatedCompareTo(date1, date2, field) == 0;
+ }
+
+ /**
+ * Determines how two calendars compare up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return a negative integer, zero, or a positive integer as the first
+ * calendar is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Calendar cal1, final Calendar cal2, final int field) {
+ final Calendar truncatedCal1 = truncate(cal1, field);
+ final Calendar truncatedCal2 = truncate(cal2, field);
+ return truncatedCal1.compareTo(truncatedCal2);
+ }
+
+ /**
+ * Determines how two dates compare up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from Calendar
+ * @return a negative integer, zero, or a positive integer as the first
+ * date is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Date date1, final Date date2, final int field) {
+ final Date truncatedDate1 = truncate(date1, field);
+ final Date truncatedDate2 = truncate(date2, field);
+ return truncatedDate1.compareTo(truncatedDate2);
+ }
+
+
+ //-----------------------------------------------------------------------
+ /**
+ * Date iterator.
+ */ + static class DateIterator implements Iteratortrue if the iterator has yet to reach the end date
+ */
+ @Override
+ public boolean hasNext() {
+ return spot.before(endFinal);
+ }
+
+ /**
+ * Return the next calendar in the iteration
+ *
+ * @return Object calendar for the next date
+ */
+ @Override
+ public Calendar next() {
+ if (spot.equals(endFinal)) {
+ throw new NoSuchElementException();
+ }
+ spot.add(Calendar.DATE, 1);
+ return (Calendar) spot.clone();
+ }
+
+ /**
+ * Always throws UnsupportedOperationException.
+ *
+ * @throws UnsupportedOperationException
+ * @see java.util.Iterator#remove()
+ */
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+}
diff --git a/Java/commons-lang-DateUtils_785/metadata.json b/Java/commons-lang-DateUtils_785/metadata.json
new file mode 100644
index 000000000..f70f984b2
--- /dev/null
+++ b/Java/commons-lang-DateUtils_785/metadata.json
@@ -0,0 +1,21 @@
+{
+ "language": "java",
+ "id": "commons-lang-DateUtils_785",
+ "buggyPath": ".",
+ "referencePath": null,
+ "buildCommand": "mvn package -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100 -DskipTests=true -DskipITs=true -Dtest=None -DfailIfNoTests=false",
+ "testCommand": "mvn test -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100",
+ "categories": [
+ "safety",
+ "npe"
+ ],
+ "npe": {
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 820,
+ "npe_method": "round",
+ "deref_field": "date",
+ "npe_class": "DateUtils",
+ "repo": "commons-lang",
+ "bug_id": "DateUtils_785"
+ }
+}
diff --git a/Java/commons-lang-DateUtils_785/npe.json b/Java/commons-lang-DateUtils_785/npe.json
new file mode 100644
index 000000000..cbeb68650
--- /dev/null
+++ b/Java/commons-lang-DateUtils_785/npe.json
@@ -0,0 +1,7 @@
+{
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 820,
+ "npe_method": "round",
+ "deref_field": "date",
+ "npe_class": "DateUtils"
+}
\ No newline at end of file
diff --git a/Java/commons-lang-DateUtils_814/Dockerfile b/Java/commons-lang-DateUtils_814/Dockerfile
new file mode 100644
index 000000000..7b7fbe349
--- /dev/null
+++ b/Java/commons-lang-DateUtils_814/Dockerfile
@@ -0,0 +1,18 @@
+FROM ghcr.io/kupl/starlab-benchmarks/java-base:commons-lang
+
+ENV TZ=Asia/Seoul
+
+COPY ./metadata.json .
+COPY ./npe.json .
+COPY ./buggy.java /tmp/buggy.java
+RUN export BUGGY_PATH=$(cat metadata.json | jq -r ".npe.filepath") \
+ && export BUGGY_LINE=$(cat metadata.json | jq -r ".npe.line") \
+ && export BUGGY_MTHD=$(cat metadata.json | jq -r ".npe.npe_method") \
+ && mv /tmp/buggy.java $BUGGY_PATH \
+ && echo "[{\"filepath\": \"$BUGGY_PATH\", \"line\": $BUGGY_LINE, \"method_name\": \"$BUGGY_MTHD\"}]" | jq . > traces.json
+
+RUN git init . && git add -A
+
+RUN $(cat metadata.json | jq -r ".buildCommand")
+
+RUN $(cat metadata.json | jq -r ".testCommand"); if [ $? -eq 0 ]; then exit 1; fi
diff --git a/Java/commons-lang-DateUtils_814/buggy.java b/Java/commons-lang-DateUtils_814/buggy.java
new file mode 100644
index 000000000..72fad20ce
--- /dev/null
+++ b/Java/commons-lang-DateUtils_814/buggy.java
@@ -0,0 +1,1875 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3.time;
+
+import java.text.ParseException;
+import java.text.ParsePosition;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.Iterator;
+import java.util.Locale;
+import java.util.NoSuchElementException;
+import java.util.TimeZone;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * A suite of utilities surrounding the use of the + * {@link java.util.Calendar} and {@link java.util.Date} object.
+ * + *DateUtils contains a lot of common methods considering manipulations + * of Dates or Calendars. Some methods require some extra explanation. + * The truncate, ceiling and round methods could be considered the Math.floor(), + * Math.ceil() or Math.round versions for dates + * This way date-fields will be ignored in bottom-up order. + * As a complement to these methods we've introduced some fragment-methods. + * With these methods the Date-fields will be ignored in top-down order. + * Since a date without a year is not a valid date, you have to decide in what + * kind of date-field you want your result, for instance milliseconds or days. + *
+ *+ * Several methods are provided for adding to {@code Date} objects, of the form + * {@code addXXX(Date date, int amount)}. It is important to note these methods + * use a {@code Calendar} internally (with default timezone and locale) and may + * be affected by changes to daylight saving time (DST). + *
+ * + * @since 2.0 + */ +public class DateUtils { + + /** + * Number of milliseconds in a standard second. + * @since 2.1 + */ + public static final long MILLIS_PER_SECOND = 1000; + /** + * Number of milliseconds in a standard minute. + * @since 2.1 + */ + public static final long MILLIS_PER_MINUTE = 60 * MILLIS_PER_SECOND; + /** + * Number of milliseconds in a standard hour. + * @since 2.1 + */ + public static final long MILLIS_PER_HOUR = 60 * MILLIS_PER_MINUTE; + /** + * Number of milliseconds in a standard day. + * @since 2.1 + */ + public static final long MILLIS_PER_DAY = 24 * MILLIS_PER_HOUR; + + /** + * This is half a month, so this represents whether a date is in the top + * or bottom half of the month. + */ + public static final int SEMI_MONTH = 1001; + + private static final int[][] fields = { + {Calendar.MILLISECOND}, + {Calendar.SECOND}, + {Calendar.MINUTE}, + {Calendar.HOUR_OF_DAY, Calendar.HOUR}, + {Calendar.DATE, Calendar.DAY_OF_MONTH, Calendar.AM_PM + /* Calendar.DAY_OF_YEAR, Calendar.DAY_OF_WEEK, Calendar.DAY_OF_WEEK_IN_MONTH */ + }, + {Calendar.MONTH, DateUtils.SEMI_MONTH}, + {Calendar.YEAR}, + {Calendar.ERA}}; + + /** + * A week range, starting on Sunday. + */ + public static final int RANGE_WEEK_SUNDAY = 1; + /** + * A week range, starting on Monday. + */ + public static final int RANGE_WEEK_MONDAY = 2; + /** + * A week range, starting on the day focused. + */ + public static final int RANGE_WEEK_RELATIVE = 3; + /** + * A week range, centered around the day focused. + */ + public static final int RANGE_WEEK_CENTER = 4; + /** + * A month range, the week starting on Sunday. + */ + public static final int RANGE_MONTH_SUNDAY = 5; + /** + * A month range, the week starting on Monday. + */ + public static final int RANGE_MONTH_MONDAY = 6; + + /** + * Calendar modification types. + */ + private enum ModifyType { + /** + * Truncation. + */ + TRUNCATE, + + /** + * Rounding. + */ + ROUND, + + /** + * Ceiling. + */ + CEILING + } + + /** + *{@code DateUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code DateUtils.parseDate(str);}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public DateUtils() { + super(); + } + + //----------------------------------------------------------------------- + /** + *Checks if two date objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar cal1 = Calendar.getInstance();
+ cal1.setTime(date1);
+ final Calendar cal2 = Calendar.getInstance();
+ cal2.setTime(date2);
+ return isSameDay(cal1, cal2);
+ }
+
+ /**
+ * Checks if two calendar objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either calendar isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two date objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return date1.getTime() == date2.getTime();
+ }
+
+ /**
+ * Checks if two calendar objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.getTime().getTime() == cal2.getTime().getTime();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two calendar objects represent the same local time.
+ * + *This method compares the values of the fields of the two objects. + * In addition, both calendars must be the same of the same type.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameLocalTime(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.MILLISECOND) == cal2.get(Calendar.MILLISECOND) &&
+ cal1.get(Calendar.SECOND) == cal2.get(Calendar.SECOND) &&
+ cal1.get(Calendar.MINUTE) == cal2.get(Calendar.MINUTE) &&
+ cal1.get(Calendar.HOUR_OF_DAY) == cal2.get(Calendar.HOUR_OF_DAY) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.getClass() == cal2.getClass();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable (or there were none) + */ + public static Date parseDate(final String str, final String... parsePatterns) throws ParseException { + return parseDate(str, null, parsePatterns); + } + + //----------------------------------------------------------------------- + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDate(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable (or there were none)
+ * @since 3.2
+ */
+ public static Date parseDate(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, true);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @since 2.5 + */ + public static Date parseDateStrictly(final String str, final String... parsePatterns) throws ParseException { + return parseDateStrictly(str, null, parsePatterns); + } + + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale..
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDateStrictly(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable
+ * @since 3.2
+ */
+ public static Date parseDateStrictly(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, false);
+ }
+
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * + * @param str the date to parse, not null + * @param locale the locale to use when interpretting the pattern, can be null in which + * case the default system locale is used + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @param lenient Specify whether or not date/time parsing is to be lenient. + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @see java.util.Calendar#isLenient() + */ + private static Date parseDateWithLeniency( + final String str, final Locale locale, final String[] parsePatterns, final boolean lenient) throws ParseException { + if (str == null || parsePatterns == null) { + throw new IllegalArgumentException("Date and Patterns must not be null"); + } + + final TimeZone tz = TimeZone.getDefault(); + final Locale lcl = locale==null ?Locale.getDefault() : locale; + final ParsePosition pos = new ParsePosition(0); + final Calendar calendar = Calendar.getInstance(tz, lcl); + calendar.setLenient(lenient); + + for (final String parsePattern : parsePatterns) { + FastDateParser fdp = new FastDateParser(parsePattern, tz, lcl); + calendar.clear(); + try { + if (fdp.parse(str, pos, calendar) && pos.getIndex()==str.length()) { + return calendar.getTime(); + } + } + catch(IllegalArgumentException ignore) { + // leniency is preventing calendar from being set + } + pos.setIndex(0); + } + throw new ParseException("Unable to parse the date: " + str, -1); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of years to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addYears(final Date date, final int amount) { + return add(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of months to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMonths(final Date date, final int amount) { + return add(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of weeks to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addWeeks(final Date date, final int amount) { + return add(date, Calendar.WEEK_OF_YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of days to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addDays(final Date date, final int amount) { + return add(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of hours to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addHours(final Date date, final int amount) { + return add(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of minutes to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMinutes(final Date date, final int amount) { + return add(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of seconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addSeconds(final Date date, final int amount) { + return add(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of milliseconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMilliseconds(final Date date, final int amount) { + return add(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the calendar field to add to + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + private static Date add(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + final Calendar c = Calendar.getInstance(); + c.setTime(date); + c.add(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Sets the years field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setYears(final Date date, final int amount) { + return set(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the months field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMonths(final Date date, final int amount) { + return set(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the day of month field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setDays(final Date date, final int amount) { + return set(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the hours field to a date returning a new object. Hours range + * from 0-23. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setHours(final Date date, final int amount) { + return set(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the minute field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMinutes(final Date date, final int amount) { + return set(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the seconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setSeconds(final Date date, final int amount) { + return set(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the milliseconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMilliseconds(final Date date, final int amount) { + return set(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the specified field to a date returning a new object. + * This does not use a lenient calendar. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the {@code Calendar} field to set the amount to + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + private static Date set(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + // getInstance() returns a new object, so this method is thread safe. + final Calendar c = Calendar.getInstance(); + c.setLenient(false); + c.setTime(date); + c.set(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} into a {@code Calendar}. + * + * @param date the date to convert to a Calendar + * @return the created Calendar + * @throws NullPointerException if null is passed in + * @since 3.0 + */ + public static Calendar toCalendar(final Date date) { + final Calendar c = Calendar.getInstance(); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} of a given {@code TimeZone} into a {@code Calendar} + * @param date the date to convert to a Calendar + * @param tz the time zone of the @{code date} + * @return the created Calendar + * @throws NullPointerException if {@code date} or {@code tz} is null + */ + public static Calendar toCalendar(final Date date, final TimeZone tz) { + final Calendar c = Calendar.getInstance(tz); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar round(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar rounded = (Calendar) date.clone();
+ modify(rounded, field, ModifyType.ROUND);
+ return rounded;
+ }
+
+ /**
+ * Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date round(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return round((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return round((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not round " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+// -----------------------------------------------------------------------
+/**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date + * the date to work with, not null + * @param field + * the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException
+ * if the date is null
+ * @throws ArithmeticException
+ * if the year is over 280 million
+ */
+public static java.util.Date truncate(final java.util.Date date, final int field) {
+ {
+ final java.util.Calendar gval = java.util.Calendar.getInstance();
+ gval.setTime(/* NPEX_NULL_EXP */
+ date);
+ org.apache.commons.lang3.time.DateUtils.modify(gval, field, org.apache.commons.lang3.time.DateUtils.ModifyType.TRUNCATE);
+ return gval.getTime();
+ }
+}
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar truncate(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar truncated = (Calendar) date.clone();
+ modify(truncated, field, ModifyType.TRUNCATE);
+ return truncated;
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return truncate((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return truncate((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not truncate " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.CEILING);
+ return gval.getTime();
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Calendar ceiling(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar ceiled = (Calendar) date.clone();
+ modify(ceiled, field, ModifyType.CEILING);
+ return ceiled;
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return ceiling((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return ceiling((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not find ceiling of for type: " + date.getClass());
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Internal calculation method.
+ * + * @param val the calendar, not null + * @param field the field constant + * @param modType type to truncate, round or ceiling + * @throws ArithmeticException if the year is over 280 million + */ + private static void modify(final Calendar val, final int field, final ModifyType modType) { + if (val.get(Calendar.YEAR) > 280000000) { + throw new ArithmeticException("Calendar value too large for accurate calculations"); + } + + if (field == Calendar.MILLISECOND) { + return; + } + + // ----------------- Fix for LANG-59 ---------------------- START --------------- + // see http://issues.apache.org/jira/browse/LANG-59 + // + // Manually truncate milliseconds, seconds and minutes, rather than using + // Calendar methods. + + final Date date = val.getTime(); + long time = date.getTime(); + boolean done = false; + + // truncate milliseconds + final int millisecs = val.get(Calendar.MILLISECOND); + if (ModifyType.TRUNCATE == modType || millisecs < 500) { + time = time - millisecs; + } + if (field == Calendar.SECOND) { + done = true; + } + + // truncate seconds + final int seconds = val.get(Calendar.SECOND); + if (!done && (ModifyType.TRUNCATE == modType || seconds < 30)) { + time = time - (seconds * 1000L); + } + if (field == Calendar.MINUTE) { + done = true; + } + + // truncate minutes + final int minutes = val.get(Calendar.MINUTE); + if (!done && (ModifyType.TRUNCATE == modType || minutes < 30)) { + time = time - (minutes * 60000L); + } + + // reset time + if (date.getTime() != time) { + date.setTime(time); + val.setTime(date); + } + // ----------------- Fix for LANG-59 ----------------------- END ---------------- + + boolean roundUp = false; + for (final int[] aField : fields) { + for (final int element : aField) { + if (element == field) { + //This is our field... we stop looping + if (modType == ModifyType.CEILING || modType == ModifyType.ROUND && roundUp) { + if (field == DateUtils.SEMI_MONTH) { + //This is a special case that's hard to generalize + //If the date is 1, we round up to 16, otherwise + // we subtract 15 days and add 1 month + if (val.get(Calendar.DATE) == 1) { + val.add(Calendar.DATE, 15); + } else { + val.add(Calendar.DATE, -15); + val.add(Calendar.MONTH, 1); + } +// ----------------- Fix for LANG-440 ---------------------- START --------------- + } else if (field == Calendar.AM_PM) { + // This is a special case + // If the time is 0, we round up to 12, otherwise + // we subtract 12 hours and add 1 day + if (val.get(Calendar.HOUR_OF_DAY) == 0) { + val.add(Calendar.HOUR_OF_DAY, 12); + } else { + val.add(Calendar.HOUR_OF_DAY, -12); + val.add(Calendar.DATE, 1); + } +// ----------------- Fix for LANG-440 ---------------------- END --------------- + } else { + //We need at add one to this field since the + // last number causes us to round up + val.add(aField[0], 1); + } + } + return; + } + } + //We have various fields that are not easy roundings + int offset = 0; + boolean offsetSet = false; + //These are special types of fields that require different rounding rules + switch (field) { + case DateUtils.SEMI_MONTH: + if (aField[0] == Calendar.DATE) { + //If we're going to drop the DATE field's value, + // we want to do this our own way. + //We need to subtrace 1 since the date has a minimum of 1 + offset = val.get(Calendar.DATE) - 1; + //If we're above 15 days adjustment, that means we're in the + // bottom half of the month and should stay accordingly. + if (offset >= 15) { + offset -= 15; + } + //Record whether we're in the top or bottom half of that range + roundUp = offset > 7; + offsetSet = true; + } + break; + case Calendar.AM_PM: + if (aField[0] == Calendar.HOUR_OF_DAY) { + //If we're going to drop the HOUR field's value, + // we want to do this our own way. + offset = val.get(Calendar.HOUR_OF_DAY); + if (offset >= 12) { + offset -= 12; + } + roundUp = offset >= 6; + offsetSet = true; + } + break; + default: + break; + } + if (!offsetSet) { + final int min = val.getActualMinimum(aField[0]); + final int max = val.getActualMaximum(aField[0]); + //Calculate the offset from the minimum allowed value + offset = val.get(aField[0]) - min; + //Set roundUp if this is more than half way between the minimum and maximum + roundUp = offset > ((max - min) / 2); + } + //We need to remove this field + if (offset != 0) { + val.set(aField[0], val.get(aField[0]) - offset); + } + } + throw new IllegalArgumentException("The field " + field + " is not supported"); + + } + + //----------------------------------------------------------------------- + /** + *Constructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ */
+ public static Iterator iterator(final Object focus, final int rangeStyle) {
+ if (focus == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (focus instanceof Date) {
+ return iterator((Date) focus, rangeStyle);
+ } else if (focus instanceof Calendar) {
+ return iterator((Calendar) focus, rangeStyle);
+ } else {
+ throw new ClassCastException("Could not iterate based on " + focus);
+ }
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of milliseconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all milliseconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MILLISECONDS);
+ }
+
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MILLISECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MILLISECONDS);
+ }
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Gets a Date fragment for any unit.
+ *
+ * @param date the date to work with, not null
+ * @param fragment the Calendar field part of date to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the date
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Date date, final int fragment, final TimeUnit unit) {
+ if(date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar calendar = Calendar.getInstance();
+ calendar.setTime(date);
+ return getFragment(calendar, fragment, unit);
+ }
+
+ /**
+ * Gets a Calendar fragment for any unit.
+ *
+ * @param calendar the calendar to work with, not null
+ * @param fragment the Calendar field part of calendar to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the calendar
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Calendar calendar, final int fragment, final TimeUnit unit) {
+ if(calendar == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+
+ long result = 0;
+
+ final int offset = (unit == TimeUnit.DAYS) ? 0 : 1;
+
+ // Fragments bigger than a day require a breakdown to days
+ switch (fragment) {
+ case Calendar.YEAR:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_YEAR) - offset, TimeUnit.DAYS);
+ break;
+ case Calendar.MONTH:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_MONTH) - offset, TimeUnit.DAYS);
+ break;
+ default:
+ break;
+ }
+
+ switch (fragment) {
+ // Number of days already calculated for these cases
+ case Calendar.YEAR:
+ case Calendar.MONTH:
+
+ // The rest of the valid cases
+ case Calendar.DAY_OF_YEAR:
+ case Calendar.DATE:
+ result += unit.convert(calendar.get(Calendar.HOUR_OF_DAY), TimeUnit.HOURS);
+ //$FALL-THROUGH$
+ case Calendar.HOUR_OF_DAY:
+ result += unit.convert(calendar.get(Calendar.MINUTE), TimeUnit.MINUTES);
+ //$FALL-THROUGH$
+ case Calendar.MINUTE:
+ result += unit.convert(calendar.get(Calendar.SECOND), TimeUnit.SECONDS);
+ //$FALL-THROUGH$
+ case Calendar.SECOND:
+ result += unit.convert(calendar.get(Calendar.MILLISECOND), TimeUnit.MILLISECONDS);
+ break;
+ case Calendar.MILLISECOND: break;//never useful
+ default: throw new IllegalArgumentException("The fragment " + fragment + " is not supported");
+ }
+ return result;
+ }
+
+ /**
+ * Determines if two calendars are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedEquals(Date, Date, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Calendar cal1, final Calendar cal2, final int field) {
+ return truncatedCompareTo(cal1, cal2, field) == 0;
+ }
+
+ /**
+ * Determines if two dates are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Date, int)
+ * @see #truncatedEquals(Calendar, Calendar, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Date date1, final Date date2, final int field) {
+ return truncatedCompareTo(date1, date2, field) == 0;
+ }
+
+ /**
+ * Determines how two calendars compare up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return a negative integer, zero, or a positive integer as the first
+ * calendar is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Calendar cal1, final Calendar cal2, final int field) {
+ final Calendar truncatedCal1 = truncate(cal1, field);
+ final Calendar truncatedCal2 = truncate(cal2, field);
+ return truncatedCal1.compareTo(truncatedCal2);
+ }
+
+ /**
+ * Determines how two dates compare up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from Calendar
+ * @return a negative integer, zero, or a positive integer as the first
+ * date is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Date date1, final Date date2, final int field) {
+ final Date truncatedDate1 = truncate(date1, field);
+ final Date truncatedDate2 = truncate(date2, field);
+ return truncatedDate1.compareTo(truncatedDate2);
+ }
+
+
+ //-----------------------------------------------------------------------
+ /**
+ * Date iterator.
+ */ + static class DateIterator implements Iteratortrue if the iterator has yet to reach the end date
+ */
+ @Override
+ public boolean hasNext() {
+ return spot.before(endFinal);
+ }
+
+ /**
+ * Return the next calendar in the iteration
+ *
+ * @return Object calendar for the next date
+ */
+ @Override
+ public Calendar next() {
+ if (spot.equals(endFinal)) {
+ throw new NoSuchElementException();
+ }
+ spot.add(Calendar.DATE, 1);
+ return (Calendar) spot.clone();
+ }
+
+ /**
+ * Always throws UnsupportedOperationException.
+ *
+ * @throws UnsupportedOperationException
+ * @see java.util.Iterator#remove()
+ */
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+}
diff --git a/Java/commons-lang-DateUtils_814/metadata.json b/Java/commons-lang-DateUtils_814/metadata.json
new file mode 100644
index 000000000..83e414e41
--- /dev/null
+++ b/Java/commons-lang-DateUtils_814/metadata.json
@@ -0,0 +1,21 @@
+{
+ "language": "java",
+ "id": "commons-lang-DateUtils_814",
+ "buggyPath": ".",
+ "referencePath": null,
+ "buildCommand": "mvn package -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100 -DskipTests=true -DskipITs=true -Dtest=None -DfailIfNoTests=false",
+ "testCommand": "mvn test -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100",
+ "categories": [
+ "safety",
+ "npe"
+ ],
+ "npe": {
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 837,
+ "npe_method": "truncate",
+ "deref_field": "date",
+ "npe_class": "DateUtils",
+ "repo": "commons-lang",
+ "bug_id": "DateUtils_814"
+ }
+}
diff --git a/Java/commons-lang-DateUtils_814/npe.json b/Java/commons-lang-DateUtils_814/npe.json
new file mode 100644
index 000000000..d5677a476
--- /dev/null
+++ b/Java/commons-lang-DateUtils_814/npe.json
@@ -0,0 +1,7 @@
+{
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 837,
+ "npe_method": "truncate",
+ "deref_field": "date",
+ "npe_class": "DateUtils"
+}
\ No newline at end of file
diff --git a/Java/commons-lang-DateUtils_839/Dockerfile b/Java/commons-lang-DateUtils_839/Dockerfile
new file mode 100644
index 000000000..7b7fbe349
--- /dev/null
+++ b/Java/commons-lang-DateUtils_839/Dockerfile
@@ -0,0 +1,18 @@
+FROM ghcr.io/kupl/starlab-benchmarks/java-base:commons-lang
+
+ENV TZ=Asia/Seoul
+
+COPY ./metadata.json .
+COPY ./npe.json .
+COPY ./buggy.java /tmp/buggy.java
+RUN export BUGGY_PATH=$(cat metadata.json | jq -r ".npe.filepath") \
+ && export BUGGY_LINE=$(cat metadata.json | jq -r ".npe.line") \
+ && export BUGGY_MTHD=$(cat metadata.json | jq -r ".npe.npe_method") \
+ && mv /tmp/buggy.java $BUGGY_PATH \
+ && echo "[{\"filepath\": \"$BUGGY_PATH\", \"line\": $BUGGY_LINE, \"method_name\": \"$BUGGY_MTHD\"}]" | jq . > traces.json
+
+RUN git init . && git add -A
+
+RUN $(cat metadata.json | jq -r ".buildCommand")
+
+RUN $(cat metadata.json | jq -r ".testCommand"); if [ $? -eq 0 ]; then exit 1; fi
diff --git a/Java/commons-lang-DateUtils_839/buggy.java b/Java/commons-lang-DateUtils_839/buggy.java
new file mode 100644
index 000000000..4b41b5d5e
--- /dev/null
+++ b/Java/commons-lang-DateUtils_839/buggy.java
@@ -0,0 +1,1874 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3.time;
+
+import java.text.ParseException;
+import java.text.ParsePosition;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.Iterator;
+import java.util.Locale;
+import java.util.NoSuchElementException;
+import java.util.TimeZone;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * A suite of utilities surrounding the use of the + * {@link java.util.Calendar} and {@link java.util.Date} object.
+ * + *DateUtils contains a lot of common methods considering manipulations + * of Dates or Calendars. Some methods require some extra explanation. + * The truncate, ceiling and round methods could be considered the Math.floor(), + * Math.ceil() or Math.round versions for dates + * This way date-fields will be ignored in bottom-up order. + * As a complement to these methods we've introduced some fragment-methods. + * With these methods the Date-fields will be ignored in top-down order. + * Since a date without a year is not a valid date, you have to decide in what + * kind of date-field you want your result, for instance milliseconds or days. + *
+ *+ * Several methods are provided for adding to {@code Date} objects, of the form + * {@code addXXX(Date date, int amount)}. It is important to note these methods + * use a {@code Calendar} internally (with default timezone and locale) and may + * be affected by changes to daylight saving time (DST). + *
+ * + * @since 2.0 + */ +public class DateUtils { + + /** + * Number of milliseconds in a standard second. + * @since 2.1 + */ + public static final long MILLIS_PER_SECOND = 1000; + /** + * Number of milliseconds in a standard minute. + * @since 2.1 + */ + public static final long MILLIS_PER_MINUTE = 60 * MILLIS_PER_SECOND; + /** + * Number of milliseconds in a standard hour. + * @since 2.1 + */ + public static final long MILLIS_PER_HOUR = 60 * MILLIS_PER_MINUTE; + /** + * Number of milliseconds in a standard day. + * @since 2.1 + */ + public static final long MILLIS_PER_DAY = 24 * MILLIS_PER_HOUR; + + /** + * This is half a month, so this represents whether a date is in the top + * or bottom half of the month. + */ + public static final int SEMI_MONTH = 1001; + + private static final int[][] fields = { + {Calendar.MILLISECOND}, + {Calendar.SECOND}, + {Calendar.MINUTE}, + {Calendar.HOUR_OF_DAY, Calendar.HOUR}, + {Calendar.DATE, Calendar.DAY_OF_MONTH, Calendar.AM_PM + /* Calendar.DAY_OF_YEAR, Calendar.DAY_OF_WEEK, Calendar.DAY_OF_WEEK_IN_MONTH */ + }, + {Calendar.MONTH, DateUtils.SEMI_MONTH}, + {Calendar.YEAR}, + {Calendar.ERA}}; + + /** + * A week range, starting on Sunday. + */ + public static final int RANGE_WEEK_SUNDAY = 1; + /** + * A week range, starting on Monday. + */ + public static final int RANGE_WEEK_MONDAY = 2; + /** + * A week range, starting on the day focused. + */ + public static final int RANGE_WEEK_RELATIVE = 3; + /** + * A week range, centered around the day focused. + */ + public static final int RANGE_WEEK_CENTER = 4; + /** + * A month range, the week starting on Sunday. + */ + public static final int RANGE_MONTH_SUNDAY = 5; + /** + * A month range, the week starting on Monday. + */ + public static final int RANGE_MONTH_MONDAY = 6; + + /** + * Calendar modification types. + */ + private enum ModifyType { + /** + * Truncation. + */ + TRUNCATE, + + /** + * Rounding. + */ + ROUND, + + /** + * Ceiling. + */ + CEILING + } + + /** + *{@code DateUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code DateUtils.parseDate(str);}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public DateUtils() { + super(); + } + + //----------------------------------------------------------------------- + /** + *Checks if two date objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar cal1 = Calendar.getInstance();
+ cal1.setTime(date1);
+ final Calendar cal2 = Calendar.getInstance();
+ cal2.setTime(date2);
+ return isSameDay(cal1, cal2);
+ }
+
+ /**
+ * Checks if two calendar objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either calendar isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two date objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return date1.getTime() == date2.getTime();
+ }
+
+ /**
+ * Checks if two calendar objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.getTime().getTime() == cal2.getTime().getTime();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two calendar objects represent the same local time.
+ * + *This method compares the values of the fields of the two objects. + * In addition, both calendars must be the same of the same type.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameLocalTime(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.MILLISECOND) == cal2.get(Calendar.MILLISECOND) &&
+ cal1.get(Calendar.SECOND) == cal2.get(Calendar.SECOND) &&
+ cal1.get(Calendar.MINUTE) == cal2.get(Calendar.MINUTE) &&
+ cal1.get(Calendar.HOUR_OF_DAY) == cal2.get(Calendar.HOUR_OF_DAY) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.getClass() == cal2.getClass();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable (or there were none) + */ + public static Date parseDate(final String str, final String... parsePatterns) throws ParseException { + return parseDate(str, null, parsePatterns); + } + + //----------------------------------------------------------------------- + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDate(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable (or there were none)
+ * @since 3.2
+ */
+ public static Date parseDate(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, true);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @since 2.5 + */ + public static Date parseDateStrictly(final String str, final String... parsePatterns) throws ParseException { + return parseDateStrictly(str, null, parsePatterns); + } + + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale..
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDateStrictly(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable
+ * @since 3.2
+ */
+ public static Date parseDateStrictly(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, false);
+ }
+
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * + * @param str the date to parse, not null + * @param locale the locale to use when interpretting the pattern, can be null in which + * case the default system locale is used + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @param lenient Specify whether or not date/time parsing is to be lenient. + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @see java.util.Calendar#isLenient() + */ + private static Date parseDateWithLeniency( + final String str, final Locale locale, final String[] parsePatterns, final boolean lenient) throws ParseException { + if (str == null || parsePatterns == null) { + throw new IllegalArgumentException("Date and Patterns must not be null"); + } + + final TimeZone tz = TimeZone.getDefault(); + final Locale lcl = locale==null ?Locale.getDefault() : locale; + final ParsePosition pos = new ParsePosition(0); + final Calendar calendar = Calendar.getInstance(tz, lcl); + calendar.setLenient(lenient); + + for (final String parsePattern : parsePatterns) { + FastDateParser fdp = new FastDateParser(parsePattern, tz, lcl); + calendar.clear(); + try { + if (fdp.parse(str, pos, calendar) && pos.getIndex()==str.length()) { + return calendar.getTime(); + } + } + catch(IllegalArgumentException ignore) { + // leniency is preventing calendar from being set + } + pos.setIndex(0); + } + throw new ParseException("Unable to parse the date: " + str, -1); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of years to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addYears(final Date date, final int amount) { + return add(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of months to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMonths(final Date date, final int amount) { + return add(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of weeks to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addWeeks(final Date date, final int amount) { + return add(date, Calendar.WEEK_OF_YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of days to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addDays(final Date date, final int amount) { + return add(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of hours to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addHours(final Date date, final int amount) { + return add(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of minutes to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMinutes(final Date date, final int amount) { + return add(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of seconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addSeconds(final Date date, final int amount) { + return add(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of milliseconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMilliseconds(final Date date, final int amount) { + return add(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the calendar field to add to + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + private static Date add(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + final Calendar c = Calendar.getInstance(); + c.setTime(date); + c.add(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Sets the years field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setYears(final Date date, final int amount) { + return set(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the months field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMonths(final Date date, final int amount) { + return set(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the day of month field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setDays(final Date date, final int amount) { + return set(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the hours field to a date returning a new object. Hours range + * from 0-23. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setHours(final Date date, final int amount) { + return set(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the minute field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMinutes(final Date date, final int amount) { + return set(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the seconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setSeconds(final Date date, final int amount) { + return set(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the milliseconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMilliseconds(final Date date, final int amount) { + return set(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the specified field to a date returning a new object. + * This does not use a lenient calendar. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the {@code Calendar} field to set the amount to + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + private static Date set(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + // getInstance() returns a new object, so this method is thread safe. + final Calendar c = Calendar.getInstance(); + c.setLenient(false); + c.setTime(date); + c.set(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} into a {@code Calendar}. + * + * @param date the date to convert to a Calendar + * @return the created Calendar + * @throws NullPointerException if null is passed in + * @since 3.0 + */ + public static Calendar toCalendar(final Date date) { + final Calendar c = Calendar.getInstance(); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} of a given {@code TimeZone} into a {@code Calendar} + * @param date the date to convert to a Calendar + * @param tz the time zone of the @{code date} + * @return the created Calendar + * @throws NullPointerException if {@code date} or {@code tz} is null + */ + public static Calendar toCalendar(final Date date, final TimeZone tz) { + final Calendar c = Calendar.getInstance(tz); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar round(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar rounded = (Calendar) date.clone();
+ modify(rounded, field, ModifyType.ROUND);
+ return rounded;
+ }
+
+ /**
+ * Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date round(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return round((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return round((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not round " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.TRUNCATE);
+ return gval.getTime();
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+/**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date + * the date to work with, not null + * @param field + * the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException
+ * if the date is null
+ * @throws ArithmeticException
+ * if the year is over 280 million
+ */
+public static java.util.Calendar truncate(final java.util.Calendar date, final int field) {
+ {
+ final java.util.Calendar truncated = ((java.util.Calendar) (/* NPEX_NULL_EXP */
+ date.clone()));
+ org.apache.commons.lang3.time.DateUtils.modify(truncated, field, org.apache.commons.lang3.time.DateUtils.ModifyType.TRUNCATE);
+ return truncated;
+ }
+}
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return truncate((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return truncate((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not truncate " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.CEILING);
+ return gval.getTime();
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Calendar ceiling(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar ceiled = (Calendar) date.clone();
+ modify(ceiled, field, ModifyType.CEILING);
+ return ceiled;
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return ceiling((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return ceiling((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not find ceiling of for type: " + date.getClass());
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Internal calculation method.
+ * + * @param val the calendar, not null + * @param field the field constant + * @param modType type to truncate, round or ceiling + * @throws ArithmeticException if the year is over 280 million + */ + private static void modify(final Calendar val, final int field, final ModifyType modType) { + if (val.get(Calendar.YEAR) > 280000000) { + throw new ArithmeticException("Calendar value too large for accurate calculations"); + } + + if (field == Calendar.MILLISECOND) { + return; + } + + // ----------------- Fix for LANG-59 ---------------------- START --------------- + // see http://issues.apache.org/jira/browse/LANG-59 + // + // Manually truncate milliseconds, seconds and minutes, rather than using + // Calendar methods. + + final Date date = val.getTime(); + long time = date.getTime(); + boolean done = false; + + // truncate milliseconds + final int millisecs = val.get(Calendar.MILLISECOND); + if (ModifyType.TRUNCATE == modType || millisecs < 500) { + time = time - millisecs; + } + if (field == Calendar.SECOND) { + done = true; + } + + // truncate seconds + final int seconds = val.get(Calendar.SECOND); + if (!done && (ModifyType.TRUNCATE == modType || seconds < 30)) { + time = time - (seconds * 1000L); + } + if (field == Calendar.MINUTE) { + done = true; + } + + // truncate minutes + final int minutes = val.get(Calendar.MINUTE); + if (!done && (ModifyType.TRUNCATE == modType || minutes < 30)) { + time = time - (minutes * 60000L); + } + + // reset time + if (date.getTime() != time) { + date.setTime(time); + val.setTime(date); + } + // ----------------- Fix for LANG-59 ----------------------- END ---------------- + + boolean roundUp = false; + for (final int[] aField : fields) { + for (final int element : aField) { + if (element == field) { + //This is our field... we stop looping + if (modType == ModifyType.CEILING || modType == ModifyType.ROUND && roundUp) { + if (field == DateUtils.SEMI_MONTH) { + //This is a special case that's hard to generalize + //If the date is 1, we round up to 16, otherwise + // we subtract 15 days and add 1 month + if (val.get(Calendar.DATE) == 1) { + val.add(Calendar.DATE, 15); + } else { + val.add(Calendar.DATE, -15); + val.add(Calendar.MONTH, 1); + } +// ----------------- Fix for LANG-440 ---------------------- START --------------- + } else if (field == Calendar.AM_PM) { + // This is a special case + // If the time is 0, we round up to 12, otherwise + // we subtract 12 hours and add 1 day + if (val.get(Calendar.HOUR_OF_DAY) == 0) { + val.add(Calendar.HOUR_OF_DAY, 12); + } else { + val.add(Calendar.HOUR_OF_DAY, -12); + val.add(Calendar.DATE, 1); + } +// ----------------- Fix for LANG-440 ---------------------- END --------------- + } else { + //We need at add one to this field since the + // last number causes us to round up + val.add(aField[0], 1); + } + } + return; + } + } + //We have various fields that are not easy roundings + int offset = 0; + boolean offsetSet = false; + //These are special types of fields that require different rounding rules + switch (field) { + case DateUtils.SEMI_MONTH: + if (aField[0] == Calendar.DATE) { + //If we're going to drop the DATE field's value, + // we want to do this our own way. + //We need to subtrace 1 since the date has a minimum of 1 + offset = val.get(Calendar.DATE) - 1; + //If we're above 15 days adjustment, that means we're in the + // bottom half of the month and should stay accordingly. + if (offset >= 15) { + offset -= 15; + } + //Record whether we're in the top or bottom half of that range + roundUp = offset > 7; + offsetSet = true; + } + break; + case Calendar.AM_PM: + if (aField[0] == Calendar.HOUR_OF_DAY) { + //If we're going to drop the HOUR field's value, + // we want to do this our own way. + offset = val.get(Calendar.HOUR_OF_DAY); + if (offset >= 12) { + offset -= 12; + } + roundUp = offset >= 6; + offsetSet = true; + } + break; + default: + break; + } + if (!offsetSet) { + final int min = val.getActualMinimum(aField[0]); + final int max = val.getActualMaximum(aField[0]); + //Calculate the offset from the minimum allowed value + offset = val.get(aField[0]) - min; + //Set roundUp if this is more than half way between the minimum and maximum + roundUp = offset > ((max - min) / 2); + } + //We need to remove this field + if (offset != 0) { + val.set(aField[0], val.get(aField[0]) - offset); + } + } + throw new IllegalArgumentException("The field " + field + " is not supported"); + + } + + //----------------------------------------------------------------------- + /** + *Constructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ */
+ public static Iterator iterator(final Object focus, final int rangeStyle) {
+ if (focus == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (focus instanceof Date) {
+ return iterator((Date) focus, rangeStyle);
+ } else if (focus instanceof Calendar) {
+ return iterator((Calendar) focus, rangeStyle);
+ } else {
+ throw new ClassCastException("Could not iterate based on " + focus);
+ }
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of milliseconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all milliseconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MILLISECONDS);
+ }
+
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MILLISECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MILLISECONDS);
+ }
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Gets a Date fragment for any unit.
+ *
+ * @param date the date to work with, not null
+ * @param fragment the Calendar field part of date to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the date
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Date date, final int fragment, final TimeUnit unit) {
+ if(date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar calendar = Calendar.getInstance();
+ calendar.setTime(date);
+ return getFragment(calendar, fragment, unit);
+ }
+
+ /**
+ * Gets a Calendar fragment for any unit.
+ *
+ * @param calendar the calendar to work with, not null
+ * @param fragment the Calendar field part of calendar to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the calendar
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Calendar calendar, final int fragment, final TimeUnit unit) {
+ if(calendar == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+
+ long result = 0;
+
+ final int offset = (unit == TimeUnit.DAYS) ? 0 : 1;
+
+ // Fragments bigger than a day require a breakdown to days
+ switch (fragment) {
+ case Calendar.YEAR:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_YEAR) - offset, TimeUnit.DAYS);
+ break;
+ case Calendar.MONTH:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_MONTH) - offset, TimeUnit.DAYS);
+ break;
+ default:
+ break;
+ }
+
+ switch (fragment) {
+ // Number of days already calculated for these cases
+ case Calendar.YEAR:
+ case Calendar.MONTH:
+
+ // The rest of the valid cases
+ case Calendar.DAY_OF_YEAR:
+ case Calendar.DATE:
+ result += unit.convert(calendar.get(Calendar.HOUR_OF_DAY), TimeUnit.HOURS);
+ //$FALL-THROUGH$
+ case Calendar.HOUR_OF_DAY:
+ result += unit.convert(calendar.get(Calendar.MINUTE), TimeUnit.MINUTES);
+ //$FALL-THROUGH$
+ case Calendar.MINUTE:
+ result += unit.convert(calendar.get(Calendar.SECOND), TimeUnit.SECONDS);
+ //$FALL-THROUGH$
+ case Calendar.SECOND:
+ result += unit.convert(calendar.get(Calendar.MILLISECOND), TimeUnit.MILLISECONDS);
+ break;
+ case Calendar.MILLISECOND: break;//never useful
+ default: throw new IllegalArgumentException("The fragment " + fragment + " is not supported");
+ }
+ return result;
+ }
+
+ /**
+ * Determines if two calendars are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedEquals(Date, Date, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Calendar cal1, final Calendar cal2, final int field) {
+ return truncatedCompareTo(cal1, cal2, field) == 0;
+ }
+
+ /**
+ * Determines if two dates are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Date, int)
+ * @see #truncatedEquals(Calendar, Calendar, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Date date1, final Date date2, final int field) {
+ return truncatedCompareTo(date1, date2, field) == 0;
+ }
+
+ /**
+ * Determines how two calendars compare up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return a negative integer, zero, or a positive integer as the first
+ * calendar is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Calendar cal1, final Calendar cal2, final int field) {
+ final Calendar truncatedCal1 = truncate(cal1, field);
+ final Calendar truncatedCal2 = truncate(cal2, field);
+ return truncatedCal1.compareTo(truncatedCal2);
+ }
+
+ /**
+ * Determines how two dates compare up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from Calendar
+ * @return a negative integer, zero, or a positive integer as the first
+ * date is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Date date1, final Date date2, final int field) {
+ final Date truncatedDate1 = truncate(date1, field);
+ final Date truncatedDate2 = truncate(date2, field);
+ return truncatedDate1.compareTo(truncatedDate2);
+ }
+
+
+ //-----------------------------------------------------------------------
+ /**
+ * Date iterator.
+ */ + static class DateIterator implements Iteratortrue if the iterator has yet to reach the end date
+ */
+ @Override
+ public boolean hasNext() {
+ return spot.before(endFinal);
+ }
+
+ /**
+ * Return the next calendar in the iteration
+ *
+ * @return Object calendar for the next date
+ */
+ @Override
+ public Calendar next() {
+ if (spot.equals(endFinal)) {
+ throw new NoSuchElementException();
+ }
+ spot.add(Calendar.DATE, 1);
+ return (Calendar) spot.clone();
+ }
+
+ /**
+ * Always throws UnsupportedOperationException.
+ *
+ * @throws UnsupportedOperationException
+ * @see java.util.Iterator#remove()
+ */
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+}
diff --git a/Java/commons-lang-DateUtils_839/metadata.json b/Java/commons-lang-DateUtils_839/metadata.json
new file mode 100644
index 000000000..75c9a49c6
--- /dev/null
+++ b/Java/commons-lang-DateUtils_839/metadata.json
@@ -0,0 +1,21 @@
+{
+ "language": "java",
+ "id": "commons-lang-DateUtils_839",
+ "buggyPath": ".",
+ "referencePath": null,
+ "buildCommand": "mvn package -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100 -DskipTests=true -DskipITs=true -Dtest=None -DfailIfNoTests=false",
+ "testCommand": "mvn test -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100",
+ "categories": [
+ "safety",
+ "npe"
+ ],
+ "npe": {
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 860,
+ "npe_method": "truncate",
+ "deref_field": "date",
+ "npe_class": "DateUtils",
+ "repo": "commons-lang",
+ "bug_id": "DateUtils_839"
+ }
+}
diff --git a/Java/commons-lang-DateUtils_839/npe.json b/Java/commons-lang-DateUtils_839/npe.json
new file mode 100644
index 000000000..000cae16c
--- /dev/null
+++ b/Java/commons-lang-DateUtils_839/npe.json
@@ -0,0 +1,7 @@
+{
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 860,
+ "npe_method": "truncate",
+ "deref_field": "date",
+ "npe_class": "DateUtils"
+}
\ No newline at end of file
diff --git a/Java/commons-lang-DateUtils_864/Dockerfile b/Java/commons-lang-DateUtils_864/Dockerfile
new file mode 100644
index 000000000..7b7fbe349
--- /dev/null
+++ b/Java/commons-lang-DateUtils_864/Dockerfile
@@ -0,0 +1,18 @@
+FROM ghcr.io/kupl/starlab-benchmarks/java-base:commons-lang
+
+ENV TZ=Asia/Seoul
+
+COPY ./metadata.json .
+COPY ./npe.json .
+COPY ./buggy.java /tmp/buggy.java
+RUN export BUGGY_PATH=$(cat metadata.json | jq -r ".npe.filepath") \
+ && export BUGGY_LINE=$(cat metadata.json | jq -r ".npe.line") \
+ && export BUGGY_MTHD=$(cat metadata.json | jq -r ".npe.npe_method") \
+ && mv /tmp/buggy.java $BUGGY_PATH \
+ && echo "[{\"filepath\": \"$BUGGY_PATH\", \"line\": $BUGGY_LINE, \"method_name\": \"$BUGGY_MTHD\"}]" | jq . > traces.json
+
+RUN git init . && git add -A
+
+RUN $(cat metadata.json | jq -r ".buildCommand")
+
+RUN $(cat metadata.json | jq -r ".testCommand"); if [ $? -eq 0 ]; then exit 1; fi
diff --git a/Java/commons-lang-DateUtils_864/buggy.java b/Java/commons-lang-DateUtils_864/buggy.java
new file mode 100644
index 000000000..c668f4f38
--- /dev/null
+++ b/Java/commons-lang-DateUtils_864/buggy.java
@@ -0,0 +1,1876 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3.time;
+
+import java.text.ParseException;
+import java.text.ParsePosition;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.Iterator;
+import java.util.Locale;
+import java.util.NoSuchElementException;
+import java.util.TimeZone;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * A suite of utilities surrounding the use of the + * {@link java.util.Calendar} and {@link java.util.Date} object.
+ * + *DateUtils contains a lot of common methods considering manipulations + * of Dates or Calendars. Some methods require some extra explanation. + * The truncate, ceiling and round methods could be considered the Math.floor(), + * Math.ceil() or Math.round versions for dates + * This way date-fields will be ignored in bottom-up order. + * As a complement to these methods we've introduced some fragment-methods. + * With these methods the Date-fields will be ignored in top-down order. + * Since a date without a year is not a valid date, you have to decide in what + * kind of date-field you want your result, for instance milliseconds or days. + *
+ *+ * Several methods are provided for adding to {@code Date} objects, of the form + * {@code addXXX(Date date, int amount)}. It is important to note these methods + * use a {@code Calendar} internally (with default timezone and locale) and may + * be affected by changes to daylight saving time (DST). + *
+ * + * @since 2.0 + */ +public class DateUtils { + + /** + * Number of milliseconds in a standard second. + * @since 2.1 + */ + public static final long MILLIS_PER_SECOND = 1000; + /** + * Number of milliseconds in a standard minute. + * @since 2.1 + */ + public static final long MILLIS_PER_MINUTE = 60 * MILLIS_PER_SECOND; + /** + * Number of milliseconds in a standard hour. + * @since 2.1 + */ + public static final long MILLIS_PER_HOUR = 60 * MILLIS_PER_MINUTE; + /** + * Number of milliseconds in a standard day. + * @since 2.1 + */ + public static final long MILLIS_PER_DAY = 24 * MILLIS_PER_HOUR; + + /** + * This is half a month, so this represents whether a date is in the top + * or bottom half of the month. + */ + public static final int SEMI_MONTH = 1001; + + private static final int[][] fields = { + {Calendar.MILLISECOND}, + {Calendar.SECOND}, + {Calendar.MINUTE}, + {Calendar.HOUR_OF_DAY, Calendar.HOUR}, + {Calendar.DATE, Calendar.DAY_OF_MONTH, Calendar.AM_PM + /* Calendar.DAY_OF_YEAR, Calendar.DAY_OF_WEEK, Calendar.DAY_OF_WEEK_IN_MONTH */ + }, + {Calendar.MONTH, DateUtils.SEMI_MONTH}, + {Calendar.YEAR}, + {Calendar.ERA}}; + + /** + * A week range, starting on Sunday. + */ + public static final int RANGE_WEEK_SUNDAY = 1; + /** + * A week range, starting on Monday. + */ + public static final int RANGE_WEEK_MONDAY = 2; + /** + * A week range, starting on the day focused. + */ + public static final int RANGE_WEEK_RELATIVE = 3; + /** + * A week range, centered around the day focused. + */ + public static final int RANGE_WEEK_CENTER = 4; + /** + * A month range, the week starting on Sunday. + */ + public static final int RANGE_MONTH_SUNDAY = 5; + /** + * A month range, the week starting on Monday. + */ + public static final int RANGE_MONTH_MONDAY = 6; + + /** + * Calendar modification types. + */ + private enum ModifyType { + /** + * Truncation. + */ + TRUNCATE, + + /** + * Rounding. + */ + ROUND, + + /** + * Ceiling. + */ + CEILING + } + + /** + *{@code DateUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code DateUtils.parseDate(str);}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public DateUtils() { + super(); + } + + //----------------------------------------------------------------------- + /** + *Checks if two date objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar cal1 = Calendar.getInstance();
+ cal1.setTime(date1);
+ final Calendar cal2 = Calendar.getInstance();
+ cal2.setTime(date2);
+ return isSameDay(cal1, cal2);
+ }
+
+ /**
+ * Checks if two calendar objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either calendar isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two date objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return date1.getTime() == date2.getTime();
+ }
+
+ /**
+ * Checks if two calendar objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.getTime().getTime() == cal2.getTime().getTime();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two calendar objects represent the same local time.
+ * + *This method compares the values of the fields of the two objects. + * In addition, both calendars must be the same of the same type.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameLocalTime(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.MILLISECOND) == cal2.get(Calendar.MILLISECOND) &&
+ cal1.get(Calendar.SECOND) == cal2.get(Calendar.SECOND) &&
+ cal1.get(Calendar.MINUTE) == cal2.get(Calendar.MINUTE) &&
+ cal1.get(Calendar.HOUR_OF_DAY) == cal2.get(Calendar.HOUR_OF_DAY) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.getClass() == cal2.getClass();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable (or there were none) + */ + public static Date parseDate(final String str, final String... parsePatterns) throws ParseException { + return parseDate(str, null, parsePatterns); + } + + //----------------------------------------------------------------------- + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDate(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable (or there were none)
+ * @since 3.2
+ */
+ public static Date parseDate(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, true);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @since 2.5 + */ + public static Date parseDateStrictly(final String str, final String... parsePatterns) throws ParseException { + return parseDateStrictly(str, null, parsePatterns); + } + + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale..
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDateStrictly(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable
+ * @since 3.2
+ */
+ public static Date parseDateStrictly(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, false);
+ }
+
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * + * @param str the date to parse, not null + * @param locale the locale to use when interpretting the pattern, can be null in which + * case the default system locale is used + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @param lenient Specify whether or not date/time parsing is to be lenient. + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @see java.util.Calendar#isLenient() + */ + private static Date parseDateWithLeniency( + final String str, final Locale locale, final String[] parsePatterns, final boolean lenient) throws ParseException { + if (str == null || parsePatterns == null) { + throw new IllegalArgumentException("Date and Patterns must not be null"); + } + + final TimeZone tz = TimeZone.getDefault(); + final Locale lcl = locale==null ?Locale.getDefault() : locale; + final ParsePosition pos = new ParsePosition(0); + final Calendar calendar = Calendar.getInstance(tz, lcl); + calendar.setLenient(lenient); + + for (final String parsePattern : parsePatterns) { + FastDateParser fdp = new FastDateParser(parsePattern, tz, lcl); + calendar.clear(); + try { + if (fdp.parse(str, pos, calendar) && pos.getIndex()==str.length()) { + return calendar.getTime(); + } + } + catch(IllegalArgumentException ignore) { + // leniency is preventing calendar from being set + } + pos.setIndex(0); + } + throw new ParseException("Unable to parse the date: " + str, -1); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of years to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addYears(final Date date, final int amount) { + return add(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of months to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMonths(final Date date, final int amount) { + return add(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of weeks to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addWeeks(final Date date, final int amount) { + return add(date, Calendar.WEEK_OF_YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of days to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addDays(final Date date, final int amount) { + return add(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of hours to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addHours(final Date date, final int amount) { + return add(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of minutes to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMinutes(final Date date, final int amount) { + return add(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of seconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addSeconds(final Date date, final int amount) { + return add(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of milliseconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMilliseconds(final Date date, final int amount) { + return add(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the calendar field to add to + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + private static Date add(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + final Calendar c = Calendar.getInstance(); + c.setTime(date); + c.add(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Sets the years field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setYears(final Date date, final int amount) { + return set(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the months field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMonths(final Date date, final int amount) { + return set(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the day of month field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setDays(final Date date, final int amount) { + return set(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the hours field to a date returning a new object. Hours range + * from 0-23. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setHours(final Date date, final int amount) { + return set(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the minute field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMinutes(final Date date, final int amount) { + return set(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the seconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setSeconds(final Date date, final int amount) { + return set(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the milliseconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMilliseconds(final Date date, final int amount) { + return set(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the specified field to a date returning a new object. + * This does not use a lenient calendar. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the {@code Calendar} field to set the amount to + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + private static Date set(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + // getInstance() returns a new object, so this method is thread safe. + final Calendar c = Calendar.getInstance(); + c.setLenient(false); + c.setTime(date); + c.set(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} into a {@code Calendar}. + * + * @param date the date to convert to a Calendar + * @return the created Calendar + * @throws NullPointerException if null is passed in + * @since 3.0 + */ + public static Calendar toCalendar(final Date date) { + final Calendar c = Calendar.getInstance(); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} of a given {@code TimeZone} into a {@code Calendar} + * @param date the date to convert to a Calendar + * @param tz the time zone of the @{code date} + * @return the created Calendar + * @throws NullPointerException if {@code date} or {@code tz} is null + */ + public static Calendar toCalendar(final Date date, final TimeZone tz) { + final Calendar c = Calendar.getInstance(tz); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar round(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar rounded = (Calendar) date.clone();
+ modify(rounded, field, ModifyType.ROUND);
+ return rounded;
+ }
+
+ /**
+ * Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date round(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return round((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return round((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not round " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.TRUNCATE);
+ return gval.getTime();
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar truncate(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar truncated = (Calendar) date.clone();
+ modify(truncated, field, ModifyType.TRUNCATE);
+ return truncated;
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+/**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date + * the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field + * the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException
+ * if the date is null
+ * @throws ClassCastException
+ * if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException
+ * if the year is over 280 million
+ */
+public static java.util.Date truncate(final java.lang.Object date, final int field) {
+ {
+ if (/* NPEX_NULL_EXP */
+ date instanceof java.util.Date) {
+ return org.apache.commons.lang3.time.DateUtils.truncate(((java.util.Date) (date)), field);
+ } else if (date instanceof java.util.Calendar) {
+ return org.apache.commons.lang3.time.DateUtils.truncate(((java.util.Calendar) (date)), field).getTime();
+ } else {
+ throw new java.lang.ClassCastException("Could not truncate " + date);
+ }
+ }
+}
+
+ //-----------------------------------------------------------------------
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.CEILING);
+ return gval.getTime();
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Calendar ceiling(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar ceiled = (Calendar) date.clone();
+ modify(ceiled, field, ModifyType.CEILING);
+ return ceiled;
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return ceiling((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return ceiling((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not find ceiling of for type: " + date.getClass());
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Internal calculation method.
+ * + * @param val the calendar, not null + * @param field the field constant + * @param modType type to truncate, round or ceiling + * @throws ArithmeticException if the year is over 280 million + */ + private static void modify(final Calendar val, final int field, final ModifyType modType) { + if (val.get(Calendar.YEAR) > 280000000) { + throw new ArithmeticException("Calendar value too large for accurate calculations"); + } + + if (field == Calendar.MILLISECOND) { + return; + } + + // ----------------- Fix for LANG-59 ---------------------- START --------------- + // see http://issues.apache.org/jira/browse/LANG-59 + // + // Manually truncate milliseconds, seconds and minutes, rather than using + // Calendar methods. + + final Date date = val.getTime(); + long time = date.getTime(); + boolean done = false; + + // truncate milliseconds + final int millisecs = val.get(Calendar.MILLISECOND); + if (ModifyType.TRUNCATE == modType || millisecs < 500) { + time = time - millisecs; + } + if (field == Calendar.SECOND) { + done = true; + } + + // truncate seconds + final int seconds = val.get(Calendar.SECOND); + if (!done && (ModifyType.TRUNCATE == modType || seconds < 30)) { + time = time - (seconds * 1000L); + } + if (field == Calendar.MINUTE) { + done = true; + } + + // truncate minutes + final int minutes = val.get(Calendar.MINUTE); + if (!done && (ModifyType.TRUNCATE == modType || minutes < 30)) { + time = time - (minutes * 60000L); + } + + // reset time + if (date.getTime() != time) { + date.setTime(time); + val.setTime(date); + } + // ----------------- Fix for LANG-59 ----------------------- END ---------------- + + boolean roundUp = false; + for (final int[] aField : fields) { + for (final int element : aField) { + if (element == field) { + //This is our field... we stop looping + if (modType == ModifyType.CEILING || modType == ModifyType.ROUND && roundUp) { + if (field == DateUtils.SEMI_MONTH) { + //This is a special case that's hard to generalize + //If the date is 1, we round up to 16, otherwise + // we subtract 15 days and add 1 month + if (val.get(Calendar.DATE) == 1) { + val.add(Calendar.DATE, 15); + } else { + val.add(Calendar.DATE, -15); + val.add(Calendar.MONTH, 1); + } +// ----------------- Fix for LANG-440 ---------------------- START --------------- + } else if (field == Calendar.AM_PM) { + // This is a special case + // If the time is 0, we round up to 12, otherwise + // we subtract 12 hours and add 1 day + if (val.get(Calendar.HOUR_OF_DAY) == 0) { + val.add(Calendar.HOUR_OF_DAY, 12); + } else { + val.add(Calendar.HOUR_OF_DAY, -12); + val.add(Calendar.DATE, 1); + } +// ----------------- Fix for LANG-440 ---------------------- END --------------- + } else { + //We need at add one to this field since the + // last number causes us to round up + val.add(aField[0], 1); + } + } + return; + } + } + //We have various fields that are not easy roundings + int offset = 0; + boolean offsetSet = false; + //These are special types of fields that require different rounding rules + switch (field) { + case DateUtils.SEMI_MONTH: + if (aField[0] == Calendar.DATE) { + //If we're going to drop the DATE field's value, + // we want to do this our own way. + //We need to subtrace 1 since the date has a minimum of 1 + offset = val.get(Calendar.DATE) - 1; + //If we're above 15 days adjustment, that means we're in the + // bottom half of the month and should stay accordingly. + if (offset >= 15) { + offset -= 15; + } + //Record whether we're in the top or bottom half of that range + roundUp = offset > 7; + offsetSet = true; + } + break; + case Calendar.AM_PM: + if (aField[0] == Calendar.HOUR_OF_DAY) { + //If we're going to drop the HOUR field's value, + // we want to do this our own way. + offset = val.get(Calendar.HOUR_OF_DAY); + if (offset >= 12) { + offset -= 12; + } + roundUp = offset >= 6; + offsetSet = true; + } + break; + default: + break; + } + if (!offsetSet) { + final int min = val.getActualMinimum(aField[0]); + final int max = val.getActualMaximum(aField[0]); + //Calculate the offset from the minimum allowed value + offset = val.get(aField[0]) - min; + //Set roundUp if this is more than half way between the minimum and maximum + roundUp = offset > ((max - min) / 2); + } + //We need to remove this field + if (offset != 0) { + val.set(aField[0], val.get(aField[0]) - offset); + } + } + throw new IllegalArgumentException("The field " + field + " is not supported"); + + } + + //----------------------------------------------------------------------- + /** + *Constructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ */
+ public static Iterator iterator(final Object focus, final int rangeStyle) {
+ if (focus == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (focus instanceof Date) {
+ return iterator((Date) focus, rangeStyle);
+ } else if (focus instanceof Calendar) {
+ return iterator((Calendar) focus, rangeStyle);
+ } else {
+ throw new ClassCastException("Could not iterate based on " + focus);
+ }
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of milliseconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all milliseconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MILLISECONDS);
+ }
+
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MILLISECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MILLISECONDS);
+ }
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Gets a Date fragment for any unit.
+ *
+ * @param date the date to work with, not null
+ * @param fragment the Calendar field part of date to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the date
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Date date, final int fragment, final TimeUnit unit) {
+ if(date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar calendar = Calendar.getInstance();
+ calendar.setTime(date);
+ return getFragment(calendar, fragment, unit);
+ }
+
+ /**
+ * Gets a Calendar fragment for any unit.
+ *
+ * @param calendar the calendar to work with, not null
+ * @param fragment the Calendar field part of calendar to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the calendar
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Calendar calendar, final int fragment, final TimeUnit unit) {
+ if(calendar == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+
+ long result = 0;
+
+ final int offset = (unit == TimeUnit.DAYS) ? 0 : 1;
+
+ // Fragments bigger than a day require a breakdown to days
+ switch (fragment) {
+ case Calendar.YEAR:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_YEAR) - offset, TimeUnit.DAYS);
+ break;
+ case Calendar.MONTH:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_MONTH) - offset, TimeUnit.DAYS);
+ break;
+ default:
+ break;
+ }
+
+ switch (fragment) {
+ // Number of days already calculated for these cases
+ case Calendar.YEAR:
+ case Calendar.MONTH:
+
+ // The rest of the valid cases
+ case Calendar.DAY_OF_YEAR:
+ case Calendar.DATE:
+ result += unit.convert(calendar.get(Calendar.HOUR_OF_DAY), TimeUnit.HOURS);
+ //$FALL-THROUGH$
+ case Calendar.HOUR_OF_DAY:
+ result += unit.convert(calendar.get(Calendar.MINUTE), TimeUnit.MINUTES);
+ //$FALL-THROUGH$
+ case Calendar.MINUTE:
+ result += unit.convert(calendar.get(Calendar.SECOND), TimeUnit.SECONDS);
+ //$FALL-THROUGH$
+ case Calendar.SECOND:
+ result += unit.convert(calendar.get(Calendar.MILLISECOND), TimeUnit.MILLISECONDS);
+ break;
+ case Calendar.MILLISECOND: break;//never useful
+ default: throw new IllegalArgumentException("The fragment " + fragment + " is not supported");
+ }
+ return result;
+ }
+
+ /**
+ * Determines if two calendars are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedEquals(Date, Date, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Calendar cal1, final Calendar cal2, final int field) {
+ return truncatedCompareTo(cal1, cal2, field) == 0;
+ }
+
+ /**
+ * Determines if two dates are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Date, int)
+ * @see #truncatedEquals(Calendar, Calendar, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Date date1, final Date date2, final int field) {
+ return truncatedCompareTo(date1, date2, field) == 0;
+ }
+
+ /**
+ * Determines how two calendars compare up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return a negative integer, zero, or a positive integer as the first
+ * calendar is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Calendar cal1, final Calendar cal2, final int field) {
+ final Calendar truncatedCal1 = truncate(cal1, field);
+ final Calendar truncatedCal2 = truncate(cal2, field);
+ return truncatedCal1.compareTo(truncatedCal2);
+ }
+
+ /**
+ * Determines how two dates compare up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from Calendar
+ * @return a negative integer, zero, or a positive integer as the first
+ * date is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Date date1, final Date date2, final int field) {
+ final Date truncatedDate1 = truncate(date1, field);
+ final Date truncatedDate2 = truncate(date2, field);
+ return truncatedDate1.compareTo(truncatedDate2);
+ }
+
+
+ //-----------------------------------------------------------------------
+ /**
+ * Date iterator.
+ */ + static class DateIterator implements Iteratortrue if the iterator has yet to reach the end date
+ */
+ @Override
+ public boolean hasNext() {
+ return spot.before(endFinal);
+ }
+
+ /**
+ * Return the next calendar in the iteration
+ *
+ * @return Object calendar for the next date
+ */
+ @Override
+ public Calendar next() {
+ if (spot.equals(endFinal)) {
+ throw new NoSuchElementException();
+ }
+ spot.add(Calendar.DATE, 1);
+ return (Calendar) spot.clone();
+ }
+
+ /**
+ * Always throws UnsupportedOperationException.
+ *
+ * @throws UnsupportedOperationException
+ * @see java.util.Iterator#remove()
+ */
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+}
diff --git a/Java/commons-lang-DateUtils_864/metadata.json b/Java/commons-lang-DateUtils_864/metadata.json
new file mode 100644
index 000000000..72ffca6a7
--- /dev/null
+++ b/Java/commons-lang-DateUtils_864/metadata.json
@@ -0,0 +1,21 @@
+{
+ "language": "java",
+ "id": "commons-lang-DateUtils_864",
+ "buggyPath": ".",
+ "referencePath": null,
+ "buildCommand": "mvn package -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100 -DskipTests=true -DskipITs=true -Dtest=None -DfailIfNoTests=false",
+ "testCommand": "mvn test -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100",
+ "categories": [
+ "safety",
+ "npe"
+ ],
+ "npe": {
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 887,
+ "npe_method": "truncate",
+ "deref_field": "date",
+ "npe_class": "DateUtils",
+ "repo": "commons-lang",
+ "bug_id": "DateUtils_864"
+ }
+}
diff --git a/Java/commons-lang-DateUtils_864/npe.json b/Java/commons-lang-DateUtils_864/npe.json
new file mode 100644
index 000000000..a9d2e3ef4
--- /dev/null
+++ b/Java/commons-lang-DateUtils_864/npe.json
@@ -0,0 +1,7 @@
+{
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 887,
+ "npe_method": "truncate",
+ "deref_field": "date",
+ "npe_class": "DateUtils"
+}
\ No newline at end of file
diff --git a/Java/commons-lang-DateUtils_894/Dockerfile b/Java/commons-lang-DateUtils_894/Dockerfile
new file mode 100644
index 000000000..7b7fbe349
--- /dev/null
+++ b/Java/commons-lang-DateUtils_894/Dockerfile
@@ -0,0 +1,18 @@
+FROM ghcr.io/kupl/starlab-benchmarks/java-base:commons-lang
+
+ENV TZ=Asia/Seoul
+
+COPY ./metadata.json .
+COPY ./npe.json .
+COPY ./buggy.java /tmp/buggy.java
+RUN export BUGGY_PATH=$(cat metadata.json | jq -r ".npe.filepath") \
+ && export BUGGY_LINE=$(cat metadata.json | jq -r ".npe.line") \
+ && export BUGGY_MTHD=$(cat metadata.json | jq -r ".npe.npe_method") \
+ && mv /tmp/buggy.java $BUGGY_PATH \
+ && echo "[{\"filepath\": \"$BUGGY_PATH\", \"line\": $BUGGY_LINE, \"method_name\": \"$BUGGY_MTHD\"}]" | jq . > traces.json
+
+RUN git init . && git add -A
+
+RUN $(cat metadata.json | jq -r ".buildCommand")
+
+RUN $(cat metadata.json | jq -r ".testCommand"); if [ $? -eq 0 ]; then exit 1; fi
diff --git a/Java/commons-lang-DateUtils_894/buggy.java b/Java/commons-lang-DateUtils_894/buggy.java
new file mode 100644
index 000000000..73d581e82
--- /dev/null
+++ b/Java/commons-lang-DateUtils_894/buggy.java
@@ -0,0 +1,1876 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3.time;
+
+import java.text.ParseException;
+import java.text.ParsePosition;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.Iterator;
+import java.util.Locale;
+import java.util.NoSuchElementException;
+import java.util.TimeZone;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * A suite of utilities surrounding the use of the + * {@link java.util.Calendar} and {@link java.util.Date} object.
+ * + *DateUtils contains a lot of common methods considering manipulations + * of Dates or Calendars. Some methods require some extra explanation. + * The truncate, ceiling and round methods could be considered the Math.floor(), + * Math.ceil() or Math.round versions for dates + * This way date-fields will be ignored in bottom-up order. + * As a complement to these methods we've introduced some fragment-methods. + * With these methods the Date-fields will be ignored in top-down order. + * Since a date without a year is not a valid date, you have to decide in what + * kind of date-field you want your result, for instance milliseconds or days. + *
+ *+ * Several methods are provided for adding to {@code Date} objects, of the form + * {@code addXXX(Date date, int amount)}. It is important to note these methods + * use a {@code Calendar} internally (with default timezone and locale) and may + * be affected by changes to daylight saving time (DST). + *
+ * + * @since 2.0 + */ +public class DateUtils { + + /** + * Number of milliseconds in a standard second. + * @since 2.1 + */ + public static final long MILLIS_PER_SECOND = 1000; + /** + * Number of milliseconds in a standard minute. + * @since 2.1 + */ + public static final long MILLIS_PER_MINUTE = 60 * MILLIS_PER_SECOND; + /** + * Number of milliseconds in a standard hour. + * @since 2.1 + */ + public static final long MILLIS_PER_HOUR = 60 * MILLIS_PER_MINUTE; + /** + * Number of milliseconds in a standard day. + * @since 2.1 + */ + public static final long MILLIS_PER_DAY = 24 * MILLIS_PER_HOUR; + + /** + * This is half a month, so this represents whether a date is in the top + * or bottom half of the month. + */ + public static final int SEMI_MONTH = 1001; + + private static final int[][] fields = { + {Calendar.MILLISECOND}, + {Calendar.SECOND}, + {Calendar.MINUTE}, + {Calendar.HOUR_OF_DAY, Calendar.HOUR}, + {Calendar.DATE, Calendar.DAY_OF_MONTH, Calendar.AM_PM + /* Calendar.DAY_OF_YEAR, Calendar.DAY_OF_WEEK, Calendar.DAY_OF_WEEK_IN_MONTH */ + }, + {Calendar.MONTH, DateUtils.SEMI_MONTH}, + {Calendar.YEAR}, + {Calendar.ERA}}; + + /** + * A week range, starting on Sunday. + */ + public static final int RANGE_WEEK_SUNDAY = 1; + /** + * A week range, starting on Monday. + */ + public static final int RANGE_WEEK_MONDAY = 2; + /** + * A week range, starting on the day focused. + */ + public static final int RANGE_WEEK_RELATIVE = 3; + /** + * A week range, centered around the day focused. + */ + public static final int RANGE_WEEK_CENTER = 4; + /** + * A month range, the week starting on Sunday. + */ + public static final int RANGE_MONTH_SUNDAY = 5; + /** + * A month range, the week starting on Monday. + */ + public static final int RANGE_MONTH_MONDAY = 6; + + /** + * Calendar modification types. + */ + private enum ModifyType { + /** + * Truncation. + */ + TRUNCATE, + + /** + * Rounding. + */ + ROUND, + + /** + * Ceiling. + */ + CEILING + } + + /** + *{@code DateUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code DateUtils.parseDate(str);}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public DateUtils() { + super(); + } + + //----------------------------------------------------------------------- + /** + *Checks if two date objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar cal1 = Calendar.getInstance();
+ cal1.setTime(date1);
+ final Calendar cal2 = Calendar.getInstance();
+ cal2.setTime(date2);
+ return isSameDay(cal1, cal2);
+ }
+
+ /**
+ * Checks if two calendar objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either calendar isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two date objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return date1.getTime() == date2.getTime();
+ }
+
+ /**
+ * Checks if two calendar objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.getTime().getTime() == cal2.getTime().getTime();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two calendar objects represent the same local time.
+ * + *This method compares the values of the fields of the two objects. + * In addition, both calendars must be the same of the same type.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameLocalTime(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.MILLISECOND) == cal2.get(Calendar.MILLISECOND) &&
+ cal1.get(Calendar.SECOND) == cal2.get(Calendar.SECOND) &&
+ cal1.get(Calendar.MINUTE) == cal2.get(Calendar.MINUTE) &&
+ cal1.get(Calendar.HOUR_OF_DAY) == cal2.get(Calendar.HOUR_OF_DAY) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.getClass() == cal2.getClass();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable (or there were none) + */ + public static Date parseDate(final String str, final String... parsePatterns) throws ParseException { + return parseDate(str, null, parsePatterns); + } + + //----------------------------------------------------------------------- + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDate(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable (or there were none)
+ * @since 3.2
+ */
+ public static Date parseDate(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, true);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @since 2.5 + */ + public static Date parseDateStrictly(final String str, final String... parsePatterns) throws ParseException { + return parseDateStrictly(str, null, parsePatterns); + } + + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale..
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDateStrictly(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable
+ * @since 3.2
+ */
+ public static Date parseDateStrictly(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, false);
+ }
+
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * + * @param str the date to parse, not null + * @param locale the locale to use when interpretting the pattern, can be null in which + * case the default system locale is used + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @param lenient Specify whether or not date/time parsing is to be lenient. + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @see java.util.Calendar#isLenient() + */ + private static Date parseDateWithLeniency( + final String str, final Locale locale, final String[] parsePatterns, final boolean lenient) throws ParseException { + if (str == null || parsePatterns == null) { + throw new IllegalArgumentException("Date and Patterns must not be null"); + } + + final TimeZone tz = TimeZone.getDefault(); + final Locale lcl = locale==null ?Locale.getDefault() : locale; + final ParsePosition pos = new ParsePosition(0); + final Calendar calendar = Calendar.getInstance(tz, lcl); + calendar.setLenient(lenient); + + for (final String parsePattern : parsePatterns) { + FastDateParser fdp = new FastDateParser(parsePattern, tz, lcl); + calendar.clear(); + try { + if (fdp.parse(str, pos, calendar) && pos.getIndex()==str.length()) { + return calendar.getTime(); + } + } + catch(IllegalArgumentException ignore) { + // leniency is preventing calendar from being set + } + pos.setIndex(0); + } + throw new ParseException("Unable to parse the date: " + str, -1); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of years to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addYears(final Date date, final int amount) { + return add(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of months to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMonths(final Date date, final int amount) { + return add(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of weeks to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addWeeks(final Date date, final int amount) { + return add(date, Calendar.WEEK_OF_YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of days to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addDays(final Date date, final int amount) { + return add(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of hours to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addHours(final Date date, final int amount) { + return add(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of minutes to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMinutes(final Date date, final int amount) { + return add(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of seconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addSeconds(final Date date, final int amount) { + return add(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of milliseconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMilliseconds(final Date date, final int amount) { + return add(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the calendar field to add to + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + private static Date add(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + final Calendar c = Calendar.getInstance(); + c.setTime(date); + c.add(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Sets the years field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setYears(final Date date, final int amount) { + return set(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the months field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMonths(final Date date, final int amount) { + return set(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the day of month field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setDays(final Date date, final int amount) { + return set(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the hours field to a date returning a new object. Hours range + * from 0-23. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setHours(final Date date, final int amount) { + return set(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the minute field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMinutes(final Date date, final int amount) { + return set(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the seconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setSeconds(final Date date, final int amount) { + return set(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the milliseconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMilliseconds(final Date date, final int amount) { + return set(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the specified field to a date returning a new object. + * This does not use a lenient calendar. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the {@code Calendar} field to set the amount to + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + private static Date set(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + // getInstance() returns a new object, so this method is thread safe. + final Calendar c = Calendar.getInstance(); + c.setLenient(false); + c.setTime(date); + c.set(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} into a {@code Calendar}. + * + * @param date the date to convert to a Calendar + * @return the created Calendar + * @throws NullPointerException if null is passed in + * @since 3.0 + */ + public static Calendar toCalendar(final Date date) { + final Calendar c = Calendar.getInstance(); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} of a given {@code TimeZone} into a {@code Calendar} + * @param date the date to convert to a Calendar + * @param tz the time zone of the @{code date} + * @return the created Calendar + * @throws NullPointerException if {@code date} or {@code tz} is null + */ + public static Calendar toCalendar(final Date date, final TimeZone tz) { + final Calendar c = Calendar.getInstance(tz); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar round(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar rounded = (Calendar) date.clone();
+ modify(rounded, field, ModifyType.ROUND);
+ return rounded;
+ }
+
+ /**
+ * Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date round(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return round((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return round((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not round " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.TRUNCATE);
+ return gval.getTime();
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar truncate(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar truncated = (Calendar) date.clone();
+ modify(truncated, field, ModifyType.TRUNCATE);
+ return truncated;
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return truncate((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return truncate((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not truncate " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+// -----------------------------------------------------------------------
+/**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date + * the date to work with, not null + * @param field + * the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException
+ * if the date is null
+ * @throws ArithmeticException
+ * if the year is over 280 million
+ * @since 2.5
+ */
+public static java.util.Date ceiling(final java.util.Date date, final int field) {
+ {
+ final java.util.Calendar gval = java.util.Calendar.getInstance();
+ gval.setTime(/* NPEX_NULL_EXP */
+ date);
+ org.apache.commons.lang3.time.DateUtils.modify(gval, field, org.apache.commons.lang3.time.DateUtils.ModifyType.CEILING);
+ return gval.getTime();
+ }
+}
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Calendar ceiling(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar ceiled = (Calendar) date.clone();
+ modify(ceiled, field, ModifyType.CEILING);
+ return ceiled;
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return ceiling((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return ceiling((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not find ceiling of for type: " + date.getClass());
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Internal calculation method.
+ * + * @param val the calendar, not null + * @param field the field constant + * @param modType type to truncate, round or ceiling + * @throws ArithmeticException if the year is over 280 million + */ + private static void modify(final Calendar val, final int field, final ModifyType modType) { + if (val.get(Calendar.YEAR) > 280000000) { + throw new ArithmeticException("Calendar value too large for accurate calculations"); + } + + if (field == Calendar.MILLISECOND) { + return; + } + + // ----------------- Fix for LANG-59 ---------------------- START --------------- + // see http://issues.apache.org/jira/browse/LANG-59 + // + // Manually truncate milliseconds, seconds and minutes, rather than using + // Calendar methods. + + final Date date = val.getTime(); + long time = date.getTime(); + boolean done = false; + + // truncate milliseconds + final int millisecs = val.get(Calendar.MILLISECOND); + if (ModifyType.TRUNCATE == modType || millisecs < 500) { + time = time - millisecs; + } + if (field == Calendar.SECOND) { + done = true; + } + + // truncate seconds + final int seconds = val.get(Calendar.SECOND); + if (!done && (ModifyType.TRUNCATE == modType || seconds < 30)) { + time = time - (seconds * 1000L); + } + if (field == Calendar.MINUTE) { + done = true; + } + + // truncate minutes + final int minutes = val.get(Calendar.MINUTE); + if (!done && (ModifyType.TRUNCATE == modType || minutes < 30)) { + time = time - (minutes * 60000L); + } + + // reset time + if (date.getTime() != time) { + date.setTime(time); + val.setTime(date); + } + // ----------------- Fix for LANG-59 ----------------------- END ---------------- + + boolean roundUp = false; + for (final int[] aField : fields) { + for (final int element : aField) { + if (element == field) { + //This is our field... we stop looping + if (modType == ModifyType.CEILING || modType == ModifyType.ROUND && roundUp) { + if (field == DateUtils.SEMI_MONTH) { + //This is a special case that's hard to generalize + //If the date is 1, we round up to 16, otherwise + // we subtract 15 days and add 1 month + if (val.get(Calendar.DATE) == 1) { + val.add(Calendar.DATE, 15); + } else { + val.add(Calendar.DATE, -15); + val.add(Calendar.MONTH, 1); + } +// ----------------- Fix for LANG-440 ---------------------- START --------------- + } else if (field == Calendar.AM_PM) { + // This is a special case + // If the time is 0, we round up to 12, otherwise + // we subtract 12 hours and add 1 day + if (val.get(Calendar.HOUR_OF_DAY) == 0) { + val.add(Calendar.HOUR_OF_DAY, 12); + } else { + val.add(Calendar.HOUR_OF_DAY, -12); + val.add(Calendar.DATE, 1); + } +// ----------------- Fix for LANG-440 ---------------------- END --------------- + } else { + //We need at add one to this field since the + // last number causes us to round up + val.add(aField[0], 1); + } + } + return; + } + } + //We have various fields that are not easy roundings + int offset = 0; + boolean offsetSet = false; + //These are special types of fields that require different rounding rules + switch (field) { + case DateUtils.SEMI_MONTH: + if (aField[0] == Calendar.DATE) { + //If we're going to drop the DATE field's value, + // we want to do this our own way. + //We need to subtrace 1 since the date has a minimum of 1 + offset = val.get(Calendar.DATE) - 1; + //If we're above 15 days adjustment, that means we're in the + // bottom half of the month and should stay accordingly. + if (offset >= 15) { + offset -= 15; + } + //Record whether we're in the top or bottom half of that range + roundUp = offset > 7; + offsetSet = true; + } + break; + case Calendar.AM_PM: + if (aField[0] == Calendar.HOUR_OF_DAY) { + //If we're going to drop the HOUR field's value, + // we want to do this our own way. + offset = val.get(Calendar.HOUR_OF_DAY); + if (offset >= 12) { + offset -= 12; + } + roundUp = offset >= 6; + offsetSet = true; + } + break; + default: + break; + } + if (!offsetSet) { + final int min = val.getActualMinimum(aField[0]); + final int max = val.getActualMaximum(aField[0]); + //Calculate the offset from the minimum allowed value + offset = val.get(aField[0]) - min; + //Set roundUp if this is more than half way between the minimum and maximum + roundUp = offset > ((max - min) / 2); + } + //We need to remove this field + if (offset != 0) { + val.set(aField[0], val.get(aField[0]) - offset); + } + } + throw new IllegalArgumentException("The field " + field + " is not supported"); + + } + + //----------------------------------------------------------------------- + /** + *Constructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ */
+ public static Iterator iterator(final Object focus, final int rangeStyle) {
+ if (focus == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (focus instanceof Date) {
+ return iterator((Date) focus, rangeStyle);
+ } else if (focus instanceof Calendar) {
+ return iterator((Calendar) focus, rangeStyle);
+ } else {
+ throw new ClassCastException("Could not iterate based on " + focus);
+ }
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of milliseconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all milliseconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MILLISECONDS);
+ }
+
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MILLISECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MILLISECONDS);
+ }
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Gets a Date fragment for any unit.
+ *
+ * @param date the date to work with, not null
+ * @param fragment the Calendar field part of date to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the date
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Date date, final int fragment, final TimeUnit unit) {
+ if(date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar calendar = Calendar.getInstance();
+ calendar.setTime(date);
+ return getFragment(calendar, fragment, unit);
+ }
+
+ /**
+ * Gets a Calendar fragment for any unit.
+ *
+ * @param calendar the calendar to work with, not null
+ * @param fragment the Calendar field part of calendar to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the calendar
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Calendar calendar, final int fragment, final TimeUnit unit) {
+ if(calendar == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+
+ long result = 0;
+
+ final int offset = (unit == TimeUnit.DAYS) ? 0 : 1;
+
+ // Fragments bigger than a day require a breakdown to days
+ switch (fragment) {
+ case Calendar.YEAR:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_YEAR) - offset, TimeUnit.DAYS);
+ break;
+ case Calendar.MONTH:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_MONTH) - offset, TimeUnit.DAYS);
+ break;
+ default:
+ break;
+ }
+
+ switch (fragment) {
+ // Number of days already calculated for these cases
+ case Calendar.YEAR:
+ case Calendar.MONTH:
+
+ // The rest of the valid cases
+ case Calendar.DAY_OF_YEAR:
+ case Calendar.DATE:
+ result += unit.convert(calendar.get(Calendar.HOUR_OF_DAY), TimeUnit.HOURS);
+ //$FALL-THROUGH$
+ case Calendar.HOUR_OF_DAY:
+ result += unit.convert(calendar.get(Calendar.MINUTE), TimeUnit.MINUTES);
+ //$FALL-THROUGH$
+ case Calendar.MINUTE:
+ result += unit.convert(calendar.get(Calendar.SECOND), TimeUnit.SECONDS);
+ //$FALL-THROUGH$
+ case Calendar.SECOND:
+ result += unit.convert(calendar.get(Calendar.MILLISECOND), TimeUnit.MILLISECONDS);
+ break;
+ case Calendar.MILLISECOND: break;//never useful
+ default: throw new IllegalArgumentException("The fragment " + fragment + " is not supported");
+ }
+ return result;
+ }
+
+ /**
+ * Determines if two calendars are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedEquals(Date, Date, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Calendar cal1, final Calendar cal2, final int field) {
+ return truncatedCompareTo(cal1, cal2, field) == 0;
+ }
+
+ /**
+ * Determines if two dates are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Date, int)
+ * @see #truncatedEquals(Calendar, Calendar, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Date date1, final Date date2, final int field) {
+ return truncatedCompareTo(date1, date2, field) == 0;
+ }
+
+ /**
+ * Determines how two calendars compare up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return a negative integer, zero, or a positive integer as the first
+ * calendar is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Calendar cal1, final Calendar cal2, final int field) {
+ final Calendar truncatedCal1 = truncate(cal1, field);
+ final Calendar truncatedCal2 = truncate(cal2, field);
+ return truncatedCal1.compareTo(truncatedCal2);
+ }
+
+ /**
+ * Determines how two dates compare up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from Calendar
+ * @return a negative integer, zero, or a positive integer as the first
+ * date is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Date date1, final Date date2, final int field) {
+ final Date truncatedDate1 = truncate(date1, field);
+ final Date truncatedDate2 = truncate(date2, field);
+ return truncatedDate1.compareTo(truncatedDate2);
+ }
+
+
+ //-----------------------------------------------------------------------
+ /**
+ * Date iterator.
+ */ + static class DateIterator implements Iteratortrue if the iterator has yet to reach the end date
+ */
+ @Override
+ public boolean hasNext() {
+ return spot.before(endFinal);
+ }
+
+ /**
+ * Return the next calendar in the iteration
+ *
+ * @return Object calendar for the next date
+ */
+ @Override
+ public Calendar next() {
+ if (spot.equals(endFinal)) {
+ throw new NoSuchElementException();
+ }
+ spot.add(Calendar.DATE, 1);
+ return (Calendar) spot.clone();
+ }
+
+ /**
+ * Always throws UnsupportedOperationException.
+ *
+ * @throws UnsupportedOperationException
+ * @see java.util.Iterator#remove()
+ */
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+}
diff --git a/Java/commons-lang-DateUtils_894/metadata.json b/Java/commons-lang-DateUtils_894/metadata.json
new file mode 100644
index 000000000..f6aad8a79
--- /dev/null
+++ b/Java/commons-lang-DateUtils_894/metadata.json
@@ -0,0 +1,21 @@
+{
+ "language": "java",
+ "id": "commons-lang-DateUtils_894",
+ "buggyPath": ".",
+ "referencePath": null,
+ "buildCommand": "mvn package -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100 -DskipTests=true -DskipITs=true -Dtest=None -DfailIfNoTests=false",
+ "testCommand": "mvn test -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100",
+ "categories": [
+ "safety",
+ "npe"
+ ],
+ "npe": {
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 918,
+ "npe_method": "ceiling",
+ "deref_field": "date",
+ "npe_class": "DateUtils",
+ "repo": "commons-lang",
+ "bug_id": "DateUtils_894"
+ }
+}
diff --git a/Java/commons-lang-DateUtils_894/npe.json b/Java/commons-lang-DateUtils_894/npe.json
new file mode 100644
index 000000000..c99d0e5c1
--- /dev/null
+++ b/Java/commons-lang-DateUtils_894/npe.json
@@ -0,0 +1,7 @@
+{
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 918,
+ "npe_method": "ceiling",
+ "deref_field": "date",
+ "npe_class": "DateUtils"
+}
\ No newline at end of file
diff --git a/Java/commons-lang-DateUtils_920/Dockerfile b/Java/commons-lang-DateUtils_920/Dockerfile
new file mode 100644
index 000000000..7b7fbe349
--- /dev/null
+++ b/Java/commons-lang-DateUtils_920/Dockerfile
@@ -0,0 +1,18 @@
+FROM ghcr.io/kupl/starlab-benchmarks/java-base:commons-lang
+
+ENV TZ=Asia/Seoul
+
+COPY ./metadata.json .
+COPY ./npe.json .
+COPY ./buggy.java /tmp/buggy.java
+RUN export BUGGY_PATH=$(cat metadata.json | jq -r ".npe.filepath") \
+ && export BUGGY_LINE=$(cat metadata.json | jq -r ".npe.line") \
+ && export BUGGY_MTHD=$(cat metadata.json | jq -r ".npe.npe_method") \
+ && mv /tmp/buggy.java $BUGGY_PATH \
+ && echo "[{\"filepath\": \"$BUGGY_PATH\", \"line\": $BUGGY_LINE, \"method_name\": \"$BUGGY_MTHD\"}]" | jq . > traces.json
+
+RUN git init . && git add -A
+
+RUN $(cat metadata.json | jq -r ".buildCommand")
+
+RUN $(cat metadata.json | jq -r ".testCommand"); if [ $? -eq 0 ]; then exit 1; fi
diff --git a/Java/commons-lang-DateUtils_920/buggy.java b/Java/commons-lang-DateUtils_920/buggy.java
new file mode 100644
index 000000000..5f1c7f2a9
--- /dev/null
+++ b/Java/commons-lang-DateUtils_920/buggy.java
@@ -0,0 +1,1875 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3.time;
+
+import java.text.ParseException;
+import java.text.ParsePosition;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.Iterator;
+import java.util.Locale;
+import java.util.NoSuchElementException;
+import java.util.TimeZone;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * A suite of utilities surrounding the use of the + * {@link java.util.Calendar} and {@link java.util.Date} object.
+ * + *DateUtils contains a lot of common methods considering manipulations + * of Dates or Calendars. Some methods require some extra explanation. + * The truncate, ceiling and round methods could be considered the Math.floor(), + * Math.ceil() or Math.round versions for dates + * This way date-fields will be ignored in bottom-up order. + * As a complement to these methods we've introduced some fragment-methods. + * With these methods the Date-fields will be ignored in top-down order. + * Since a date without a year is not a valid date, you have to decide in what + * kind of date-field you want your result, for instance milliseconds or days. + *
+ *+ * Several methods are provided for adding to {@code Date} objects, of the form + * {@code addXXX(Date date, int amount)}. It is important to note these methods + * use a {@code Calendar} internally (with default timezone and locale) and may + * be affected by changes to daylight saving time (DST). + *
+ * + * @since 2.0 + */ +public class DateUtils { + + /** + * Number of milliseconds in a standard second. + * @since 2.1 + */ + public static final long MILLIS_PER_SECOND = 1000; + /** + * Number of milliseconds in a standard minute. + * @since 2.1 + */ + public static final long MILLIS_PER_MINUTE = 60 * MILLIS_PER_SECOND; + /** + * Number of milliseconds in a standard hour. + * @since 2.1 + */ + public static final long MILLIS_PER_HOUR = 60 * MILLIS_PER_MINUTE; + /** + * Number of milliseconds in a standard day. + * @since 2.1 + */ + public static final long MILLIS_PER_DAY = 24 * MILLIS_PER_HOUR; + + /** + * This is half a month, so this represents whether a date is in the top + * or bottom half of the month. + */ + public static final int SEMI_MONTH = 1001; + + private static final int[][] fields = { + {Calendar.MILLISECOND}, + {Calendar.SECOND}, + {Calendar.MINUTE}, + {Calendar.HOUR_OF_DAY, Calendar.HOUR}, + {Calendar.DATE, Calendar.DAY_OF_MONTH, Calendar.AM_PM + /* Calendar.DAY_OF_YEAR, Calendar.DAY_OF_WEEK, Calendar.DAY_OF_WEEK_IN_MONTH */ + }, + {Calendar.MONTH, DateUtils.SEMI_MONTH}, + {Calendar.YEAR}, + {Calendar.ERA}}; + + /** + * A week range, starting on Sunday. + */ + public static final int RANGE_WEEK_SUNDAY = 1; + /** + * A week range, starting on Monday. + */ + public static final int RANGE_WEEK_MONDAY = 2; + /** + * A week range, starting on the day focused. + */ + public static final int RANGE_WEEK_RELATIVE = 3; + /** + * A week range, centered around the day focused. + */ + public static final int RANGE_WEEK_CENTER = 4; + /** + * A month range, the week starting on Sunday. + */ + public static final int RANGE_MONTH_SUNDAY = 5; + /** + * A month range, the week starting on Monday. + */ + public static final int RANGE_MONTH_MONDAY = 6; + + /** + * Calendar modification types. + */ + private enum ModifyType { + /** + * Truncation. + */ + TRUNCATE, + + /** + * Rounding. + */ + ROUND, + + /** + * Ceiling. + */ + CEILING + } + + /** + *{@code DateUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code DateUtils.parseDate(str);}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public DateUtils() { + super(); + } + + //----------------------------------------------------------------------- + /** + *Checks if two date objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar cal1 = Calendar.getInstance();
+ cal1.setTime(date1);
+ final Calendar cal2 = Calendar.getInstance();
+ cal2.setTime(date2);
+ return isSameDay(cal1, cal2);
+ }
+
+ /**
+ * Checks if two calendar objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either calendar isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two date objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return date1.getTime() == date2.getTime();
+ }
+
+ /**
+ * Checks if two calendar objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.getTime().getTime() == cal2.getTime().getTime();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two calendar objects represent the same local time.
+ * + *This method compares the values of the fields of the two objects. + * In addition, both calendars must be the same of the same type.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameLocalTime(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.MILLISECOND) == cal2.get(Calendar.MILLISECOND) &&
+ cal1.get(Calendar.SECOND) == cal2.get(Calendar.SECOND) &&
+ cal1.get(Calendar.MINUTE) == cal2.get(Calendar.MINUTE) &&
+ cal1.get(Calendar.HOUR_OF_DAY) == cal2.get(Calendar.HOUR_OF_DAY) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.getClass() == cal2.getClass();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable (or there were none) + */ + public static Date parseDate(final String str, final String... parsePatterns) throws ParseException { + return parseDate(str, null, parsePatterns); + } + + //----------------------------------------------------------------------- + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDate(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable (or there were none)
+ * @since 3.2
+ */
+ public static Date parseDate(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, true);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @since 2.5 + */ + public static Date parseDateStrictly(final String str, final String... parsePatterns) throws ParseException { + return parseDateStrictly(str, null, parsePatterns); + } + + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale..
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDateStrictly(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable
+ * @since 3.2
+ */
+ public static Date parseDateStrictly(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, false);
+ }
+
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * + * @param str the date to parse, not null + * @param locale the locale to use when interpretting the pattern, can be null in which + * case the default system locale is used + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @param lenient Specify whether or not date/time parsing is to be lenient. + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @see java.util.Calendar#isLenient() + */ + private static Date parseDateWithLeniency( + final String str, final Locale locale, final String[] parsePatterns, final boolean lenient) throws ParseException { + if (str == null || parsePatterns == null) { + throw new IllegalArgumentException("Date and Patterns must not be null"); + } + + final TimeZone tz = TimeZone.getDefault(); + final Locale lcl = locale==null ?Locale.getDefault() : locale; + final ParsePosition pos = new ParsePosition(0); + final Calendar calendar = Calendar.getInstance(tz, lcl); + calendar.setLenient(lenient); + + for (final String parsePattern : parsePatterns) { + FastDateParser fdp = new FastDateParser(parsePattern, tz, lcl); + calendar.clear(); + try { + if (fdp.parse(str, pos, calendar) && pos.getIndex()==str.length()) { + return calendar.getTime(); + } + } + catch(IllegalArgumentException ignore) { + // leniency is preventing calendar from being set + } + pos.setIndex(0); + } + throw new ParseException("Unable to parse the date: " + str, -1); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of years to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addYears(final Date date, final int amount) { + return add(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of months to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMonths(final Date date, final int amount) { + return add(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of weeks to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addWeeks(final Date date, final int amount) { + return add(date, Calendar.WEEK_OF_YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of days to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addDays(final Date date, final int amount) { + return add(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of hours to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addHours(final Date date, final int amount) { + return add(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of minutes to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMinutes(final Date date, final int amount) { + return add(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of seconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addSeconds(final Date date, final int amount) { + return add(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of milliseconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMilliseconds(final Date date, final int amount) { + return add(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the calendar field to add to + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + private static Date add(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + final Calendar c = Calendar.getInstance(); + c.setTime(date); + c.add(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Sets the years field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setYears(final Date date, final int amount) { + return set(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the months field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMonths(final Date date, final int amount) { + return set(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the day of month field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setDays(final Date date, final int amount) { + return set(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the hours field to a date returning a new object. Hours range + * from 0-23. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setHours(final Date date, final int amount) { + return set(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the minute field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMinutes(final Date date, final int amount) { + return set(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the seconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setSeconds(final Date date, final int amount) { + return set(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the milliseconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMilliseconds(final Date date, final int amount) { + return set(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the specified field to a date returning a new object. + * This does not use a lenient calendar. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the {@code Calendar} field to set the amount to + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + private static Date set(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + // getInstance() returns a new object, so this method is thread safe. + final Calendar c = Calendar.getInstance(); + c.setLenient(false); + c.setTime(date); + c.set(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} into a {@code Calendar}. + * + * @param date the date to convert to a Calendar + * @return the created Calendar + * @throws NullPointerException if null is passed in + * @since 3.0 + */ + public static Calendar toCalendar(final Date date) { + final Calendar c = Calendar.getInstance(); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} of a given {@code TimeZone} into a {@code Calendar} + * @param date the date to convert to a Calendar + * @param tz the time zone of the @{code date} + * @return the created Calendar + * @throws NullPointerException if {@code date} or {@code tz} is null + */ + public static Calendar toCalendar(final Date date, final TimeZone tz) { + final Calendar c = Calendar.getInstance(tz); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar round(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar rounded = (Calendar) date.clone();
+ modify(rounded, field, ModifyType.ROUND);
+ return rounded;
+ }
+
+ /**
+ * Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date round(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return round((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return round((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not round " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.TRUNCATE);
+ return gval.getTime();
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar truncate(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar truncated = (Calendar) date.clone();
+ modify(truncated, field, ModifyType.TRUNCATE);
+ return truncated;
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return truncate((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return truncate((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not truncate " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.CEILING);
+ return gval.getTime();
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+/**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date + * the date to work with, not null + * @param field + * the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException
+ * if the date is null
+ * @throws ArithmeticException
+ * if the year is over 280 million
+ * @since 2.5
+ */
+public static java.util.Calendar ceiling(final java.util.Calendar date, final int field) {
+ {
+ final java.util.Calendar ceiled = ((java.util.Calendar) (/* NPEX_NULL_EXP */
+ date.clone()));
+ org.apache.commons.lang3.time.DateUtils.modify(ceiled, field, org.apache.commons.lang3.time.DateUtils.ModifyType.CEILING);
+ return ceiled;
+ }
+}
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return ceiling((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return ceiling((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not find ceiling of for type: " + date.getClass());
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Internal calculation method.
+ * + * @param val the calendar, not null + * @param field the field constant + * @param modType type to truncate, round or ceiling + * @throws ArithmeticException if the year is over 280 million + */ + private static void modify(final Calendar val, final int field, final ModifyType modType) { + if (val.get(Calendar.YEAR) > 280000000) { + throw new ArithmeticException("Calendar value too large for accurate calculations"); + } + + if (field == Calendar.MILLISECOND) { + return; + } + + // ----------------- Fix for LANG-59 ---------------------- START --------------- + // see http://issues.apache.org/jira/browse/LANG-59 + // + // Manually truncate milliseconds, seconds and minutes, rather than using + // Calendar methods. + + final Date date = val.getTime(); + long time = date.getTime(); + boolean done = false; + + // truncate milliseconds + final int millisecs = val.get(Calendar.MILLISECOND); + if (ModifyType.TRUNCATE == modType || millisecs < 500) { + time = time - millisecs; + } + if (field == Calendar.SECOND) { + done = true; + } + + // truncate seconds + final int seconds = val.get(Calendar.SECOND); + if (!done && (ModifyType.TRUNCATE == modType || seconds < 30)) { + time = time - (seconds * 1000L); + } + if (field == Calendar.MINUTE) { + done = true; + } + + // truncate minutes + final int minutes = val.get(Calendar.MINUTE); + if (!done && (ModifyType.TRUNCATE == modType || minutes < 30)) { + time = time - (minutes * 60000L); + } + + // reset time + if (date.getTime() != time) { + date.setTime(time); + val.setTime(date); + } + // ----------------- Fix for LANG-59 ----------------------- END ---------------- + + boolean roundUp = false; + for (final int[] aField : fields) { + for (final int element : aField) { + if (element == field) { + //This is our field... we stop looping + if (modType == ModifyType.CEILING || modType == ModifyType.ROUND && roundUp) { + if (field == DateUtils.SEMI_MONTH) { + //This is a special case that's hard to generalize + //If the date is 1, we round up to 16, otherwise + // we subtract 15 days and add 1 month + if (val.get(Calendar.DATE) == 1) { + val.add(Calendar.DATE, 15); + } else { + val.add(Calendar.DATE, -15); + val.add(Calendar.MONTH, 1); + } +// ----------------- Fix for LANG-440 ---------------------- START --------------- + } else if (field == Calendar.AM_PM) { + // This is a special case + // If the time is 0, we round up to 12, otherwise + // we subtract 12 hours and add 1 day + if (val.get(Calendar.HOUR_OF_DAY) == 0) { + val.add(Calendar.HOUR_OF_DAY, 12); + } else { + val.add(Calendar.HOUR_OF_DAY, -12); + val.add(Calendar.DATE, 1); + } +// ----------------- Fix for LANG-440 ---------------------- END --------------- + } else { + //We need at add one to this field since the + // last number causes us to round up + val.add(aField[0], 1); + } + } + return; + } + } + //We have various fields that are not easy roundings + int offset = 0; + boolean offsetSet = false; + //These are special types of fields that require different rounding rules + switch (field) { + case DateUtils.SEMI_MONTH: + if (aField[0] == Calendar.DATE) { + //If we're going to drop the DATE field's value, + // we want to do this our own way. + //We need to subtrace 1 since the date has a minimum of 1 + offset = val.get(Calendar.DATE) - 1; + //If we're above 15 days adjustment, that means we're in the + // bottom half of the month and should stay accordingly. + if (offset >= 15) { + offset -= 15; + } + //Record whether we're in the top or bottom half of that range + roundUp = offset > 7; + offsetSet = true; + } + break; + case Calendar.AM_PM: + if (aField[0] == Calendar.HOUR_OF_DAY) { + //If we're going to drop the HOUR field's value, + // we want to do this our own way. + offset = val.get(Calendar.HOUR_OF_DAY); + if (offset >= 12) { + offset -= 12; + } + roundUp = offset >= 6; + offsetSet = true; + } + break; + default: + break; + } + if (!offsetSet) { + final int min = val.getActualMinimum(aField[0]); + final int max = val.getActualMaximum(aField[0]); + //Calculate the offset from the minimum allowed value + offset = val.get(aField[0]) - min; + //Set roundUp if this is more than half way between the minimum and maximum + roundUp = offset > ((max - min) / 2); + } + //We need to remove this field + if (offset != 0) { + val.set(aField[0], val.get(aField[0]) - offset); + } + } + throw new IllegalArgumentException("The field " + field + " is not supported"); + + } + + //----------------------------------------------------------------------- + /** + *Constructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ */
+ public static Iterator iterator(final Object focus, final int rangeStyle) {
+ if (focus == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (focus instanceof Date) {
+ return iterator((Date) focus, rangeStyle);
+ } else if (focus instanceof Calendar) {
+ return iterator((Calendar) focus, rangeStyle);
+ } else {
+ throw new ClassCastException("Could not iterate based on " + focus);
+ }
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of milliseconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all milliseconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MILLISECONDS);
+ }
+
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MILLISECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MILLISECONDS);
+ }
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Gets a Date fragment for any unit.
+ *
+ * @param date the date to work with, not null
+ * @param fragment the Calendar field part of date to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the date
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Date date, final int fragment, final TimeUnit unit) {
+ if(date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar calendar = Calendar.getInstance();
+ calendar.setTime(date);
+ return getFragment(calendar, fragment, unit);
+ }
+
+ /**
+ * Gets a Calendar fragment for any unit.
+ *
+ * @param calendar the calendar to work with, not null
+ * @param fragment the Calendar field part of calendar to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the calendar
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Calendar calendar, final int fragment, final TimeUnit unit) {
+ if(calendar == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+
+ long result = 0;
+
+ final int offset = (unit == TimeUnit.DAYS) ? 0 : 1;
+
+ // Fragments bigger than a day require a breakdown to days
+ switch (fragment) {
+ case Calendar.YEAR:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_YEAR) - offset, TimeUnit.DAYS);
+ break;
+ case Calendar.MONTH:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_MONTH) - offset, TimeUnit.DAYS);
+ break;
+ default:
+ break;
+ }
+
+ switch (fragment) {
+ // Number of days already calculated for these cases
+ case Calendar.YEAR:
+ case Calendar.MONTH:
+
+ // The rest of the valid cases
+ case Calendar.DAY_OF_YEAR:
+ case Calendar.DATE:
+ result += unit.convert(calendar.get(Calendar.HOUR_OF_DAY), TimeUnit.HOURS);
+ //$FALL-THROUGH$
+ case Calendar.HOUR_OF_DAY:
+ result += unit.convert(calendar.get(Calendar.MINUTE), TimeUnit.MINUTES);
+ //$FALL-THROUGH$
+ case Calendar.MINUTE:
+ result += unit.convert(calendar.get(Calendar.SECOND), TimeUnit.SECONDS);
+ //$FALL-THROUGH$
+ case Calendar.SECOND:
+ result += unit.convert(calendar.get(Calendar.MILLISECOND), TimeUnit.MILLISECONDS);
+ break;
+ case Calendar.MILLISECOND: break;//never useful
+ default: throw new IllegalArgumentException("The fragment " + fragment + " is not supported");
+ }
+ return result;
+ }
+
+ /**
+ * Determines if two calendars are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedEquals(Date, Date, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Calendar cal1, final Calendar cal2, final int field) {
+ return truncatedCompareTo(cal1, cal2, field) == 0;
+ }
+
+ /**
+ * Determines if two dates are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Date, int)
+ * @see #truncatedEquals(Calendar, Calendar, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Date date1, final Date date2, final int field) {
+ return truncatedCompareTo(date1, date2, field) == 0;
+ }
+
+ /**
+ * Determines how two calendars compare up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return a negative integer, zero, or a positive integer as the first
+ * calendar is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Calendar cal1, final Calendar cal2, final int field) {
+ final Calendar truncatedCal1 = truncate(cal1, field);
+ final Calendar truncatedCal2 = truncate(cal2, field);
+ return truncatedCal1.compareTo(truncatedCal2);
+ }
+
+ /**
+ * Determines how two dates compare up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from Calendar
+ * @return a negative integer, zero, or a positive integer as the first
+ * date is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Date date1, final Date date2, final int field) {
+ final Date truncatedDate1 = truncate(date1, field);
+ final Date truncatedDate2 = truncate(date2, field);
+ return truncatedDate1.compareTo(truncatedDate2);
+ }
+
+
+ //-----------------------------------------------------------------------
+ /**
+ * Date iterator.
+ */ + static class DateIterator implements Iteratortrue if the iterator has yet to reach the end date
+ */
+ @Override
+ public boolean hasNext() {
+ return spot.before(endFinal);
+ }
+
+ /**
+ * Return the next calendar in the iteration
+ *
+ * @return Object calendar for the next date
+ */
+ @Override
+ public Calendar next() {
+ if (spot.equals(endFinal)) {
+ throw new NoSuchElementException();
+ }
+ spot.add(Calendar.DATE, 1);
+ return (Calendar) spot.clone();
+ }
+
+ /**
+ * Always throws UnsupportedOperationException.
+ *
+ * @throws UnsupportedOperationException
+ * @see java.util.Iterator#remove()
+ */
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+}
diff --git a/Java/commons-lang-DateUtils_920/metadata.json b/Java/commons-lang-DateUtils_920/metadata.json
new file mode 100644
index 000000000..65900cb8b
--- /dev/null
+++ b/Java/commons-lang-DateUtils_920/metadata.json
@@ -0,0 +1,21 @@
+{
+ "language": "java",
+ "id": "commons-lang-DateUtils_920",
+ "buggyPath": ".",
+ "referencePath": null,
+ "buildCommand": "mvn package -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100 -DskipTests=true -DskipITs=true -Dtest=None -DfailIfNoTests=false",
+ "testCommand": "mvn test -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100",
+ "categories": [
+ "safety",
+ "npe"
+ ],
+ "npe": {
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 942,
+ "npe_method": "ceiling",
+ "deref_field": "date",
+ "npe_class": "DateUtils",
+ "repo": "commons-lang",
+ "bug_id": "DateUtils_920"
+ }
+}
diff --git a/Java/commons-lang-DateUtils_920/npe.json b/Java/commons-lang-DateUtils_920/npe.json
new file mode 100644
index 000000000..2b565f57c
--- /dev/null
+++ b/Java/commons-lang-DateUtils_920/npe.json
@@ -0,0 +1,7 @@
+{
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 942,
+ "npe_method": "ceiling",
+ "deref_field": "date",
+ "npe_class": "DateUtils"
+}
\ No newline at end of file
diff --git a/Java/commons-lang-DateUtils_946/Dockerfile b/Java/commons-lang-DateUtils_946/Dockerfile
new file mode 100644
index 000000000..7b7fbe349
--- /dev/null
+++ b/Java/commons-lang-DateUtils_946/Dockerfile
@@ -0,0 +1,18 @@
+FROM ghcr.io/kupl/starlab-benchmarks/java-base:commons-lang
+
+ENV TZ=Asia/Seoul
+
+COPY ./metadata.json .
+COPY ./npe.json .
+COPY ./buggy.java /tmp/buggy.java
+RUN export BUGGY_PATH=$(cat metadata.json | jq -r ".npe.filepath") \
+ && export BUGGY_LINE=$(cat metadata.json | jq -r ".npe.line") \
+ && export BUGGY_MTHD=$(cat metadata.json | jq -r ".npe.npe_method") \
+ && mv /tmp/buggy.java $BUGGY_PATH \
+ && echo "[{\"filepath\": \"$BUGGY_PATH\", \"line\": $BUGGY_LINE, \"method_name\": \"$BUGGY_MTHD\"}]" | jq . > traces.json
+
+RUN git init . && git add -A
+
+RUN $(cat metadata.json | jq -r ".buildCommand")
+
+RUN $(cat metadata.json | jq -r ".testCommand"); if [ $? -eq 0 ]; then exit 1; fi
diff --git a/Java/commons-lang-DateUtils_946/buggy.java b/Java/commons-lang-DateUtils_946/buggy.java
new file mode 100644
index 000000000..0ed859a59
--- /dev/null
+++ b/Java/commons-lang-DateUtils_946/buggy.java
@@ -0,0 +1,1877 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3.time;
+
+import java.text.ParseException;
+import java.text.ParsePosition;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.Iterator;
+import java.util.Locale;
+import java.util.NoSuchElementException;
+import java.util.TimeZone;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * A suite of utilities surrounding the use of the + * {@link java.util.Calendar} and {@link java.util.Date} object.
+ * + *DateUtils contains a lot of common methods considering manipulations + * of Dates or Calendars. Some methods require some extra explanation. + * The truncate, ceiling and round methods could be considered the Math.floor(), + * Math.ceil() or Math.round versions for dates + * This way date-fields will be ignored in bottom-up order. + * As a complement to these methods we've introduced some fragment-methods. + * With these methods the Date-fields will be ignored in top-down order. + * Since a date without a year is not a valid date, you have to decide in what + * kind of date-field you want your result, for instance milliseconds or days. + *
+ *+ * Several methods are provided for adding to {@code Date} objects, of the form + * {@code addXXX(Date date, int amount)}. It is important to note these methods + * use a {@code Calendar} internally (with default timezone and locale) and may + * be affected by changes to daylight saving time (DST). + *
+ * + * @since 2.0 + */ +public class DateUtils { + + /** + * Number of milliseconds in a standard second. + * @since 2.1 + */ + public static final long MILLIS_PER_SECOND = 1000; + /** + * Number of milliseconds in a standard minute. + * @since 2.1 + */ + public static final long MILLIS_PER_MINUTE = 60 * MILLIS_PER_SECOND; + /** + * Number of milliseconds in a standard hour. + * @since 2.1 + */ + public static final long MILLIS_PER_HOUR = 60 * MILLIS_PER_MINUTE; + /** + * Number of milliseconds in a standard day. + * @since 2.1 + */ + public static final long MILLIS_PER_DAY = 24 * MILLIS_PER_HOUR; + + /** + * This is half a month, so this represents whether a date is in the top + * or bottom half of the month. + */ + public static final int SEMI_MONTH = 1001; + + private static final int[][] fields = { + {Calendar.MILLISECOND}, + {Calendar.SECOND}, + {Calendar.MINUTE}, + {Calendar.HOUR_OF_DAY, Calendar.HOUR}, + {Calendar.DATE, Calendar.DAY_OF_MONTH, Calendar.AM_PM + /* Calendar.DAY_OF_YEAR, Calendar.DAY_OF_WEEK, Calendar.DAY_OF_WEEK_IN_MONTH */ + }, + {Calendar.MONTH, DateUtils.SEMI_MONTH}, + {Calendar.YEAR}, + {Calendar.ERA}}; + + /** + * A week range, starting on Sunday. + */ + public static final int RANGE_WEEK_SUNDAY = 1; + /** + * A week range, starting on Monday. + */ + public static final int RANGE_WEEK_MONDAY = 2; + /** + * A week range, starting on the day focused. + */ + public static final int RANGE_WEEK_RELATIVE = 3; + /** + * A week range, centered around the day focused. + */ + public static final int RANGE_WEEK_CENTER = 4; + /** + * A month range, the week starting on Sunday. + */ + public static final int RANGE_MONTH_SUNDAY = 5; + /** + * A month range, the week starting on Monday. + */ + public static final int RANGE_MONTH_MONDAY = 6; + + /** + * Calendar modification types. + */ + private enum ModifyType { + /** + * Truncation. + */ + TRUNCATE, + + /** + * Rounding. + */ + ROUND, + + /** + * Ceiling. + */ + CEILING + } + + /** + *{@code DateUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code DateUtils.parseDate(str);}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public DateUtils() { + super(); + } + + //----------------------------------------------------------------------- + /** + *Checks if two date objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar cal1 = Calendar.getInstance();
+ cal1.setTime(date1);
+ final Calendar cal2 = Calendar.getInstance();
+ cal2.setTime(date2);
+ return isSameDay(cal1, cal2);
+ }
+
+ /**
+ * Checks if two calendar objects are on the same day ignoring time.
+ * + *28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. + * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false. + *
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same day + * @throws IllegalArgumentException if either calendar isnull
+ * @since 2.1
+ */
+ public static boolean isSameDay(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two date objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param date1 the first date, not altered, not null + * @param date2 the second date, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Date date1, final Date date2) {
+ if (date1 == null || date2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return date1.getTime() == date2.getTime();
+ }
+
+ /**
+ * Checks if two calendar objects represent the same instant in time.
+ * + *This method compares the long millisecond time of the two objects.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameInstant(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.getTime().getTime() == cal2.getTime().getTime();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Checks if two calendar objects represent the same local time.
+ * + *This method compares the values of the fields of the two objects. + * In addition, both calendars must be the same of the same type.
+ * + * @param cal1 the first calendar, not altered, not null + * @param cal2 the second calendar, not altered, not null + * @return true if they represent the same millisecond instant + * @throws IllegalArgumentException if either date isnull
+ * @since 2.1
+ */
+ public static boolean isSameLocalTime(final Calendar cal1, final Calendar cal2) {
+ if (cal1 == null || cal2 == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ return cal1.get(Calendar.MILLISECOND) == cal2.get(Calendar.MILLISECOND) &&
+ cal1.get(Calendar.SECOND) == cal2.get(Calendar.SECOND) &&
+ cal1.get(Calendar.MINUTE) == cal2.get(Calendar.MINUTE) &&
+ cal1.get(Calendar.HOUR_OF_DAY) == cal2.get(Calendar.HOUR_OF_DAY) &&
+ cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR) &&
+ cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
+ cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
+ cal1.getClass() == cal2.getClass();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable (or there were none) + */ + public static Date parseDate(final String str, final String... parsePatterns) throws ParseException { + return parseDate(str, null, parsePatterns); + } + + //----------------------------------------------------------------------- + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser will be lenient toward the parsed date. + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDate(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable (or there were none)
+ * @since 3.2
+ */
+ public static Date parseDate(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, true);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @since 2.5 + */ + public static Date parseDateStrictly(final String str, final String... parsePatterns) throws ParseException { + return parseDateStrictly(str, null, parsePatterns); + } + + /** + *Parses a string representing a date by trying a variety of different parsers, + * using the default date format symbols for the given locale..
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * The parser parses strictly - it does not allow for dates such as "February 942, 1996". + * + * @param str the date to parse, not null + * @param locale the locale whose date format symbols should be used. Ifnull,
+ * the system locale is used (as per {@link #parseDateStrictly(String, String...)}).
+ * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null
+ * @return the parsed date
+ * @throws IllegalArgumentException if the date string or pattern array is null
+ * @throws ParseException if none of the date patterns were suitable
+ * @since 3.2
+ */
+ public static Date parseDateStrictly(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
+ return parseDateWithLeniency(str, locale, parsePatterns, false);
+ }
+
+ /**
+ * Parses a string representing a date by trying a variety of different parsers.
+ * + *The parse will try each parse pattern in turn. + * A parse is only deemed successful if it parses the whole of the input string. + * If no parse patterns match, a ParseException is thrown.
+ * + * @param str the date to parse, not null + * @param locale the locale to use when interpretting the pattern, can be null in which + * case the default system locale is used + * @param parsePatterns the date format patterns to use, see SimpleDateFormat, not null + * @param lenient Specify whether or not date/time parsing is to be lenient. + * @return the parsed date + * @throws IllegalArgumentException if the date string or pattern array is null + * @throws ParseException if none of the date patterns were suitable + * @see java.util.Calendar#isLenient() + */ + private static Date parseDateWithLeniency( + final String str, final Locale locale, final String[] parsePatterns, final boolean lenient) throws ParseException { + if (str == null || parsePatterns == null) { + throw new IllegalArgumentException("Date and Patterns must not be null"); + } + + final TimeZone tz = TimeZone.getDefault(); + final Locale lcl = locale==null ?Locale.getDefault() : locale; + final ParsePosition pos = new ParsePosition(0); + final Calendar calendar = Calendar.getInstance(tz, lcl); + calendar.setLenient(lenient); + + for (final String parsePattern : parsePatterns) { + FastDateParser fdp = new FastDateParser(parsePattern, tz, lcl); + calendar.clear(); + try { + if (fdp.parse(str, pos, calendar) && pos.getIndex()==str.length()) { + return calendar.getTime(); + } + } + catch(IllegalArgumentException ignore) { + // leniency is preventing calendar from being set + } + pos.setIndex(0); + } + throw new ParseException("Unable to parse the date: " + str, -1); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of years to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addYears(final Date date, final int amount) { + return add(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of months to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMonths(final Date date, final int amount) { + return add(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of weeks to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addWeeks(final Date date, final int amount) { + return add(date, Calendar.WEEK_OF_YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of days to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addDays(final Date date, final int amount) { + return add(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of hours to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addHours(final Date date, final int amount) { + return add(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of minutes to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMinutes(final Date date, final int amount) { + return add(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of seconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addSeconds(final Date date, final int amount) { + return add(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds a number of milliseconds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + public static Date addMilliseconds(final Date date, final int amount) { + return add(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Adds to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the calendar field to add to + * @param amount the amount to add, may be negative + * @return the new {@code Date} with the amount added + * @throws IllegalArgumentException if the date is null + */ + private static Date add(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + final Calendar c = Calendar.getInstance(); + c.setTime(date); + c.add(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Sets the years field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setYears(final Date date, final int amount) { + return set(date, Calendar.YEAR, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the months field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMonths(final Date date, final int amount) { + return set(date, Calendar.MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the day of month field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setDays(final Date date, final int amount) { + return set(date, Calendar.DAY_OF_MONTH, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the hours field to a date returning a new object. Hours range + * from 0-23. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setHours(final Date date, final int amount) { + return set(date, Calendar.HOUR_OF_DAY, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the minute field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMinutes(final Date date, final int amount) { + return set(date, Calendar.MINUTE, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the seconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setSeconds(final Date date, final int amount) { + return set(date, Calendar.SECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the milliseconds field to a date returning a new object. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + public static Date setMilliseconds(final Date date, final int amount) { + return set(date, Calendar.MILLISECOND, amount); + } + + //----------------------------------------------------------------------- + /** + * Sets the specified field to a date returning a new object. + * This does not use a lenient calendar. + * The original {@code Date} is unchanged. + * + * @param date the date, not null + * @param calendarField the {@code Calendar} field to set the amount to + * @param amount the amount to set + * @return a new {@code Date} set with the specified value + * @throws IllegalArgumentException if the date is null + * @since 2.4 + */ + private static Date set(final Date date, final int calendarField, final int amount) { + if (date == null) { + throw new IllegalArgumentException("The date must not be null"); + } + // getInstance() returns a new object, so this method is thread safe. + final Calendar c = Calendar.getInstance(); + c.setLenient(false); + c.setTime(date); + c.set(calendarField, amount); + return c.getTime(); + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} into a {@code Calendar}. + * + * @param date the date to convert to a Calendar + * @return the created Calendar + * @throws NullPointerException if null is passed in + * @since 3.0 + */ + public static Calendar toCalendar(final Date date) { + final Calendar c = Calendar.getInstance(); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + * Converts a {@code Date} of a given {@code TimeZone} into a {@code Calendar} + * @param date the date to convert to a Calendar + * @param tz the time zone of the @{code date} + * @return the created Calendar + * @throws NullPointerException if {@code date} or {@code tz} is null + */ + public static Calendar toCalendar(final Date date, final TimeZone tz) { + final Calendar c = Calendar.getInstance(tz); + c.setTime(date); + return c; + } + + //----------------------------------------------------------------------- + /** + *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar round(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar rounded = (Calendar) date.clone();
+ modify(rounded, field, ModifyType.ROUND);
+ return rounded;
+ }
+
+ /**
+ * Rounds a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if this was passed with HOUR, it would return + * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it + * would return 1 April 2002 0:00:00.000.
+ * + *For a date in a timezone that handles the change to daylight + * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a + * date that crosses this time would produce the following values: + *
+ *SEMI_MONTH
+ * @return the different rounded date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date round(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return round((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return round((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not round " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.TRUNCATE);
+ return gval.getTime();
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Calendar truncate(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar truncated = (Calendar) date.clone();
+ modify(truncated, field, ModifyType.TRUNCATE);
+ return truncated;
+ }
+
+ /**
+ * Truncates a date, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 13:00:00.000. If this was passed with MONTH, it would + * return 1 Mar 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different truncated date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ */
+ public static Date truncate(final Object date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (date instanceof Date) {
+ return truncate((Date) date, field);
+ } else if (date instanceof Calendar) {
+ return truncate((Calendar) date, field).getTime();
+ } else {
+ throw new ClassCastException("Could not truncate " + date);
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Date ceiling(final Date date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar gval = Calendar.getInstance();
+ gval.setTime(date);
+ modify(gval, field, ModifyType.CEILING);
+ return gval.getTime();
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+ public static Calendar ceiling(final Calendar date, final int field) {
+ if (date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar ceiled = (Calendar) date.clone();
+ modify(ceiled, field, ModifyType.CEILING);
+ return ceiled;
+ }
+
+ /**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException if the date is null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException if the year is over 280 million
+ * @since 2.5
+ */
+/**
+ * Gets a date ceiling, leaving the field specified as the most + * significant field.
+ * + *For example, if you had the date-time of 28 Mar 2002 + * 13:45:01.231, if you passed with HOUR, it would return 28 Mar + * 2002 14:00:00.000. If this was passed with MONTH, it would + * return 1 Apr 2002 0:00:00.000.
+ * + * @param date + * the date to work with, either {@code Date} or {@code Calendar}, not null + * @param field + * the field from {@code Calendar} orSEMI_MONTH
+ * @return the different ceil date, not null
+ * @throws IllegalArgumentException
+ * if the date is null
+ * @throws ClassCastException
+ * if the object type is not a {@code Date} or {@code Calendar}
+ * @throws ArithmeticException
+ * if the year is over 280 million
+ * @since 2.5
+ */
+public static java.util.Date ceiling(final java.lang.Object date, final int field) {
+ {
+ if (/* NPEX_NULL_EXP */
+ date instanceof java.util.Date) {
+ return org.apache.commons.lang3.time.DateUtils.ceiling(((java.util.Date) (date)), field);
+ } else if (date instanceof java.util.Calendar) {
+ return org.apache.commons.lang3.time.DateUtils.ceiling(((java.util.Calendar) (date)), field).getTime();
+ } else {
+ throw new java.lang.ClassCastException("Could not find ceiling of for type: " + date.getClass());
+ }
+ }
+}
+
+ //-----------------------------------------------------------------------
+ /**
+ * Internal calculation method.
+ * + * @param val the calendar, not null + * @param field the field constant + * @param modType type to truncate, round or ceiling + * @throws ArithmeticException if the year is over 280 million + */ + private static void modify(final Calendar val, final int field, final ModifyType modType) { + if (val.get(Calendar.YEAR) > 280000000) { + throw new ArithmeticException("Calendar value too large for accurate calculations"); + } + + if (field == Calendar.MILLISECOND) { + return; + } + + // ----------------- Fix for LANG-59 ---------------------- START --------------- + // see http://issues.apache.org/jira/browse/LANG-59 + // + // Manually truncate milliseconds, seconds and minutes, rather than using + // Calendar methods. + + final Date date = val.getTime(); + long time = date.getTime(); + boolean done = false; + + // truncate milliseconds + final int millisecs = val.get(Calendar.MILLISECOND); + if (ModifyType.TRUNCATE == modType || millisecs < 500) { + time = time - millisecs; + } + if (field == Calendar.SECOND) { + done = true; + } + + // truncate seconds + final int seconds = val.get(Calendar.SECOND); + if (!done && (ModifyType.TRUNCATE == modType || seconds < 30)) { + time = time - (seconds * 1000L); + } + if (field == Calendar.MINUTE) { + done = true; + } + + // truncate minutes + final int minutes = val.get(Calendar.MINUTE); + if (!done && (ModifyType.TRUNCATE == modType || minutes < 30)) { + time = time - (minutes * 60000L); + } + + // reset time + if (date.getTime() != time) { + date.setTime(time); + val.setTime(date); + } + // ----------------- Fix for LANG-59 ----------------------- END ---------------- + + boolean roundUp = false; + for (final int[] aField : fields) { + for (final int element : aField) { + if (element == field) { + //This is our field... we stop looping + if (modType == ModifyType.CEILING || modType == ModifyType.ROUND && roundUp) { + if (field == DateUtils.SEMI_MONTH) { + //This is a special case that's hard to generalize + //If the date is 1, we round up to 16, otherwise + // we subtract 15 days and add 1 month + if (val.get(Calendar.DATE) == 1) { + val.add(Calendar.DATE, 15); + } else { + val.add(Calendar.DATE, -15); + val.add(Calendar.MONTH, 1); + } +// ----------------- Fix for LANG-440 ---------------------- START --------------- + } else if (field == Calendar.AM_PM) { + // This is a special case + // If the time is 0, we round up to 12, otherwise + // we subtract 12 hours and add 1 day + if (val.get(Calendar.HOUR_OF_DAY) == 0) { + val.add(Calendar.HOUR_OF_DAY, 12); + } else { + val.add(Calendar.HOUR_OF_DAY, -12); + val.add(Calendar.DATE, 1); + } +// ----------------- Fix for LANG-440 ---------------------- END --------------- + } else { + //We need at add one to this field since the + // last number causes us to round up + val.add(aField[0], 1); + } + } + return; + } + } + //We have various fields that are not easy roundings + int offset = 0; + boolean offsetSet = false; + //These are special types of fields that require different rounding rules + switch (field) { + case DateUtils.SEMI_MONTH: + if (aField[0] == Calendar.DATE) { + //If we're going to drop the DATE field's value, + // we want to do this our own way. + //We need to subtrace 1 since the date has a minimum of 1 + offset = val.get(Calendar.DATE) - 1; + //If we're above 15 days adjustment, that means we're in the + // bottom half of the month and should stay accordingly. + if (offset >= 15) { + offset -= 15; + } + //Record whether we're in the top or bottom half of that range + roundUp = offset > 7; + offsetSet = true; + } + break; + case Calendar.AM_PM: + if (aField[0] == Calendar.HOUR_OF_DAY) { + //If we're going to drop the HOUR field's value, + // we want to do this our own way. + offset = val.get(Calendar.HOUR_OF_DAY); + if (offset >= 12) { + offset -= 12; + } + roundUp = offset >= 6; + offsetSet = true; + } + break; + default: + break; + } + if (!offsetSet) { + final int min = val.getActualMinimum(aField[0]); + final int max = val.getActualMaximum(aField[0]); + //Calculate the offset from the minimum allowed value + offset = val.get(aField[0]) - min; + //Set roundUp if this is more than half way between the minimum and maximum + roundUp = offset > ((max - min) / 2); + } + //We need to remove this field + if (offset != 0) { + val.set(aField[0], val.get(aField[0]) - offset); + } + } + throw new IllegalArgumentException("The field " + field + " is not supported"); + + } + + //----------------------------------------------------------------------- + /** + *Constructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
This method provides an iterator that returns Calendar objects. + * The days are progressed using {@link Calendar#add(int, int)}.
+ * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * {@link DateUtils#RANGE_MONTH_SUNDAY}, + * {@link DateUtils#RANGE_MONTH_MONDAY}, + * {@link DateUtils#RANGE_WEEK_SUNDAY}, + * {@link DateUtils#RANGE_WEEK_MONDAY}, + * {@link DateUtils#RANGE_WEEK_RELATIVE}, + * {@link DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, not null + * @throws IllegalArgumentException if the date isnull
+ * @throws IllegalArgumentException if the rangeStyle is invalid
+ */
+ public static IteratorConstructs an Iterator over each day in a date
+ * range defined by a focus date and range style.
For instance, passing Thursday, July 4, 2002 and a
+ * RANGE_MONTH_SUNDAY will return an Iterator
+ * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
+ * 2002, returning a Calendar instance for each intermediate day.
null
+ * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
+ */
+ public static Iterator iterator(final Object focus, final int rangeStyle) {
+ if (focus == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ if (focus instanceof Date) {
+ return iterator((Date) focus, rangeStyle);
+ } else if (focus instanceof Calendar) {
+ return iterator((Calendar) focus, rangeStyle);
+ } else {
+ throw new ClassCastException("Could not iterate based on " + focus);
+ }
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of milliseconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all milliseconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MILLISECONDS);
+ }
+
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Date date, final int fragment) {
+ return getFragment(date, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the milliseconds of any date will only return the number of milliseconds + * of the current second (resulting in a number between 0 and 999). This + * method will retrieve the number of milliseconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s), minutes(s) and second(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MILLISECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMilliseconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MILLISECONDS);
+ }
+ /**
+ * Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the seconds of any date will only return the number of seconds + * of the current minute (resulting in a number between 0 and 59). This + * method will retrieve the number of seconds for any fragment. + * For example, if you want to calculate the number of seconds past today, + * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will + * be all seconds of the past hour(s) and minutes(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a SECOND field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInSeconds(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.SECONDS);
+ }
+
+ /**
+ * Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the minutes of any date will only return the number of minutes + * of the current hour (resulting in a number between 0 and 59). This + * method will retrieve the number of minutes for any fragment. + * For example, if you want to calculate the number of minutes past this month, + * your fragment is Calendar.MONTH. The result will be all minutes of the + * past day(s) and hour(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a MINUTE field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInMinutes(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.MINUTES);
+ }
+
+ /**
+ * Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the hours of any date will only return the number of hours + * of the current day (resulting in a number between 0 and 23). This + * method will retrieve the number of hours for any fragment. + * For example, if you want to calculate the number of hours past this month, + * your fragment is Calendar.MONTH. The result will be all hours of the + * past day(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a HOUR field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInHours(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.HOURS);
+ }
+
+ /**
+ * Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.
+ * + *Asking the days of any date will only return the number of days + * of the current month (resulting in a number between 1 and 31). This + * method will retrieve the number of days for any fragment. + * For example, if you want to calculate the number of days past this year, + * your fragment is Calendar.YEAR. The result will be all days of the + * past month(s).
+ * + *Valid fragments are: Calendar.YEAR, Calendar.MONTH, both + * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND + * A fragment less than or equal to a DAY field will return 0.
+ * + *null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ public static long getFragmentInDays(final Calendar calendar, final int fragment) {
+ return getFragment(calendar, fragment, TimeUnit.DAYS);
+ }
+
+ /**
+ * Gets a Date fragment for any unit.
+ *
+ * @param date the date to work with, not null
+ * @param fragment the Calendar field part of date to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the date
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Date date, final int fragment, final TimeUnit unit) {
+ if(date == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+ final Calendar calendar = Calendar.getInstance();
+ calendar.setTime(date);
+ return getFragment(calendar, fragment, unit);
+ }
+
+ /**
+ * Gets a Calendar fragment for any unit.
+ *
+ * @param calendar the calendar to work with, not null
+ * @param fragment the Calendar field part of calendar to calculate
+ * @param unit the time unit
+ * @return number of units within the fragment of the calendar
+ * @throws IllegalArgumentException if the date is null or
+ * fragment is not supported
+ * @since 2.4
+ */
+ private static long getFragment(final Calendar calendar, final int fragment, final TimeUnit unit) {
+ if(calendar == null) {
+ throw new IllegalArgumentException("The date must not be null");
+ }
+
+ long result = 0;
+
+ final int offset = (unit == TimeUnit.DAYS) ? 0 : 1;
+
+ // Fragments bigger than a day require a breakdown to days
+ switch (fragment) {
+ case Calendar.YEAR:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_YEAR) - offset, TimeUnit.DAYS);
+ break;
+ case Calendar.MONTH:
+ result += unit.convert(calendar.get(Calendar.DAY_OF_MONTH) - offset, TimeUnit.DAYS);
+ break;
+ default:
+ break;
+ }
+
+ switch (fragment) {
+ // Number of days already calculated for these cases
+ case Calendar.YEAR:
+ case Calendar.MONTH:
+
+ // The rest of the valid cases
+ case Calendar.DAY_OF_YEAR:
+ case Calendar.DATE:
+ result += unit.convert(calendar.get(Calendar.HOUR_OF_DAY), TimeUnit.HOURS);
+ //$FALL-THROUGH$
+ case Calendar.HOUR_OF_DAY:
+ result += unit.convert(calendar.get(Calendar.MINUTE), TimeUnit.MINUTES);
+ //$FALL-THROUGH$
+ case Calendar.MINUTE:
+ result += unit.convert(calendar.get(Calendar.SECOND), TimeUnit.SECONDS);
+ //$FALL-THROUGH$
+ case Calendar.SECOND:
+ result += unit.convert(calendar.get(Calendar.MILLISECOND), TimeUnit.MILLISECONDS);
+ break;
+ case Calendar.MILLISECOND: break;//never useful
+ default: throw new IllegalArgumentException("The fragment " + fragment + " is not supported");
+ }
+ return result;
+ }
+
+ /**
+ * Determines if two calendars are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedEquals(Date, Date, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Calendar cal1, final Calendar cal2, final int field) {
+ return truncatedCompareTo(cal1, cal2, field) == 0;
+ }
+
+ /**
+ * Determines if two dates are equal up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from {@code Calendar}
+ * @return true if equal; otherwise false
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Date, int)
+ * @see #truncatedEquals(Calendar, Calendar, int)
+ * @since 3.0
+ */
+ public static boolean truncatedEquals(final Date date1, final Date date2, final int field) {
+ return truncatedCompareTo(date1, date2, field) == 0;
+ }
+
+ /**
+ * Determines how two calendars compare up to no more than the specified
+ * most significant field.
+ *
+ * @param cal1 the first calendar, not null
+ * @param cal2 the second calendar, not null
+ * @param field the field from {@code Calendar}
+ * @return a negative integer, zero, or a positive integer as the first
+ * calendar is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Calendar cal1, final Calendar cal2, final int field) {
+ final Calendar truncatedCal1 = truncate(cal1, field);
+ final Calendar truncatedCal2 = truncate(cal2, field);
+ return truncatedCal1.compareTo(truncatedCal2);
+ }
+
+ /**
+ * Determines how two dates compare up to no more than the specified
+ * most significant field.
+ *
+ * @param date1 the first date, not null
+ * @param date2 the second date, not null
+ * @param field the field from Calendar
+ * @return a negative integer, zero, or a positive integer as the first
+ * date is less than, equal to, or greater than the second.
+ * @throws IllegalArgumentException if any argument is null
+ * @see #truncate(Calendar, int)
+ * @see #truncatedCompareTo(Date, Date, int)
+ * @since 3.0
+ */
+ public static int truncatedCompareTo(final Date date1, final Date date2, final int field) {
+ final Date truncatedDate1 = truncate(date1, field);
+ final Date truncatedDate2 = truncate(date2, field);
+ return truncatedDate1.compareTo(truncatedDate2);
+ }
+
+
+ //-----------------------------------------------------------------------
+ /**
+ * Date iterator.
+ */ + static class DateIterator implements Iteratortrue if the iterator has yet to reach the end date
+ */
+ @Override
+ public boolean hasNext() {
+ return spot.before(endFinal);
+ }
+
+ /**
+ * Return the next calendar in the iteration
+ *
+ * @return Object calendar for the next date
+ */
+ @Override
+ public Calendar next() {
+ if (spot.equals(endFinal)) {
+ throw new NoSuchElementException();
+ }
+ spot.add(Calendar.DATE, 1);
+ return (Calendar) spot.clone();
+ }
+
+ /**
+ * Always throws UnsupportedOperationException.
+ *
+ * @throws UnsupportedOperationException
+ * @see java.util.Iterator#remove()
+ */
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+}
diff --git a/Java/commons-lang-DateUtils_946/metadata.json b/Java/commons-lang-DateUtils_946/metadata.json
new file mode 100644
index 000000000..25069ed11
--- /dev/null
+++ b/Java/commons-lang-DateUtils_946/metadata.json
@@ -0,0 +1,21 @@
+{
+ "language": "java",
+ "id": "commons-lang-DateUtils_946",
+ "buggyPath": ".",
+ "referencePath": null,
+ "buildCommand": "mvn package -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100 -DskipTests=true -DskipITs=true -Dtest=None -DfailIfNoTests=false",
+ "testCommand": "mvn test -V -B -Denforcer.skip=true -Dcheckstyle.skip=true -Dcobertura.skip=true -Drat.skip=true -Dlicense.skip=true -Dfindbugs.skip=true -Dgpg.skip=true -Dskip.npm=true -Dskip.gulp=true -Dskip.bower=true -Drat.numUnapprovedLicenses=100",
+ "categories": [
+ "safety",
+ "npe"
+ ],
+ "npe": {
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 970,
+ "npe_method": "ceiling",
+ "deref_field": "date",
+ "npe_class": "DateUtils",
+ "repo": "commons-lang",
+ "bug_id": "DateUtils_946"
+ }
+}
diff --git a/Java/commons-lang-DateUtils_946/npe.json b/Java/commons-lang-DateUtils_946/npe.json
new file mode 100644
index 000000000..654d98355
--- /dev/null
+++ b/Java/commons-lang-DateUtils_946/npe.json
@@ -0,0 +1,7 @@
+{
+ "filepath": "src/main/java/org/apache/commons/lang3/time/DateUtils.java",
+ "line": 970,
+ "npe_method": "ceiling",
+ "deref_field": "date",
+ "npe_class": "DateUtils"
+}
\ No newline at end of file
diff --git a/Java/commons-lang-DefaultExceptionContext_129/Dockerfile b/Java/commons-lang-DefaultExceptionContext_129/Dockerfile
new file mode 100644
index 000000000..7b7fbe349
--- /dev/null
+++ b/Java/commons-lang-DefaultExceptionContext_129/Dockerfile
@@ -0,0 +1,18 @@
+FROM ghcr.io/kupl/starlab-benchmarks/java-base:commons-lang
+
+ENV TZ=Asia/Seoul
+
+COPY ./metadata.json .
+COPY ./npe.json .
+COPY ./buggy.java /tmp/buggy.java
+RUN export BUGGY_PATH=$(cat metadata.json | jq -r ".npe.filepath") \
+ && export BUGGY_LINE=$(cat metadata.json | jq -r ".npe.line") \
+ && export BUGGY_MTHD=$(cat metadata.json | jq -r ".npe.npe_method") \
+ && mv /tmp/buggy.java $BUGGY_PATH \
+ && echo "[{\"filepath\": \"$BUGGY_PATH\", \"line\": $BUGGY_LINE, \"method_name\": \"$BUGGY_MTHD\"}]" | jq . > traces.json
+
+RUN git init . && git add -A
+
+RUN $(cat metadata.json | jq -r ".buildCommand")
+
+RUN $(cat metadata.json | jq -r ".testCommand"); if [ $? -eq 0 ]; then exit 1; fi
diff --git a/Java/commons-lang-DefaultExceptionContext_129/buggy.java b/Java/commons-lang-DefaultExceptionContext_129/buggy.java
new file mode 100644
index 000000000..dea4c445b
--- /dev/null
+++ b/Java/commons-lang-DefaultExceptionContext_129/buggy.java
@@ -0,0 +1,171 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3.exception;
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Set;
+
+import org.apache.commons.lang3.StringUtils;
+import org.apache.commons.lang3.tuple.ImmutablePair;
+import org.apache.commons.lang3.tuple.Pair;
+
+/**
+ * Default implementation of the context storing the label-value pairs for contexted exceptions.
+ * + * This implementation is serializable, however this is dependent on the values that + * are added also being serializable. + *
+ * + * @see ContextedException + * @see ContextedRuntimeException + * @since 3.0 + */ +public class DefaultExceptionContext implements ExceptionContext, Serializable { + + /** The serialization version. */ + private static final long serialVersionUID = 20110706L; + + /** The list storing the label-data pairs. */ + private final List