    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.lang3.time;
    018
    019import java.text.ParseException;
    020import java.text.ParsePosition;
    021import java.util.Calendar;
    022import java.util.Date;
    023import java.util.Iterator;
    024import java.util.Locale;
    025import java.util.NoSuchElementException;
    026import java.util.Objects;
    027import java.util.TimeZone;
    028import java.util.concurrent.TimeUnit;
    029
    030import org.apache.commons.lang3.LocaleUtils;
    031
    032/**
    033 * A suite of utilities surrounding the use of the
    034 * {@link java.util.Calendar} and {@link java.util.Date} object.
    035 *
    036 * <p>DateUtils contains a lot of common methods considering manipulations
    037 * of Dates or Calendars. Some methods require some extra explanation.
    038 * The truncate, ceiling and round methods could be considered the Math.floor(),
    039 * Math.ceil() or Math.round versions for dates
    040 * This way date-fields will be ignored in bottom-up order.
    041 * As a complement to these methods we've introduced some fragment-methods.
    042 * With these methods the Date-fields will be ignored in top-down order.
    043 * Since a date without a year is not a valid date, you have to decide in what
    044 * kind of date-field you want your result, for instance milliseconds or days.
    045 * </p>
    046 * <p>
    047 * Several methods are provided for adding to {@link Date} objects, of the form
    048 * {@code addXXX(Date date, int amount)}. It is important to note these methods
    049 * use a {@link Calendar} internally (with default time zone and locale) and may
    050 * be affected by changes to daylight saving time (DST).
    051 * </p>
    052 *
    053 * @since 2.0
    054 */
    055public class DateUtils {
    056
    057    /**
    058     * Number of milliseconds in a standard second.
    059     * @since 2.1
    060     */
    061    public static final long MILLIS_PER_SECOND = 1000;
    062    /**
    063     * Number of milliseconds in a standard minute.
    064     * @since 2.1
    065     */
    066    public static final long MILLIS_PER_MINUTE = 60 * MILLIS_PER_SECOND;
    067    /**
    068     * Number of milliseconds in a standard hour.
    069     * @since 2.1
    070     */
    071    public static final long MILLIS_PER_HOUR = 60 * MILLIS_PER_MINUTE;
    072    /**
    073     * Number of milliseconds in a standard day.
    074     * @since 2.1
    075     */
    076    public static final long MILLIS_PER_DAY = 24 * MILLIS_PER_HOUR;
    077
    078    /**
    079     * This is half a month, so this represents whether a date is in the top
    080     * or bottom half of the month.
    081     */
    082    public static final int SEMI_MONTH = 1001;
    083
    084    private static final int[][] fields = {
    085            {Calendar.MILLISECOND},
    086            {Calendar.SECOND},
    087            {Calendar.MINUTE},
    088            {Calendar.HOUR_OF_DAY, Calendar.HOUR},
    089            {Calendar.DATE, Calendar.DAY_OF_MONTH, Calendar.AM_PM
    090                /* Calendar.DAY_OF_YEAR, Calendar.DAY_OF_WEEK, Calendar.DAY_OF_WEEK_IN_MONTH */
    091            },
    092            {Calendar.MONTH, SEMI_MONTH},
    093            {Calendar.YEAR},
    094            {Calendar.ERA}};
    095
    096    /**
    097     * A week range, starting on Sunday.
    098     */
    099    public static final int RANGE_WEEK_SUNDAY = 1;
    100    /**
    101     * A week range, starting on Monday.
    102     */
    103    public static final int RANGE_WEEK_MONDAY = 2;
    104    /**
    105     * A week range, starting on the day focused.
    106     */
    107    public static final int RANGE_WEEK_RELATIVE = 3;
    108    /**
    109     * A week range, centered around the day focused.
    110     */
    111    public static final int RANGE_WEEK_CENTER = 4;
    112    /**
    113     * A month range, the week starting on Sunday.
    114     */
    115    public static final int RANGE_MONTH_SUNDAY = 5;
    116    /**
    117     * A month range, the week starting on Monday.
    118     */
    119    public static final int RANGE_MONTH_MONDAY = 6;
    120
    121    /**
    122     * Calendar modification types.
    123     */
    124    private enum ModifyType {
    125        /**
    126         * Truncation.
    127         */
    128        TRUNCATE,
    129
    130        /**
    131         * Rounding.
    132         */
    133        ROUND,
    134
    135        /**
    136         * Ceiling.
    137         */
    138        CEILING
    139    }
    140
    141    /**
    142     * {@link DateUtils} instances should NOT be constructed in
    143     * standard programming. Instead, the static methods on the class should
    144     * be used, such as {@code DateUtils.parseDate(str);}.
    145     *
    146     * <p>This constructor is public to permit tools that require a JavaBean
    147     * instance to operate.</p>
    148     */
    149    public DateUtils() {
    150    }
    151
    152    /**
    153     * Checks if two date objects are on the same day ignoring time.
    154     *
    155     * <p>28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true.
    156     * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false.
    157     * </p>
    158     *
    159     * @param date1  the first date, not altered, not null
    160     * @param date2  the second date, not altered, not null
    161     * @return true if they represent the same day
    162     * @throws NullPointerException if either date is {@code null}
    163     * @since 2.1
    164     */
    165    public static boolean isSameDay(final Date date1, final Date date2) {
    166        return isSameDay(toCalendar(date1), toCalendar(date2));
    167    }
    168
    169    /**
    170     * Checks if two calendar objects are on the same day ignoring time.
    171     *
    172     * <p>28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true.
    173     * 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false.
    174     * </p>
    175     *
    176     * @param cal1  the first calendar, not altered, not null
    177     * @param cal2  the second calendar, not altered, not null
    178     * @return true if they represent the same day
    179     * @throws NullPointerException if either calendar is {@code null}
    180     * @since 2.1
    181     */
    182    public static boolean isSameDay(final Calendar cal1, final Calendar cal2) {
    183        Objects.requireNonNull(cal1, "cal1");
    184        Objects.requireNonNull(cal2, "cal2");
    185        return cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
    186                cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
    187                cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR);
    188    }
    189
    190    /**
    191     * Checks if two date objects represent the same instant in time.
    192     *
    193     * <p>This method compares the long millisecond time of the two objects.</p>
    194     *
    195     * @param date1  the first date, not altered, not null
    196     * @param date2  the second date, not altered, not null
    197     * @return true if they represent the same millisecond instant
    198     * @throws NullPointerException if either date is {@code null}
    199     * @since 2.1
    200     */
    201    public static boolean isSameInstant(final Date date1, final Date date2) {
    202        Objects.requireNonNull(date1, "date1");
    203        Objects.requireNonNull(date2, "date2");
    204        return date1.getTime() == date2.getTime();
    205    }
    206
    207    /**
    208     * Checks if two calendar objects represent the same instant in time.
    209     *
    210     * <p>This method compares the long millisecond time of the two objects.</p>
    211     *
    212     * @param cal1  the first calendar, not altered, not null
    213     * @param cal2  the second calendar, not altered, not null
    214     * @return true if they represent the same millisecond instant
    215     * @throws NullPointerException if either date is {@code null}
    216     * @since 2.1
    217     */
    218    public static boolean isSameInstant(final Calendar cal1, final Calendar cal2) {
    219        Objects.requireNonNull(cal1, "cal1");
    220        Objects.requireNonNull(cal2, "cal2");
    221        return cal1.getTime().getTime() == cal2.getTime().getTime();
    222    }
    223
    224    /**
    225     * Checks if two calendar objects represent the same local time.
    226     *
    227     * <p>This method compares the values of the fields of the two objects.
    228     * In addition, both calendars must be the same of the same type.</p>
    229     *
    230     * @param cal1  the first calendar, not altered, not null
    231     * @param cal2  the second calendar, not altered, not null
    232     * @return true if they represent the same millisecond instant
    233     * @throws NullPointerException if either date is {@code null}
    234     * @since 2.1
    235     */
    236    public static boolean isSameLocalTime(final Calendar cal1, final Calendar cal2) {
    237        Objects.requireNonNull(cal1, "cal1");
    238        Objects.requireNonNull(cal2, "cal2");
    239        return cal1.get(Calendar.MILLISECOND) == cal2.get(Calendar.MILLISECOND) &&
    240                cal1.get(Calendar.SECOND) == cal2.get(Calendar.SECOND) &&
    241                cal1.get(Calendar.MINUTE) == cal2.get(Calendar.MINUTE) &&
    242                cal1.get(Calendar.HOUR_OF_DAY) == cal2.get(Calendar.HOUR_OF_DAY) &&
    243                cal1.get(Calendar.DAY_OF_YEAR) == cal2.get(Calendar.DAY_OF_YEAR) &&
    244                cal1.get(Calendar.YEAR) == cal2.get(Calendar.YEAR) &&
    245                cal1.get(Calendar.ERA) == cal2.get(Calendar.ERA) &&
    246                cal1.getClass() == cal2.getClass();
    247    }
    248
    249    /**
    250     * Parses a string representing a date by trying a variety of different parsers.
    251     *
    252     * <p>The parse will try each parse pattern in turn.
    253     * A parse is only deemed successful if it parses the whole of the input string.
    254     * If no parse patterns match, a ParseException is thrown.</p>
    255     * The parser will be lenient toward the parsed date.
    256     *
    257     * @param str  the date to parse, not null
    258     * @param parsePatterns  the date format patterns to use, see SimpleDateFormat, not null
    259     * @return the parsed date
    260     * @throws NullPointerException if the date string or pattern array is null
    261     * @throws ParseException if none of the date patterns were suitable (or there were none)
    262     */
    263    public static Date parseDate(final String str, final String... parsePatterns) throws ParseException {
    264        return parseDate(str, null, parsePatterns);
    265    }
    266
    267    /**
    268     * Parses a string representing a date by trying a variety of different parsers,
    269     * using the default date format symbols for the given locale.
    270     *
    271     * <p>The parse will try each parse pattern in turn.
    272     * A parse is only deemed successful if it parses the whole of the input string.
    273     * If no parse patterns match, a ParseException is thrown.</p>
    274     * The parser will be lenient toward the parsed date.
    275     *
    276     * @param str  the date to parse, not null
    277     * @param locale the locale whose date format symbols should be used. If {@code null},
    278     * the system locale is used (as per {@link #parseDate(String, String...)}).
    279     * @param parsePatterns  the date format patterns to use, see SimpleDateFormat, not null
    280     * @return the parsed date
    281     * @throws NullPointerException if the date string or pattern array is null
    282     * @throws ParseException if none of the date patterns were suitable (or there were none)
    283     * @since 3.2
    284     */
    285    public static Date parseDate(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
    286        return parseDateWithLeniency(str, locale, parsePatterns, true);
    287    }
    288
    289    /**
    290     * Parses a string representing a date by trying a variety of different parsers.
    291     *
    292     * <p>The parse will try each parse pattern in turn.
    293     * A parse is only deemed successful if it parses the whole of the input string.
    294     * If no parse patterns match, a ParseException is thrown.</p>
    295     * The parser parses strictly - it does not allow for dates such as "February 942, 1996".
    296     *
    297     * @param str  the date to parse, not null
    298     * @param parsePatterns  the date format patterns to use, see SimpleDateFormat, not null
    299     * @return the parsed date
    300     * @throws NullPointerException if the date string or pattern array is null
    301     * @throws ParseException if none of the date patterns were suitable
    302     * @since 2.5
    303     */
    304    public static Date parseDateStrictly(final String str, final String... parsePatterns) throws ParseException {
    305        return parseDateStrictly(str, null, parsePatterns);
    306    }
    307
    308    /**
    309     * Parses a string representing a date by trying a variety of different parsers,
    310     * using the default date format symbols for the given locale..
    311     *
    312     * <p>The parse will try each parse pattern in turn.
    313     * A parse is only deemed successful if it parses the whole of the input string.
    314     * If no parse patterns match, a ParseException is thrown.</p>
    315     * The parser parses strictly - it does not allow for dates such as "February 942, 1996".
    316     *
    317     * @param str  the date to parse, not null
    318     * @param locale the locale whose date format symbols should be used. If {@code null},
    319     * the system locale is used (as per {@link #parseDateStrictly(String, String...)}).
    320     * @param parsePatterns  the date format patterns to use, see SimpleDateFormat, not null
    321     * @return the parsed date
    322     * @throws NullPointerException if the date string or pattern array is null
    323     * @throws ParseException if none of the date patterns were suitable
    324     * @since 3.2
    325     */
    326    public static Date parseDateStrictly(final String str, final Locale locale, final String... parsePatterns) throws ParseException {
    327        return parseDateWithLeniency(str, locale, parsePatterns, false);
    328    }
    329
    330    /**
    331     * Parses a string representing a date by trying a variety of different parsers.
    332     *
    333     * <p>The parse will try each parse pattern in turn.
    334     * A parse is only deemed successful if it parses the whole of the input string.
    335     * If no parse patterns match, a ParseException is thrown.</p>
    336     *
    337     * @param dateStr  the date to parse, not null
    338     * @param locale the locale to use when interpreting the pattern, can be null in which
    339     * case the default system locale is used
    340     * @param parsePatterns  the date format patterns to use, see SimpleDateFormat, not null
    341     * @param lenient Specify whether or not date/time parsing is to be lenient.
    342     * @return the parsed date
    343     * @throws NullPointerException if the date string or pattern array is null
    344     * @throws ParseException if none of the date patterns were suitable
    345     * @see java.util.Calendar#isLenient()
    346     */
    347    private static Date parseDateWithLeniency(final String dateStr, final Locale locale, final String[] parsePatterns,
    348        final boolean lenient) throws ParseException {
    349        Objects.requireNonNull(dateStr, "str");
    350        Objects.requireNonNull(parsePatterns, "parsePatterns");
    351
    352        final TimeZone tz = TimeZone.getDefault();
    353        final Locale lcl = LocaleUtils.toLocale(locale);
    354        final ParsePosition pos = new ParsePosition(0);
    355        final Calendar calendar = Calendar.getInstance(tz, lcl);
    356        calendar.setLenient(lenient);
    357
    358        for (final String parsePattern : parsePatterns) {
    359            final FastDateParser fdp = new FastDateParser(parsePattern, tz, lcl);
    360            calendar.clear();
    361            try {
    362                if (fdp.parse(dateStr, pos, calendar) && pos.getIndex() == dateStr.length()) {
    363                    return calendar.getTime();
    364                }
    365            } catch (final IllegalArgumentException ignored) {
    366                // leniency is preventing calendar from being set
    367            }
    368            pos.setIndex(0);
    369        }
    370        throw new ParseException("Unable to parse the date: " + dateStr, -1);
    371    }
    372
    373    /**
    374     * Adds a number of years to a date returning a new object.
    375     * The original {@link Date} is unchanged.
    376     *
    377     * @param date  the date, not null
    378     * @param amount  the amount to add, may be negative
    379     * @return the new {@link Date} with the amount added
    380     * @throws NullPointerException if the date is null
    381     */
    382    public static Date addYears(final Date date, final int amount) {
    383        return add(date, Calendar.YEAR, amount);
    384    }
    385
    386    /**
    387     * Adds a number of months to a date returning a new object.
    388     * The original {@link Date} is unchanged.
    389     *
    390     * @param date  the date, not null
    391     * @param amount  the amount to add, may be negative
    392     * @return the new {@link Date} with the amount added
    393     * @throws NullPointerException if the date is null
    394     */
    395    public static Date addMonths(final Date date, final int amount) {
    396        return add(date, Calendar.MONTH, amount);
    397    }
    398
    399    /**
    400     * Adds a number of weeks to a date returning a new object.
    401     * The original {@link Date} is unchanged.
    402     *
    403     * @param date  the date, not null
    404     * @param amount  the amount to add, may be negative
    405     * @return the new {@link Date} with the amount added
    406     * @throws NullPointerException if the date is null
    407     */
    408    public static Date addWeeks(final Date date, final int amount) {
    409        return add(date, Calendar.WEEK_OF_YEAR, amount);
    410    }
    411
    412    /**
    413     * Adds a number of days to a date returning a new object.
    414     * The original {@link Date} is unchanged.
    415     *
    416     * @param date  the date, not null
    417     * @param amount  the amount to add, may be negative
    418     * @return the new {@link Date} with the amount added
    419     * @throws NullPointerException if the date is null
    420     */
    421    public static Date addDays(final Date date, final int amount) {
    422        return add(date, Calendar.DAY_OF_MONTH, amount);
    423    }
    424
    425    /**
    426     * Adds a number of hours to a date returning a new object.
    427     * The original {@link Date} is unchanged.
    428     *
    429     * @param date  the date, not null
    430     * @param amount  the amount to add, may be negative
    431     * @return the new {@link Date} with the amount added
    432     * @throws NullPointerException if the date is null
    433     */
    434    public static Date addHours(final Date date, final int amount) {
    435        return add(date, Calendar.HOUR_OF_DAY, amount);
    436    }
    437
    438    /**
    439     * Adds a number of minutes to a date returning a new object.
    440     * The original {@link Date} is unchanged.
    441     *
    442     * @param date  the date, not null
    443     * @param amount  the amount to add, may be negative
    444     * @return the new {@link Date} with the amount added
    445     * @throws NullPointerException if the date is null
    446     */
    447    public static Date addMinutes(final Date date, final int amount) {
    448        return add(date, Calendar.MINUTE, amount);
    449    }
    450
    451    /**
    452     * Adds a number of seconds to a date returning a new object.
    453     * The original {@link Date} is unchanged.
    454     *
    455     * @param date  the date, not null
    456     * @param amount  the amount to add, may be negative
    457     * @return the new {@link Date} with the amount added
    458     * @throws NullPointerException if the date is null
    459     */
    460    public static Date addSeconds(final Date date, final int amount) {
    461        return add(date, Calendar.SECOND, amount);
    462    }
    463
    464    /**
    465     * Adds a number of milliseconds to a date returning a new object.
    466     * The original {@link Date} is unchanged.
    467     *
    468     * @param date  the date, not null
    469     * @param amount  the amount to add, may be negative
    470     * @return the new {@link Date} with the amount added
    471     * @throws NullPointerException if the date is null
    472     */
    473    public static Date addMilliseconds(final Date date, final int amount) {
    474        return add(date, Calendar.MILLISECOND, amount);
    475    }
    476
    477    /**
    478     * Adds to a date returning a new object.
    479     * The original {@link Date} is unchanged.
    480     *
    481     * @param date  the date, not null
    482     * @param calendarField  the calendar field to add to
    483     * @param amount  the amount to add, may be negative
    484     * @return the new {@link Date} with the amount added
    485     * @throws NullPointerException if the date is null
    486     */
    487    private static Date add(final Date date, final int calendarField, final int amount) {
    488        validateDateNotNull(date);
    489        final Calendar c = Calendar.getInstance();
    490        c.setTime(date);
    491        c.add(calendarField, amount);
    492        return c.getTime();
    493    }
    494
    495    /**
    496     * Sets the years field to a date returning a new object.
    497     * The original {@link Date} is unchanged.
    498     *
    499     * @param date  the date, not null
    500     * @param amount the amount to set
    501     * @return a new {@link Date} set with the specified value
    502     * @throws NullPointerException if the date is null
    503     * @since 2.4
    504     */
    505    public static Date setYears(final Date date, final int amount) {
    506        return set(date, Calendar.YEAR, amount);
    507    }
    508
    509    /**
    510     * Sets the months field to a date returning a new object.
    511     * The original {@link Date} is unchanged.
    512     *
    513     * @param date  the date, not null
    514     * @param amount the amount to set
    515     * @return a new {@link Date} set with the specified value
    516     * @throws NullPointerException if the date is null
    517     * @throws IllegalArgumentException if {@code amount} is not in the range
    518     *  {@code 0 <= amount <= 11}
    519     * @since 2.4
    520     */
    521    public static Date setMonths(final Date date, final int amount) {
    522        return set(date, Calendar.MONTH, amount);
    523    }
    524
    525    /**
    526     * Sets the day of month field to a date returning a new object.
    527     * The original {@link Date} is unchanged.
    528     *
    529     * @param date  the date, not null
    530     * @param amount the amount to set
    531     * @return a new {@link Date} set with the specified value
    532     * @throws NullPointerException if the date is null
    533     * @throws IllegalArgumentException if {@code amount} is not in the range
    534     *  {@code 1 <= amount <= 31}
    535     * @since 2.4
    536     */
    537    public static Date setDays(final Date date, final int amount) {
    538        return set(date, Calendar.DAY_OF_MONTH, amount);
    539    }
    540
    541    /**
    542     * Sets the hours field to a date returning a new object.  Hours range
    543     * from  0-23.
    544     * The original {@link Date} is unchanged.
    545     *
    546     * @param date  the date, not null
    547     * @param amount the amount to set
    548     * @return a new {@link Date} set with the specified value
    549     * @throws NullPointerException if the date is null
    550     * @throws IllegalArgumentException if {@code amount} is not in the range
    551     *  {@code 0 <= amount <= 23}
    552     * @since 2.4
    553     */
    554    public static Date setHours(final Date date, final int amount) {
    555        return set(date, Calendar.HOUR_OF_DAY, amount);
    556    }
    557
    558    /**
    559     * Sets the minute field to a date returning a new object.
    560     * The original {@link Date} is unchanged.
    561     *
    562     * @param date  the date, not null
    563     * @param amount the amount to set
    564     * @return a new {@link Date} set with the specified value
    565     * @throws NullPointerException if the date is null
    566     * @throws IllegalArgumentException if {@code amount} is not in the range
    567     *  {@code 0 <= amount <= 59}
    568     * @since 2.4
    569     */
    570    public static Date setMinutes(final Date date, final int amount) {
    571        return set(date, Calendar.MINUTE, amount);
    572    }
    573
    574    /**
    575     * Sets the seconds field to a date returning a new object.
    576     * The original {@link Date} is unchanged.
    577     *
    578     * @param date  the date, not null
    579     * @param amount the amount to set
    580     * @return a new {@link Date} set with the specified value
    581     * @throws NullPointerException if the date is null
    582     * @throws IllegalArgumentException if {@code amount} is not in the range
    583     *  {@code 0 <= amount <= 59}
    584     * @since 2.4
    585     */
    586    public static Date setSeconds(final Date date, final int amount) {
    587        return set(date, Calendar.SECOND, amount);
    588    }
    589
    590    /**
    591     * Sets the milliseconds field to a date returning a new object.
    592     * The original {@link Date} is unchanged.
    593     *
    594     * @param date  the date, not null
    595     * @param amount the amount to set
    596     * @return a new {@link Date} set with the specified value
    597     * @throws NullPointerException if the date is null
    598     * @throws IllegalArgumentException if {@code amount} is not in the range
    599     *  {@code 0 <= amount <= 999}
    600     * @since 2.4
    601     */
    602    public static Date setMilliseconds(final Date date, final int amount) {
    603        return set(date, Calendar.MILLISECOND, amount);
    604    }
    605
    606    /**
    607     * Sets the specified field to a date returning a new object.
    608     * This does not use a lenient calendar.
    609     * The original {@link Date} is unchanged.
    610     *
    611     * @param date  the date, not null
    612     * @param calendarField  the {@link Calendar} field to set the amount to
    613     * @param amount the amount to set
    614     * @return a new {@link Date} set with the specified value
    615     * @throws NullPointerException if the date is null
    616     * @since 2.4
    617     */
    618    private static Date set(final Date date, final int calendarField, final int amount) {
    619        validateDateNotNull(date);
    620        // getInstance() returns a new object, so this method is thread safe.
    621        final Calendar c = Calendar.getInstance();
    622        c.setLenient(false);
    623        c.setTime(date);
    624        c.set(calendarField, amount);
    625        return c.getTime();
    626    }
    627
    628    /**
    629     * Converts a {@link Date} into a {@link Calendar}.
    630     *
    631     * @param date the date to convert to a Calendar
    632     * @return the created Calendar
    633     * @throws NullPointerException if null is passed in
    634     * @since 3.0
    635     */
    636    public static Calendar toCalendar(final Date date) {
    637        final Calendar c = Calendar.getInstance();
    638        c.setTime(Objects.requireNonNull(date, "date"));
    639        return c;
    640    }
    641
    642    /**
    643     * Converts a {@link Date} of a given {@link TimeZone} into a {@link Calendar}
    644     * @param date the date to convert to a Calendar
    645     * @param tz the time zone of the {@code date}
    646     * @return the created Calendar
    647     * @throws NullPointerException if {@code date} or {@code tz} is null
    648     */
    649    public static Calendar toCalendar(final Date date, final TimeZone tz) {
    650        final Calendar c = Calendar.getInstance(tz);
    651        c.setTime(Objects.requireNonNull(date, "date"));
    652        return c;
    653    }
    654
    655    /**
    656     * Rounds a date, leaving the field specified as the most
    657     * significant field.
    658     *
    659     * <p>For example, if you had the date-time of 28 Mar 2002
    660     * 13:45:01.231, if this was passed with HOUR, it would return
    661     * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it
    662     * would return 1 April 2002 0:00:00.000.</p>
    663     *
    664     * <p>For a date in a time zone that handles the change to daylight
    665     * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows.
    666     * Suppose daylight saving time begins at 02:00 on March 30. Rounding a
    667     * date that crosses this time would produce the following values:
    668     * </p>
    669     * <ul>
    670     * <li>March 30, 2003 01:10 rounds to March 30, 2003 01:00</li>
    671     * <li>March 30, 2003 01:40 rounds to March 30, 2003 03:00</li>
    672     * <li>March 30, 2003 02:10 rounds to March 30, 2003 03:00</li>
    673     * <li>March 30, 2003 02:40 rounds to March 30, 2003 04:00</li>
    674     * </ul>
    675     *
    676     * @param date  the date to work with, not null
    677     * @param field  the field from {@link Calendar} or {@code SEMI_MONTH}
    678     * @return the different rounded date, not null
    679     * @throws NullPointerException if the date is null
    680     * @throws ArithmeticException if the year is over 280 million
    681     */
    682    public static Date round(final Date date, final int field) {
    683        return modify(toCalendar(date), field, ModifyType.ROUND).getTime();
    684    }
    685
    686    /**
    687     * Rounds a date, leaving the field specified as the most
    688     * significant field.
    689     *
    690     * <p>For example, if you had the date-time of 28 Mar 2002
    691     * 13:45:01.231, if this was passed with HOUR, it would return
    692     * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it
    693     * would return 1 April 2002 0:00:00.000.</p>
    694     *
    695     * <p>For a date in a time zone that handles the change to daylight
    696     * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows.
    697     * Suppose daylight saving time begins at 02:00 on March 30. Rounding a
    698     * date that crosses this time would produce the following values:
    699     * </p>
    700     * <ul>
    701     * <li>March 30, 2003 01:10 rounds to March 30, 2003 01:00</li>
    702     * <li>March 30, 2003 01:40 rounds to March 30, 2003 03:00</li>
    703     * <li>March 30, 2003 02:10 rounds to March 30, 2003 03:00</li>
    704     * <li>March 30, 2003 02:40 rounds to March 30, 2003 04:00</li>
    705     * </ul>
    706     *
    707     * @param calendar  the date to work with, not null
    708     * @param field  the field from {@link Calendar} or {@code SEMI_MONTH}
    709     * @return the different rounded date, not null
    710     * @throws NullPointerException if the date is {@code null}
    711     * @throws ArithmeticException if the year is over 280 million
    712     */
    713    public static Calendar round(final Calendar calendar, final int field) {
    714        Objects.requireNonNull(calendar, "calendar");
    715        return modify((Calendar) calendar.clone(), field, ModifyType.ROUND);
    716    }
    717
    718    /**
    719     * Rounds a date, leaving the field specified as the most
    720     * significant field.
    721     *
    722     * <p>For example, if you had the date-time of 28 Mar 2002
    723     * 13:45:01.231, if this was passed with HOUR, it would return
    724     * 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it
    725     * would return 1 April 2002 0:00:00.000.</p>
    726     *
    727     * <p>For a date in a time zone that handles the change to daylight
    728     * saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows.
    729     * Suppose daylight saving time begins at 02:00 on March 30. Rounding a
    730     * date that crosses this time would produce the following values:
    731     * </p>
    732     * <ul>
    733     * <li>March 30, 2003 01:10 rounds to March 30, 2003 01:00</li>
    734     * <li>March 30, 2003 01:40 rounds to March 30, 2003 03:00</li>
    735     * <li>March 30, 2003 02:10 rounds to March 30, 2003 03:00</li>
    736     * <li>March 30, 2003 02:40 rounds to March 30, 2003 04:00</li>
    737     * </ul>
    738     *
    739     * @param date  the date to work with, either {@link Date} or {@link Calendar}, not null
    740     * @param field  the field from {@link Calendar} or {@code SEMI_MONTH}
    741     * @return the different rounded date, not null
    742     * @throws NullPointerException if the date is {@code null}
    743     * @throws ClassCastException if the object type is not a {@link Date} or {@link Calendar}
    744     * @throws ArithmeticException if the year is over 280 million
    745     */
    746    public static Date round(final Object date, final int field) {
    747        Objects.requireNonNull(date, "date");
    748        if (date instanceof Date) {
    749            return round((Date) date, field);
    750        }
    751        if (date instanceof Calendar) {
    752            return round((Calendar) date, field).getTime();
    753        }
    754        throw new ClassCastException("Could not round " + date);
    755    }
    756
    757    /**
    758     * Truncates a date, leaving the field specified as the most
    759     * significant field.
    760     *
    761     * <p>For example, if you had the date-time of 28 Mar 2002
    762     * 13:45:01.231, if you passed with HOUR, it would return 28 Mar
    763     * 2002 13:00:00.000.  If this was passed with MONTH, it would
    764     * return 1 Mar 2002 0:00:00.000.</p>
    765     *
    766     * @param date  the date to work with, not null
    767     * @param field  the field from {@link Calendar} or {@code SEMI_MONTH}
    768     * @return the different truncated date, not null
    769     * @throws NullPointerException if the date is {@code null}
    770     * @throws ArithmeticException if the year is over 280 million
    771     */
    772    public static Date truncate(final Date date, final int field) {
    773        return modify(toCalendar(date), field, ModifyType.TRUNCATE).getTime();
    774    }
    775
    776    /**
    777     * Truncates a date, leaving the field specified as the most
    778     * significant field.
    779     *
    780     * <p>For example, if you had the date-time of 28 Mar 2002
    781     * 13:45:01.231, if you passed with HOUR, it would return 28 Mar
    782     * 2002 13:00:00.000.  If this was passed with MONTH, it would
    783     * return 1 Mar 2002 0:00:00.000.</p>
    784     *
    785     * @param date  the date to work with, not null
    786     * @param field  the field from {@link Calendar} or {@code SEMI_MONTH}
    787     * @return the different truncated date, not null
    788     * @throws NullPointerException if the date is {@code null}
    789     * @throws ArithmeticException if the year is over 280 million
    790     */
    791    public static Calendar truncate(final Calendar date, final int field) {
    792        Objects.requireNonNull(date, "date");
    793        return modify((Calendar) date.clone(), field, ModifyType.TRUNCATE);
    794    }
    795
    796    /**
    797     * Truncates a date, leaving the field specified as the most
    798     * significant field.
    799     *
    800     * <p>For example, if you had the date-time of 28 Mar 2002
    801     * 13:45:01.231, if you passed with HOUR, it would return 28 Mar
    802     * 2002 13:00:00.000.  If this was passed with MONTH, it would
    803     * return 1 Mar 2002 0:00:00.000.</p>
    804     *
    805     * @param date  the date to work with, either {@link Date} or {@link Calendar}, not null
    806     * @param field  the field from {@link Calendar} or {@code SEMI_MONTH}
    807     * @return the different truncated date, not null
    808     * @throws NullPointerException if the date is {@code null}
    809     * @throws ClassCastException if the object type is not a {@link Date} or {@link Calendar}
    810     * @throws ArithmeticException if the year is over 280 million
    811     */
    812    public static Date truncate(final Object date, final int field) {
    813        Objects.requireNonNull(date, "date");
    814        if (date instanceof Date) {
    815            return truncate((Date) date, field);
    816        }
    817        if (date instanceof Calendar) {
    818            return truncate((Calendar) date, field).getTime();
    819        }
    820        throw new ClassCastException("Could not truncate " + date);
    821    }
    822
    823    /**
    824     * Gets a date ceiling, leaving the field specified as the most
    825     * significant field.
    826     *
    827     * <p>For example, if you had the date-time of 28 Mar 2002
    828     * 13:45:01.231, if you passed with HOUR, it would return 28 Mar
    829     * 2002 14:00:00.000.  If this was passed with MONTH, it would
    830     * return 1 Apr 2002 0:00:00.000.</p>
    831     *
    832     * @param date  the date to work with, not null
    833     * @param field  the field from {@link Calendar} or {@code SEMI_MONTH}
    834     * @return the different ceil date, not null
    835     * @throws NullPointerException if the date is {@code null}
    836     * @throws ArithmeticException if the year is over 280 million
    837     * @since 2.5
    838     */
    839    public static Date ceiling(final Date date, final int field) {
    840        return modify(toCalendar(date), field, ModifyType.CEILING).getTime();
    841    }
    842
    843    /**
    844     * Gets a date ceiling, leaving the field specified as the most
    845     * significant field.
    846     *
    847     * <p>For example, if you had the date-time of 28 Mar 2002
    848     * 13:45:01.231, if you passed with HOUR, it would return 28 Mar
    849     * 2002 14:00:00.000.  If this was passed with MONTH, it would
    850     * return 1 Apr 2002 0:00:00.000.</p>
    851     *
    852     * @param calendar  the date to work with, not null
    853     * @param field  the field from {@link Calendar} or {@code SEMI_MONTH}
    854     * @return the different ceil date, not null
    855     * @throws NullPointerException if the date is {@code null}
    856     * @throws ArithmeticException if the year is over 280 million
    857     * @since 2.5
    858     */
    859    public static Calendar ceiling(final Calendar calendar, final int field) {
    860        Objects.requireNonNull(calendar, "calendar");
    861        return modify((Calendar) calendar.clone(), field, ModifyType.CEILING);
    862    }
    863
    864    /**
    865     * Gets a date ceiling, leaving the field specified as the most
    866     * significant field.
    867     *
    868     * <p>For example, if you had the date-time of 28 Mar 2002
    869     * 13:45:01.231, if you passed with HOUR, it would return 28 Mar
    870     * 2002 14:00:00.000.  If this was passed with MONTH, it would
    871     * return 1 Apr 2002 0:00:00.000.</p>
    872     *
    873     * @param date  the date to work with, either {@link Date} or {@link Calendar}, not null
    874     * @param field  the field from {@link Calendar} or {@code SEMI_MONTH}
    875     * @return the different ceil date, not null
    876     * @throws NullPointerException if the date is {@code null}
    877     * @throws ClassCastException if the object type is not a {@link Date} or {@link Calendar}
    878     * @throws ArithmeticException if the year is over 280 million
    879     * @since 2.5
    880     */
    881    public static Date ceiling(final Object date, final int field) {
    882        Objects.requireNonNull(date, "date");
    883        if (date instanceof Date) {
    884            return ceiling((Date) date, field);
    885        }
    886        if (date instanceof Calendar) {
    887            return ceiling((Calendar) date, field).getTime();
    888        }
    889        throw new ClassCastException("Could not find ceiling of for type: " + date.getClass());
    890    }
    891
    892    /**
    893     * Internal calculation method.
    894     *
    895     * @param val  the calendar, not null
    896     * @param field  the field constant
    897     * @param modType  type to truncate, round or ceiling
    898     * @return the given calendar
    899     * @throws ArithmeticException if the year is over 280 million
    900     */
    901    private static Calendar modify(final Calendar val, final int field, final ModifyType modType) {
    902        if (val.get(Calendar.YEAR) > 280000000) {
    903            throw new ArithmeticException("Calendar value too large for accurate calculations");
    904        }
    905
    906        if (field == Calendar.MILLISECOND) {
    907            return val;
    908        }
    909
    910        // Fix for LANG-59 START
    911        // see https://issues.apache.org/jira/browse/LANG-59
    912        //
    913        // Manually truncate milliseconds, seconds and minutes, rather than using
    914        // Calendar methods.
    915
    916        final Date date = val.getTime();
    917        long time = date.getTime();
    918        boolean done = false;
    919
    920        // truncate milliseconds
    921        final int millisecs = val.get(Calendar.MILLISECOND);
    922        if (ModifyType.TRUNCATE == modType || millisecs < 500) {
    923            time = time - millisecs;
    924        }
    925        if (field == Calendar.SECOND) {
    926            done = true;
    927        }
    928
    929        // truncate seconds
    930        final int seconds = val.get(Calendar.SECOND);
    931        if (!done && (ModifyType.TRUNCATE == modType || seconds < 30)) {
    932            time = time - (seconds * 1000L);
    933        }
    934        if (field == Calendar.MINUTE) {
    935            done = true;
    936        }
    937
    938        // truncate minutes
    939        final int minutes = val.get(Calendar.MINUTE);
    940        if (!done && (ModifyType.TRUNCATE == modType || minutes < 30)) {
    941            time = time - (minutes * 60000L);
    942        }
    943
    944        // reset time
    945        if (date.getTime() != time) {
    946            date.setTime(time);
    947            val.setTime(date);
    948        }
    949        // Fix for LANG-59 END
    950
    951        boolean roundUp = false;
    952        for (final int[] aField : fields) {
    953            for (final int element : aField) {
    954                if (element == field) {
    955                    //This is our field... we stop looping
    956                    if (modType == ModifyType.CEILING || modType == ModifyType.ROUND && roundUp) {
    957                        if (field == SEMI_MONTH) {
    958                            //This is a special case that's hard to generalize
    959                            //If the date is 1, we round up to 16, otherwise
    960                            //  we subtract 15 days and add 1 month
    961                            if (val.get(Calendar.DATE) == 1) {
    962                                val.add(Calendar.DATE, 15);
    963                            } else {
    964                                val.add(Calendar.DATE, -15);
    965                                val.add(Calendar.MONTH, 1);
    966                            }
    967                        // Fix for LANG-440 START
    968                        } else if (field == Calendar.AM_PM) {
    969                            // This is a special case
    970                            // If the time is 0, we round up to 12, otherwise
    971                            //  we subtract 12 hours and add 1 day
    972                            if (val.get(Calendar.HOUR_OF_DAY) == 0) {
    973                                val.add(Calendar.HOUR_OF_DAY, 12);
    974                            } else {
    975                                val.add(Calendar.HOUR_OF_DAY, -12);
    976                                val.add(Calendar.DATE, 1);
    977                            }
    978                            // Fix for LANG-440 END
    979                        } else {
    980                            //We need at add one to this field since the
    981                            //  last number causes us to round up
    982                            val.add(aField[0], 1);
    983                        }
    984                    }
    985                    return val;
    986                }
    987            }
    988            //We have various fields that are not easy roundings
    989            int offset = 0;
    990            boolean offsetSet = false;
    991            //These are special types of fields that require different rounding rules
    992            switch (field) {
    993                case SEMI_MONTH:
    994                    if (aField[0] == Calendar.DATE) {
    995                        //If we're going to drop the DATE field's value,
    996                        //  we want to do this our own way.
    997                        //We need to subtract 1 since the date has a minimum of 1
    998                        offset = val.get(Calendar.DATE) - 1;
    999                        //If we're above 15 days adjustment, that means we're in the
    1000                        //  bottom half of the month and should stay accordingly.
    1001                        if (offset >= 15) {
    1002                            offset -= 15;
    1003                        }
    1004                        //Record whether we're in the top or bottom half of that range
    1005                        roundUp = offset > 7;
    1006                        offsetSet = true;
    1007                    }
    1008                    break;
    1009                case Calendar.AM_PM:
    1010                    if (aField[0] == Calendar.HOUR_OF_DAY) {
    1011                        //If we're going to drop the HOUR field's value,
    1012                        //  we want to do this our own way.
    1013                        offset = val.get(Calendar.HOUR_OF_DAY);
    1014                        if (offset >= 12) {
    1015                            offset -= 12;
    1016                        }
    1017                        roundUp = offset >= 6;
    1018                        offsetSet = true;
    1019                    }
    1020                    break;
    1021                default:
    1022                    break;
    1023            }
    1024            if (!offsetSet) {
    1025                final int min = val.getActualMinimum(aField[0]);
    1026                final int max = val.getActualMaximum(aField[0]);
    1027                //Calculate the offset from the minimum allowed value
    1028                offset = val.get(aField[0]) - min;
    1029                //Set roundUp if this is more than half way between the minimum and maximum
    1030                roundUp = offset > ((max - min) / 2);
    1031            }
    1032            //We need to remove this field
    1033            if (offset != 0) {
    1034                val.set(aField[0], val.get(aField[0]) - offset);
    1035            }
    1036        }
    1037        throw new IllegalArgumentException("The field " + field + " is not supported");
    1038    }
    1039
    1040    /**
    1041     * Constructs an {@link Iterator} over each day in a date
    1042     * range defined by a focus date and range style.
    1043     *
    1044     * <p>For instance, passing Thursday, July 4, 2002 and a
    1045     * {@code RANGE_MONTH_SUNDAY} will return an {@link Iterator}
    1046     * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
    1047     * 2002, returning a Calendar instance for each intermediate day.</p>
    1048     *
    1049     * <p>This method provides an iterator that returns Calendar objects.
    1050     * The days are progressed using {@link Calendar#add(int, int)}.</p>
    1051     *
    1052     * @param focus  the date to work with, not null
    1053     * @param rangeStyle  the style constant to use. Must be one of
    1054     * {@link DateUtils#RANGE_MONTH_SUNDAY},
    1055     * {@link DateUtils#RANGE_MONTH_MONDAY},
    1056     * {@link DateUtils#RANGE_WEEK_SUNDAY},
    1057     * {@link DateUtils#RANGE_WEEK_MONDAY},
    1058     * {@link DateUtils#RANGE_WEEK_RELATIVE},
    1059     * {@link DateUtils#RANGE_WEEK_CENTER}
    1060     * @return the date iterator, not null, not null
    1061     * @throws NullPointerException if the date is {@code null}
    1062     * @throws IllegalArgumentException if the rangeStyle is invalid
    1063     */
    1064    public static Iterator<Calendar> iterator(final Date focus, final int rangeStyle) {
    1065        return iterator(toCalendar(focus), rangeStyle);
    1066    }
    1067
    1068    /**
    1069     * Constructs an {@link Iterator} over each day in a date
    1070     * range defined by a focus date and range style.
    1071     *
    1072     * <p>For instance, passing Thursday, July 4, 2002 and a
    1073     * {@code RANGE_MONTH_SUNDAY} will return an {@link Iterator}
    1074     * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
    1075     * 2002, returning a Calendar instance for each intermediate day.</p>
    1076     *
    1077     * <p>This method provides an iterator that returns Calendar objects.
    1078     * The days are progressed using {@link Calendar#add(int, int)}.</p>
    1079     *
    1080     * @param calendar  the date to work with, not null
    1081     * @param rangeStyle  the style constant to use. Must be one of
    1082     * {@link DateUtils#RANGE_MONTH_SUNDAY},
    1083     * {@link DateUtils#RANGE_MONTH_MONDAY},
    1084     * {@link DateUtils#RANGE_WEEK_SUNDAY},
    1085     * {@link DateUtils#RANGE_WEEK_MONDAY},
    1086     * {@link DateUtils#RANGE_WEEK_RELATIVE},
    1087     * {@link DateUtils#RANGE_WEEK_CENTER}
    1088     * @return the date iterator, not null
    1089     * @throws NullPointerException if calendar is {@code null}
    1090     * @throws IllegalArgumentException if the rangeStyle is invalid
    1091     */
    1092    public static Iterator<Calendar> iterator(final Calendar calendar, final int rangeStyle) {
    1093        Objects.requireNonNull(calendar, "calendar");
    1094        final Calendar start;
    1095        final Calendar end;
    1096        int startCutoff = Calendar.SUNDAY;
    1097        int endCutoff = Calendar.SATURDAY;
    1098        switch (rangeStyle) {
    1099            case RANGE_MONTH_SUNDAY:
    1100            case RANGE_MONTH_MONDAY:
    1101                //Set start to the first of the month
    1102                start = truncate(calendar, Calendar.MONTH);
    1103                //Set end to the last of the month
    1104                end = (Calendar) start.clone();
    1105                end.add(Calendar.MONTH, 1);
    1106                end.add(Calendar.DATE, -1);
    1107                //Loop start back to the previous sunday or monday
    1108                if (rangeStyle == RANGE_MONTH_MONDAY) {
    1109                    startCutoff = Calendar.MONDAY;
    1110                    endCutoff = Calendar.SUNDAY;
    1111                }
    1112                break;
    1113            case RANGE_WEEK_SUNDAY:
    1114            case RANGE_WEEK_MONDAY:
    1115            case RANGE_WEEK_RELATIVE:
    1116            case RANGE_WEEK_CENTER:
    1117                //Set start and end to the current date
    1118                start = truncate(calendar, Calendar.DATE);
    1119                end = truncate(calendar, Calendar.DATE);
    1120                switch (rangeStyle) {
    1121                    case RANGE_WEEK_SUNDAY:
    1122                        //already set by default
    1123                        break;
    1124                    case RANGE_WEEK_MONDAY:
    1125                        startCutoff = Calendar.MONDAY;
    1126                        endCutoff = Calendar.SUNDAY;
    1127                        break;
    1128                    case RANGE_WEEK_RELATIVE:
    1129                        startCutoff = calendar.get(Calendar.DAY_OF_WEEK);
    1130                        endCutoff = startCutoff - 1;
    1131                        break;
    1132                    case RANGE_WEEK_CENTER:
    1133                        startCutoff = calendar.get(Calendar.DAY_OF_WEEK) - 3;
    1134                        endCutoff = calendar.get(Calendar.DAY_OF_WEEK) + 3;
    1135                        break;
    1136                    default:
    1137                        break;
    1138                }
    1139                break;
    1140            default:
    1141                throw new IllegalArgumentException("The range style " + rangeStyle + " is not valid.");
    1142        }
    1143        if (startCutoff < Calendar.SUNDAY) {
    1144            startCutoff += 7;
    1145        }
    1146        if (startCutoff > Calendar.SATURDAY) {
    1147            startCutoff -= 7;
    1148        }
    1149        if (endCutoff < Calendar.SUNDAY) {
    1150            endCutoff += 7;
    1151        }
    1152        if (endCutoff > Calendar.SATURDAY) {
    1153            endCutoff -= 7;
    1154        }
    1155        while (start.get(Calendar.DAY_OF_WEEK) != startCutoff) {
    1156            start.add(Calendar.DATE, -1);
    1157        }
    1158        while (end.get(Calendar.DAY_OF_WEEK) != endCutoff) {
    1159            end.add(Calendar.DATE, 1);
    1160        }
    1161        return new DateIterator(start, end);
    1162    }
    1163
    1164    /**
    1165     * Constructs an {@link Iterator} over each day in a date
    1166     * range defined by a focus date and range style.
    1167     *
    1168     * <p>For instance, passing Thursday, July 4, 2002 and a
    1169     * {@code RANGE_MONTH_SUNDAY} will return an {@link Iterator}
    1170     * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
    1171     * 2002, returning a Calendar instance for each intermediate day.</p>
    1172     *
    1173     * @param calendar  the date to work with, either {@link Date} or {@link Calendar}, not null
    1174     * @param rangeStyle  the style constant to use. Must be one of the range
    1175     * styles listed for the {@link #iterator(Calendar, int)} method.
    1176     * @return the date iterator, not null
    1177     * @throws NullPointerException if the date is {@code null}
    1178     * @throws ClassCastException if the object type is not a {@link Date} or {@link Calendar}
    1179     */
    1180    public static Iterator<?> iterator(final Object calendar, final int rangeStyle) {
    1181        Objects.requireNonNull(calendar, "calendar");
    1182        if (calendar instanceof Date) {
    1183            return iterator((Date) calendar, rangeStyle);
    1184        }
    1185        if (calendar instanceof Calendar) {
    1186            return iterator((Calendar) calendar, rangeStyle);
    1187        }
    1188        throw new ClassCastException("Could not iterate based on " + calendar);
    1189    }
    1190
    1191    /**
    1192     * Returns the number of milliseconds within the
    1193     * fragment. All date fields greater than the fragment will be ignored.
    1194     *
    1195     * <p>Asking the milliseconds of any date will only return the number of milliseconds
    1196     * of the current second (resulting in a number between 0 and 999). This
    1197     * method will retrieve the number of milliseconds for any fragment.
    1198     * For example, if you want to calculate the number of milliseconds past today,
    1199     * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will
    1200     * be all milliseconds of the past hour(s), minutes(s) and second(s).</p>
    1201     *
    1202     * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both
    1203     * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY,
    1204     * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND
    1205     * A fragment less than or equal to a SECOND field will return 0.</p>
    1206     *
    1207     * <ul>
    1208     *  <li>January 1, 2008 7:15:10.538 with Calendar.SECOND as fragment will return 538</li>
    1209     *  <li>January 6, 2008 7:15:10.538 with Calendar.SECOND as fragment will return 538</li>
    1210     *  <li>January 6, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10538 (10*1000 + 538)</li>
    1211     *  <li>January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0
    1212     *   (a millisecond cannot be split in milliseconds)</li>
    1213     * </ul>
    1214     *
    1215     * @param date the date to work with, not null
    1216     * @param fragment the {@link Calendar} field part of date to calculate
    1217     * @return number of milliseconds within the fragment of date
    1218     * @throws NullPointerException if the date is {@code null}
    1219     * @throws IllegalArgumentException if the fragment is not supported
    1220     * @since 2.4
    1221     */
    1222    public static long getFragmentInMilliseconds(final Date date, final int fragment) {
    1223        return getFragment(date, fragment, TimeUnit.MILLISECONDS);
    1224    }
    1225
    1226    /**
    1227     * Returns the number of seconds within the
    1228     * fragment. All date fields greater than the fragment will be ignored.
    1229     *
    1230     * <p>Asking the seconds of any date will only return the number of seconds
    1231     * of the current minute (resulting in a number between 0 and 59). This
    1232     * method will retrieve the number of seconds for any fragment.
    1233     * For example, if you want to calculate the number of seconds past today,
    1234     * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will
    1235     * be all seconds of the past hour(s) and minutes(s).</p>
    1236     *
    1237     * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both
    1238     * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY,
    1239     * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND
    1240     * A fragment less than or equal to a SECOND field will return 0.</p>
    1241     *
    1242     * <ul>
    1243     *  <li>January 1, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10
    1244     *   (equivalent to deprecated date.getSeconds())</li>
    1245     *  <li>January 6, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10
    1246     *   (equivalent to deprecated date.getSeconds())</li>
    1247     *  <li>January 6, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 26110
    1248     *   (7*3600 + 15*60 + 10)</li>
    1249     *  <li>January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0
    1250     *   (a millisecond cannot be split in seconds)</li>
    1251     * </ul>
    1252     *
    1253     * @param date the date to work with, not null
    1254     * @param fragment the {@link Calendar} field part of date to calculate
    1255     * @return number of seconds within the fragment of date
    1256     * @throws NullPointerException if the date is {@code null}
    1257     * @throws IllegalArgumentException if the fragment is not supported
    1258     * @since 2.4
    1259     */
    1260    public static long getFragmentInSeconds(final Date date, final int fragment) {
    1261        return getFragment(date, fragment, TimeUnit.SECONDS);
    1262    }
    1263
    1264    /**
    1265     * Returns the number of minutes within the
    1266     * fragment. All date fields greater than the fragment will be ignored.
    1267     *
    1268     * <p>Asking the minutes of any date will only return the number of minutes
    1269     * of the current hour (resulting in a number between 0 and 59). This
    1270     * method will retrieve the number of minutes for any fragment.
    1271     * For example, if you want to calculate the number of minutes past this month,
    1272     * your fragment is Calendar.MONTH. The result will be all minutes of the
    1273     * past day(s) and hour(s).</p>
    1274     *
    1275     * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both
    1276     * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY,
    1277     * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND
    1278     * A fragment less than or equal to a MINUTE field will return 0.</p>
    1279     *
    1280     * <ul>
    1281     *  <li>January 1, 2008 7:15:10.538 with Calendar.HOUR_OF_DAY as fragment will return 15
    1282     *   (equivalent to deprecated date.getMinutes())</li>
    1283     *  <li>January 6, 2008 7:15:10.538 with Calendar.HOUR_OF_DAY as fragment will return 15
    1284     *   (equivalent to deprecated date.getMinutes())</li>
    1285     *  <li>January 1, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 15</li>
    1286     *  <li>January 6, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 435 (7*60 + 15)</li>
    1287     *  <li>January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0
    1288     *   (a millisecond cannot be split in minutes)</li>
    1289     * </ul>
    1290     *
    1291     * @param date the date to work with, not null
    1292     * @param fragment the {@link Calendar} field part of date to calculate
    1293     * @return number of minutes within the fragment of date
    1294     * @throws NullPointerException if the date is {@code null}
    1295     * @throws IllegalArgumentException if the fragment is not supported
    1296     * @since 2.4
    1297     */
    1298    public static long getFragmentInMinutes(final Date date, final int fragment) {
    1299        return getFragment(date, fragment, TimeUnit.MINUTES);
    1300    }
    1301
    1302    /**
    1303     * Returns the number of hours within the
    1304     * fragment. All date fields greater than the fragment will be ignored.
    1305     *
    1306     * <p>Asking the hours of any date will only return the number of hours
    1307     * of the current day (resulting in a number between 0 and 23). This
    1308     * method will retrieve the number of hours for any fragment.
    1309     * For example, if you want to calculate the number of hours past this month,
    1310     * your fragment is Calendar.MONTH. The result will be all hours of the
    1311     * past day(s).</p>
    1312     *
    1313     * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both
    1314     * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY,
    1315     * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND
    1316     * A fragment less than or equal to a HOUR field will return 0.</p>
    1317     *
    1318     * <ul>
    1319     *  <li>January 1, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 7
    1320     *   (equivalent to deprecated date.getHours())</li>
    1321     *  <li>January 6, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 7
    1322     *   (equivalent to deprecated date.getHours())</li>
    1323     *  <li>January 1, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 7</li>
    1324     *  <li>January 6, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 127 (5*24 + 7)</li>
    1325     *  <li>January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0
    1326     *   (a millisecond cannot be split in hours)</li>
    1327     * </ul>
    1328     *
    1329     * @param date the date to work with, not null
    1330     * @param fragment the {@link Calendar} field part of date to calculate
    1331     * @return number of hours within the fragment of date
    1332     * @throws NullPointerException if the date is {@code null}
    1333     * @throws IllegalArgumentException if the fragment is not supported
    1334     * @since 2.4
    1335     */
    1336    public static long getFragmentInHours(final Date date, final int fragment) {
    1337        return getFragment(date, fragment, TimeUnit.HOURS);
    1338    }
    1339
    1340    /**
    1341     * Returns the number of days within the
    1342     * fragment. All date fields greater than the fragment will be ignored.
    1343     *
    1344     * <p>Asking the days of any date will only return the number of days
    1345     * of the current month (resulting in a number between 1 and 31). This
    1346     * method will retrieve the number of days for any fragment.
    1347     * For example, if you want to calculate the number of days past this year,
    1348     * your fragment is Calendar.YEAR. The result will be all days of the
    1349     * past month(s).</p>
    1350     *
    1351     * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both
    1352     * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY,
    1353     * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND
    1354     * A fragment less than or equal to a DAY field will return 0.</p>
    1355     *
    1356     * <ul>
    1357     *  <li>January 28, 2008 with Calendar.MONTH as fragment will return 28
    1358     *   (equivalent to deprecated date.getDay())</li>
    1359     *  <li>February 28, 2008 with Calendar.MONTH as fragment will return 28
    1360     *   (equivalent to deprecated date.getDay())</li>
    1361     *  <li>January 28, 2008 with Calendar.YEAR as fragment will return 28</li>
    1362     *  <li>February 28, 2008 with Calendar.YEAR as fragment will return 59</li>
    1363     *  <li>January 28, 2008 with Calendar.MILLISECOND as fragment will return 0
    1364     *   (a millisecond cannot be split in days)</li>
    1365     * </ul>
    1366     *
    1367     * @param date the date to work with, not null
    1368     * @param fragment the {@link Calendar} field part of date to calculate
    1369     * @return number of days  within the fragment of date
    1370     * @throws NullPointerException if the date is {@code null}
    1371     * @throws IllegalArgumentException if the fragment is not supported
    1372     * @since 2.4
    1373     */
    1374    public static long getFragmentInDays(final Date date, final int fragment) {
    1375        return getFragment(date, fragment, TimeUnit.DAYS);
    1376    }
    1377
    1378    /**
    1379     * Returns the number of milliseconds within the
    1380     * fragment. All date fields greater than the fragment will be ignored.
    1381     *
    1382     * <p>Asking the milliseconds of any date will only return the number of milliseconds
    1383     * of the current second (resulting in a number between 0 and 999). This
    1384     * method will retrieve the number of milliseconds for any fragment.
    1385     * For example, if you want to calculate the number of seconds past today,
    1386     * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will
    1387     * be all seconds of the past hour(s), minutes(s) and second(s).</p>
    1388     *
    1389     * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both
    1390     * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY,
    1391     * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND
    1392     * A fragment less than or equal to a MILLISECOND field will return 0.</p>
    1393     *
    1394     * <ul>
    1395     *  <li>January 1, 2008 7:15:10.538 with Calendar.SECOND as fragment will return 538
    1396     *   (equivalent to calendar.get(Calendar.MILLISECOND))</li>
    1397     *  <li>January 6, 2008 7:15:10.538 with Calendar.SECOND as fragment will return 538
    1398     *   (equivalent to calendar.get(Calendar.MILLISECOND))</li>
    1399     *  <li>January 6, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10538
    1400     *   (10*1000 + 538)</li>
    1401     *  <li>January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0
    1402     *   (a millisecond cannot be split in milliseconds)</li>
    1403     * </ul>
    1404     *
    1405     * @param calendar the calendar to work with, not null
    1406     * @param fragment the {@link Calendar} field part of calendar to calculate
    1407     * @return number of milliseconds within the fragment of date
    1408     * @throws NullPointerException if the date is {@code null} or
    1409     * fragment is not supported
    1410     * @since 2.4
    1411     */
    1412  public static long getFragmentInMilliseconds(final Calendar calendar, final int fragment) {
    1413    return getFragment(calendar, fragment, TimeUnit.MILLISECONDS);
    1414  }
    1415    /**
    1416     * Returns the number of seconds within the
    1417     * fragment. All date fields greater than the fragment will be ignored.
    1418     *
    1419     * <p>Asking the seconds of any date will only return the number of seconds
    1420     * of the current minute (resulting in a number between 0 and 59). This
    1421     * method will retrieve the number of seconds for any fragment.
    1422     * For example, if you want to calculate the number of seconds past today,
    1423     * your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will
    1424     * be all seconds of the past hour(s) and minutes(s).</p>
    1425     *
    1426     * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both
    1427     * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY,
    1428     * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND
    1429     * A fragment less than or equal to a SECOND field will return 0.</p>
    1430     *
    1431     * <ul>
    1432     *  <li>January 1, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10
    1433     *   (equivalent to calendar.get(Calendar.SECOND))</li>
    1434     *  <li>January 6, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10
    1435     *   (equivalent to calendar.get(Calendar.SECOND))</li>
    1436     *  <li>January 6, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 26110
    1437     *   (7*3600 + 15*60 + 10)</li>
    1438     *  <li>January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0
    1439     *   (a millisecond cannot be split in seconds)</li>
    1440     * </ul>
    1441     *
    1442     * @param calendar the calendar to work with, not null
    1443     * @param fragment the {@link Calendar} field part of calendar to calculate
    1444     * @return number of seconds within the fragment of date
    1445     * @throws NullPointerException if the date is {@code null} or
    1446     * fragment is not supported
    1447     * @since 2.4
    1448     */
    1449    public static long getFragmentInSeconds(final Calendar calendar, final int fragment) {
    1450        return getFragment(calendar, fragment, TimeUnit.SECONDS);
    1451    }
    1452
    1453    /**
    1454     * Returns the number of minutes within the
    1455     * fragment. All date fields greater than the fragment will be ignored.
    1456     *
    1457     * <p>Asking the minutes of any date will only return the number of minutes
    1458     * of the current hour (resulting in a number between 0 and 59). This
    1459     * method will retrieve the number of minutes for any fragment.
    1460     * For example, if you want to calculate the number of minutes past this month,
    1461     * your fragment is Calendar.MONTH. The result will be all minutes of the
    1462     * past day(s) and hour(s).</p>
    1463     *
    1464     * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both
    1465     * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY,
    1466     * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND
    1467     * A fragment less than or equal to a MINUTE field will return 0.</p>
    1468     *
    1469     * <ul>
    1470     *  <li>January 1, 2008 7:15:10.538 with Calendar.HOUR_OF_DAY as fragment will return 15
    1471     *   (equivalent to calendar.get(Calendar.MINUTES))</li>
    1472     *  <li>January 6, 2008 7:15:10.538 with Calendar.HOUR_OF_DAY as fragment will return 15
    1473     *   (equivalent to calendar.get(Calendar.MINUTES))</li>
    1474     *  <li>January 1, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 15</li>
    1475     *  <li>January 6, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 435 (7*60 + 15)</li>
    1476     *  <li>January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0
    1477     *   (a millisecond cannot be split in minutes)</li>
    1478     * </ul>
    1479     *
    1480     * @param calendar the calendar to work with, not null
    1481     * @param fragment the {@link Calendar} field part of calendar to calculate
    1482     * @return number of minutes within the fragment of date
    1483     * @throws NullPointerException if the date is {@code null} or
    1484     * fragment is not supported
    1485     * @since 2.4
    1486     */
    1487    public static long getFragmentInMinutes(final Calendar calendar, final int fragment) {
    1488        return getFragment(calendar, fragment, TimeUnit.MINUTES);
    1489    }
    1490
    1491    /**
    1492     * Returns the number of hours within the
    1493     * fragment. All date fields greater than the fragment will be ignored.
    1494     *
    1495     * <p>Asking the hours of any date will only return the number of hours
    1496     * of the current day (resulting in a number between 0 and 23). This
    1497     * method will retrieve the number of hours for any fragment.
    1498     * For example, if you want to calculate the number of hours past this month,
    1499     * your fragment is Calendar.MONTH. The result will be all hours of the
    1500     * past day(s).</p>
    1501     *
    1502     * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both
    1503     * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY,
    1504     * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND
    1505     * A fragment less than or equal to a HOUR field will return 0.</p>
    1506     *
    1507     * <ul>
    1508     *  <li>January 1, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 7
    1509     *   (equivalent to calendar.get(Calendar.HOUR_OF_DAY))</li>
    1510     *  <li>January 6, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 7
    1511     *   (equivalent to calendar.get(Calendar.HOUR_OF_DAY))</li>
    1512     *  <li>January 1, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 7</li>
    1513     *  <li>January 6, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 127 (5*24 + 7)</li>
    1514     *  <li>January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0
    1515     *   (a millisecond cannot be split in hours)</li>
    1516     * </ul>
    1517     *
    1518     * @param calendar the calendar to work with, not null
    1519     * @param fragment the {@link Calendar} field part of calendar to calculate
    1520     * @return number of hours within the fragment of date
    1521     * @throws NullPointerException if the date is {@code null} or
    1522     * fragment is not supported
    1523     * @since 2.4
    1524     */
    1525    public static long getFragmentInHours(final Calendar calendar, final int fragment) {
    1526        return getFragment(calendar, fragment, TimeUnit.HOURS);
    1527    }
    1528
    1529    /**
    1530     * Returns the number of days within the
    1531     * fragment. All datefields greater than the fragment will be ignored.
    1532     *
    1533     * <p>Asking the days of any date will only return the number of days
    1534     * of the current month (resulting in a number between 1 and 31). This
    1535     * method will retrieve the number of days for any fragment.
    1536     * For example, if you want to calculate the number of days past this year,
    1537     * your fragment is Calendar.YEAR. The result will be all days of the
    1538     * past month(s).</p>
    1539     *
    1540     * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both
    1541     * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY,
    1542     * Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND
    1543     * A fragment less than or equal to a DAY field will return 0.</p>
    1544     *
    1545     * <ul>
    1546     *  <li>January 28, 2008 with Calendar.MONTH as fragment will return 28
    1547     *   (equivalent to calendar.get(Calendar.DAY_OF_MONTH))</li>
    1548     *  <li>February 28, 2008 with Calendar.MONTH as fragment will return 28
    1549     *   (equivalent to calendar.get(Calendar.DAY_OF_MONTH))</li>
    1550     *  <li>January 28, 2008 with Calendar.YEAR as fragment will return 28
    1551     *   (equivalent to calendar.get(Calendar.DAY_OF_YEAR))</li>
    1552     *  <li>February 28, 2008 with Calendar.YEAR as fragment will return 59
    1553     *   (equivalent to calendar.get(Calendar.DAY_OF_YEAR))</li>
    1554     *  <li>January 28, 2008 with Calendar.MILLISECOND as fragment will return 0
    1555     *   (a millisecond cannot be split in days)</li>
    1556     * </ul>
    1557     *
    1558     * @param calendar the calendar to work with, not null
    1559     * @param fragment the {@link Calendar} field part of calendar to calculate
    1560     * @return number of days within the fragment of date
    1561     * @throws NullPointerException if the date is {@code null} or
    1562     * fragment is not supported
    1563     * @since 2.4
    1564     */
    1565    public static long getFragmentInDays(final Calendar calendar, final int fragment) {
    1566        return getFragment(calendar, fragment, TimeUnit.DAYS);
    1567    }
    1568
    1569    /**
    1570     * Gets a Date fragment for any unit.
    1571     *
    1572     * @param date the date to work with, not null
    1573     * @param fragment the Calendar field part of date to calculate
    1574     * @param unit the time unit
    1575     * @return number of units within the fragment of the date
    1576     * @throws NullPointerException if the date is {@code null}
    1577     * @throws IllegalArgumentException if fragment is not supported
    1578     * @since 2.4
    1579     */
    1580    private static long getFragment(final Date date, final int fragment, final TimeUnit unit) {
    1581        validateDateNotNull(date);
    1582        final Calendar calendar = Calendar.getInstance();
    1583        calendar.setTime(date);
    1584        return getFragment(calendar, fragment, unit);
    1585    }
    1586
    1587    /**
    1588     * Gets a Calendar fragment for any unit.
    1589     *
    1590     * @param calendar the calendar to work with, not null
    1591     * @param fragment the Calendar field part of calendar to calculate
    1592     * @param unit the time unit
    1593     * @return number of units within the fragment of the calendar
    1594     * @throws NullPointerException if the date is {@code null} or
    1595     * fragment is not supported
    1596     * @since 2.4
    1597     */
    1598    private static long getFragment(final Calendar calendar, final int fragment, final TimeUnit unit) {
    1599        Objects.requireNonNull(calendar, "calendar");
    1600        long result = 0;
    1601        final int offset = (unit == TimeUnit.DAYS) ? 0 : 1;
    1602
    1603        // Fragments bigger than a day require a breakdown to days
    1604        switch (fragment) {
    1605            case Calendar.YEAR:
    1606                result += unit.convert(calendar.get(Calendar.DAY_OF_YEAR) - offset, TimeUnit.DAYS);
    1607                break;
    1608            case Calendar.MONTH:
    1609                result += unit.convert(calendar.get(Calendar.DAY_OF_MONTH) - offset, TimeUnit.DAYS);
    1610                break;
    1611            default:
    1612                break;
    1613        }
    1614
    1615        switch (fragment) {
    1616            // Number of days already calculated for these cases
    1617            case Calendar.YEAR:
    1618            case Calendar.MONTH:
    1619
    1620            // The rest of the valid cases
    1621            case Calendar.DAY_OF_YEAR:
    1622            case Calendar.DATE:
    1623                result += unit.convert(calendar.get(Calendar.HOUR_OF_DAY), TimeUnit.HOURS);
    1624                //$FALL-THROUGH$
    1625            case Calendar.HOUR_OF_DAY:
    1626                result += unit.convert(calendar.get(Calendar.MINUTE), TimeUnit.MINUTES);
    1627                //$FALL-THROUGH$
    1628            case Calendar.MINUTE:
    1629                result += unit.convert(calendar.get(Calendar.SECOND), TimeUnit.SECONDS);
    1630                //$FALL-THROUGH$
    1631            case Calendar.SECOND:
    1632                result += unit.convert(calendar.get(Calendar.MILLISECOND), TimeUnit.MILLISECONDS);
    1633                break;
    1634            case Calendar.MILLISECOND: break; //never useful
    1635                default: throw new IllegalArgumentException("The fragment " + fragment + " is not supported");
    1636        }
    1637        return result;
    1638    }
    1639
    1640    /**
    1641     * Determines if two calendars are equal up to no more than the specified
    1642     * most significant field.
    1643     *
    1644     * @param cal1 the first calendar, not {@code null}
    1645     * @param cal2 the second calendar, not {@code null}
    1646     * @param field the field from {@link Calendar}
    1647     * @return {@code true} if equal; otherwise {@code false}
    1648     * @throws NullPointerException if any argument is {@code null}
    1649     * @see #truncate(Calendar, int)
    1650     * @see #truncatedEquals(Date, Date, int)
    1651     * @since 3.0
    1652     */
    1653    public static boolean truncatedEquals(final Calendar cal1, final Calendar cal2, final int field) {
    1654        return truncatedCompareTo(cal1, cal2, field) == 0;
    1655    }
    1656
    1657    /**
    1658     * Determines if two dates are equal up to no more than the specified
    1659     * most significant field.
    1660     *
    1661     * @param date1 the first date, not {@code null}
    1662     * @param date2 the second date, not {@code null}
    1663     * @param field the field from {@link Calendar}
    1664     * @return {@code true} if equal; otherwise {@code false}
    1665     * @throws NullPointerException if any argument is {@code null}
    1666     * @see #truncate(Date, int)
    1667     * @see #truncatedEquals(Calendar, Calendar, int)
    1668     * @since 3.0
    1669     */
    1670    public static boolean truncatedEquals(final Date date1, final Date date2, final int field) {
    1671        return truncatedCompareTo(date1, date2, field) == 0;
    1672    }
    1673
    1674    /**
    1675     * Determines how two calendars compare up to no more than the specified
    1676     * most significant field.
    1677     *
    1678     * @param cal1 the first calendar, not {@code null}
    1679     * @param cal2 the second calendar, not {@code null}
    1680     * @param field the field from {@link Calendar}
    1681     * @return a negative integer, zero, or a positive integer as the first
    1682     * calendar is less than, equal to, or greater than the second.
    1683     * @throws NullPointerException if any argument is {@code null}
    1684     * @see #truncate(Calendar, int)
    1685     * @see #truncatedCompareTo(Date, Date, int)
    1686     * @since 3.0
    1687     */
    1688    public static int truncatedCompareTo(final Calendar cal1, final Calendar cal2, final int field) {
    1689        final Calendar truncatedCal1 = truncate(cal1, field);
    1690        final Calendar truncatedCal2 = truncate(cal2, field);
    1691        return truncatedCal1.compareTo(truncatedCal2);
    1692    }
    1693
    1694    /**
    1695     * Determines how two dates compare up to no more than the specified
    1696     * most significant field.
    1697     *
    1698     * @param date1 the first date, not {@code null}
    1699     * @param date2 the second date, not {@code null}
    1700     * @param field the field from {@link Calendar}
    1701     * @return a negative integer, zero, or a positive integer as the first
    1702     * date is less than, equal to, or greater than the second.
    1703     * @throws NullPointerException if any argument is {@code null}
    1704     * @see #truncate(Calendar, int)
    1705     * @see #truncatedCompareTo(Date, Date, int)
    1706     * @since 3.0
    1707     */
    1708    public static int truncatedCompareTo(final Date date1, final Date date2, final int field) {
    1709        final Date truncatedDate1 = truncate(date1, field);
    1710        final Date truncatedDate2 = truncate(date2, field);
    1711        return truncatedDate1.compareTo(truncatedDate2);
    1712    }
    1713
    1714    /**
    1715     * @param date Date to validate.
    1716     * @throws NullPointerException if {@code date == null}
    1717     */
    1718    private static void validateDateNotNull(final Date date) {
    1719        Objects.requireNonNull(date, "date");
    1720    }
    1721
    1722    /**
    1723     * Date iterator.
    1724     */
    1725    static class DateIterator implements Iterator<Calendar> {
    1726        private final Calendar endFinal;
    1727        private final Calendar spot;
    1728
    1729        /**
    1730         * Constructs a DateIterator that ranges from one date to another.
    1731         *
    1732         * @param startFinal start date (inclusive)
    1733         * @param endFinal end date (inclusive)
    1734         */
    1735        DateIterator(final Calendar startFinal, final Calendar endFinal) {
    1736            this.endFinal = endFinal;
    1737            spot = startFinal;
    1738            spot.add(Calendar.DATE, -1);
    1739        }
    1740
    1741        /**
    1742         * Has the iterator not reached the end date yet?
    1743         *
    1744         * @return {@code true} if the iterator has yet to reach the end date
    1745         */
    1746        @Override
    1747        public boolean hasNext() {
    1748            return spot.before(endFinal);
    1749        }
    1750
    1751        /**
    1752         * Returns the next calendar in the iteration
    1753         *
    1754         * @return Object calendar for the next date
    1755         */
    1756        @Override
    1757        public Calendar next() {
    1758            if (spot.equals(endFinal)) {
    1759                throw new NoSuchElementException();
    1760            }
    1761            spot.add(Calendar.DATE, 1);
    1762            return (Calendar) spot.clone();
    1763        }
    1764
    1765        /**
    1766         * Always throws UnsupportedOperationException.
    1767         *
    1768         * @throws UnsupportedOperationException Always thrown.
    1769         * @see java.util.Iterator#remove()
    1770         */
    1771        @Override
    1772        public void remove() {
    1773            throw new UnsupportedOperationException();
    1774        }
    1775    }
    1776
    1777}