http://git-wip-us.apache.org/repos/asf/commons-lang/blob/1da8ccdb/src/main/java/org/apache/commons/lang3/time/DateUtils.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/lang3/time/DateUtils.java b/src/main/java/org/apache/commons/lang3/time/DateUtils.java index 7f3bc97..7e5e4f6 100644 --- a/src/main/java/org/apache/commons/lang3/time/DateUtils.java +++ b/src/main/java/org/apache/commons/lang3/time/DateUtils.java @@ -5,9 +5,9 @@ * 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. @@ -31,7 +31,7 @@ import org.apache.commons.lang3.Validate; /** * <p>A suite of utilities surrounding the use of the * {@link java.util.Calendar} and {@link java.util.Date} object.</p> - * + * * <p>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(), @@ -43,8 +43,8 @@ import org.apache.commons.lang3.Validate; * kind of date-field you want your result, for instance milliseconds or days. * </p> * <p> - * 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 + * 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). * </p> @@ -85,7 +85,7 @@ public class DateUtils { {Calendar.SECOND}, {Calendar.MINUTE}, {Calendar.HOUR_OF_DAY, Calendar.HOUR}, - {Calendar.DATE, Calendar.DAY_OF_MONTH, Calendar.AM_PM + {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}, @@ -125,14 +125,14 @@ public class DateUtils { * Truncation. */ TRUNCATE, - + /** - * Rounding. + * Rounding. */ ROUND, - + /** - * Ceiling. + * Ceiling. */ CEILING } @@ -156,7 +156,7 @@ public class DateUtils { * <p>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. * </p> - * + * * @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 @@ -180,7 +180,7 @@ public class DateUtils { * <p>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. * </p> - * + * * @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 @@ -201,7 +201,7 @@ public class DateUtils { * <p>Checks if two date objects represent the same instant in time.</p> * * <p>This method compares the long millisecond time of the two objects.</p> - * + * * @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 @@ -219,7 +219,7 @@ public class DateUtils { * <p>Checks if two calendar objects represent the same instant in time.</p> * * <p>This method compares the long millisecond time of the two objects.</p> - * + * * @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 @@ -239,7 +239,7 @@ public class DateUtils { * * <p>This method compares the values of the fields of the two objects. * In addition, both calendars must be the same of the same type.</p> - * + * * @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 @@ -263,12 +263,12 @@ public class DateUtils { //----------------------------------------------------------------------- /** * <p>Parses a string representing a date by trying a variety of different parsers.</p> - * + * * <p>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.</p> * 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 @@ -278,17 +278,17 @@ public class DateUtils { public static Date parseDate(final String str, final String... parsePatterns) throws ParseException { return parseDate(str, null, parsePatterns); } - + //----------------------------------------------------------------------- /** * <p>Parses a string representing a date by trying a variety of different parsers, * using the default date format symbols for the given locale.</p> - * + * * <p>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.</p> * 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. If <code>null</code>, * the system locale is used (as per {@link #parseDate(String, String...)}). @@ -300,17 +300,17 @@ public class DateUtils { */ public static Date parseDate(final String str, final Locale locale, final String... parsePatterns) throws ParseException { return parseDateWithLeniency(str, locale, parsePatterns, true); - } + } //----------------------------------------------------------------------- /** * <p>Parses a string representing a date by trying a variety of different parsers.</p> - * + * * <p>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.</p> - * The parser parses strictly - it does not allow for dates such as "February 942, 1996". - * + * 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 @@ -325,12 +325,12 @@ public class DateUtils { /** * <p>Parses a string representing a date by trying a variety of different parsers, * using the default date format symbols for the given locale..</p> - * + * * <p>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.</p> - * The parser parses strictly - it does not allow for dates such as "February 942, 1996". - * + * 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. If <code>null</code>, * the system locale is used (as per {@link #parseDateStrictly(String, String...)}). @@ -342,15 +342,15 @@ public class DateUtils { */ public static Date parseDateStrictly(final String str, final Locale locale, final String... parsePatterns) throws ParseException { return parseDateWithLeniency(str, locale, parsePatterns, false); - } + } /** * <p>Parses a string representing a date by trying a variety of different parsers.</p> - * + * * <p>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.</p> - * + * * @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 @@ -519,7 +519,7 @@ public class DateUtils { c.add(calendarField, amount); return c.getTime(); } - + //----------------------------------------------------------------------- /** * Sets the years field to a date returning a new object. @@ -567,7 +567,7 @@ public class DateUtils { //----------------------------------------------------------------------- /** - * Sets the hours field to a date returning a new object. Hours range + * Sets the hours field to a date returning a new object. Hours range * from 0-23. * The original {@code Date} is unchanged. * @@ -595,7 +595,7 @@ public class DateUtils { 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. @@ -624,11 +624,11 @@ public class DateUtils { */ 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. + * Sets the specified field to a date returning a new object. * This does not use a lenient calendar. * The original {@code Date} is unchanged. * @@ -647,12 +647,12 @@ public class DateUtils { c.setTime(date); c.set(calendarField, amount); return c.getTime(); - } + } //----------------------------------------------------------------------- /** - * Converts a {@code Date} into a {@code Calendar}. - * + * 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 @@ -663,7 +663,7 @@ public class DateUtils { c.setTime(date); return c; } - + //----------------------------------------------------------------------- /** * Converts a {@code Date} of a given {@code TimeZone} into a {@code Calendar} @@ -677,7 +677,7 @@ public class DateUtils { c.setTime(date); return c; } - + //----------------------------------------------------------------------- /** * <p>Rounds a date, leaving the field specified as the most @@ -687,10 +687,10 @@ public class DateUtils { * 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.</p> - * + * * <p>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 + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a * date that crosses this time would produce the following values: * </p> * <ul> @@ -699,7 +699,7 @@ public class DateUtils { * <li>March 30, 2003 02:10 rounds to March 30, 2003 03:00</li> * <li>March 30, 2003 02:40 rounds to March 30, 2003 04:00</li> * </ul> - * + * * @param date the date to work with, not null * @param field the field from {@code Calendar} or {@code SEMI_MONTH} * @return the different rounded date, not null @@ -721,10 +721,10 @@ public class DateUtils { * 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.</p> - * + * * <p>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 + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a * date that crosses this time would produce the following values: * </p> * <ul> @@ -733,7 +733,7 @@ public class DateUtils { * <li>March 30, 2003 02:10 rounds to March 30, 2003 03:00</li> * <li>March 30, 2003 02:40 rounds to March 30, 2003 04:00</li> * </ul> - * + * * @param date the date to work with, not null * @param field the field from {@code Calendar} or <code>SEMI_MONTH</code> * @return the different rounded date, not null @@ -757,10 +757,10 @@ public class DateUtils { * 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.</p> - * + * * <p>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 + * Suppose daylight saving time begins at 02:00 on March 30. Rounding a * date that crosses this time would produce the following values: * </p> * <ul> @@ -769,7 +769,7 @@ public class DateUtils { * <li>March 30, 2003 02:10 rounds to March 30, 2003 03:00</li> * <li>March 30, 2003 02:40 rounds to March 30, 2003 04:00</li> * </ul> - * + * * @param date the date to work with, either {@code Date} or {@code Calendar}, not null * @param field the field from {@code Calendar} or <code>SEMI_MONTH</code> * @return the different rounded date, not null @@ -799,7 +799,7 @@ public class DateUtils { * 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.</p> - * + * * @param date the date to work with, not null * @param field the field from {@code Calendar} or <code>SEMI_MONTH</code> * @return the different truncated date, not null @@ -822,7 +822,7 @@ public class DateUtils { * 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.</p> - * + * * @param date the date to work with, not null * @param field the field from {@code Calendar} or <code>SEMI_MONTH</code> * @return the different truncated date, not null @@ -846,7 +846,7 @@ public class DateUtils { * 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.</p> - * + * * @param date the date to work with, either {@code Date} or {@code Calendar}, not null * @param field the field from {@code Calendar} or <code>SEMI_MONTH</code> * @return the different truncated date, not null @@ -866,7 +866,7 @@ public class DateUtils { throw new ClassCastException("Could not truncate " + date); } } - + //----------------------------------------------------------------------- /** * <p>Gets a date ceiling, leaving the field specified as the most @@ -876,7 +876,7 @@ public class DateUtils { * 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.</p> - * + * * @param date the date to work with, not null * @param field the field from {@code Calendar} or <code>SEMI_MONTH</code> * @return the different ceil date, not null @@ -900,7 +900,7 @@ public class DateUtils { * 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.</p> - * + * * @param date the date to work with, not null * @param field the field from {@code Calendar} or <code>SEMI_MONTH</code> * @return the different ceil date, not null @@ -925,7 +925,7 @@ public class DateUtils { * 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.</p> - * + * * @param date the date to work with, either {@code Date} or {@code Calendar}, not null * @param field the field from {@code Calendar} or <code>SEMI_MONTH</code> * @return the different ceil date, not null @@ -950,7 +950,7 @@ public class DateUtils { //----------------------------------------------------------------------- /** * <p>Internal calculation method.</p> - * + * * @param val the calendar, not null * @param field the field constant * @param modType type to truncate, round or ceiling @@ -960,7 +960,7 @@ public class DateUtils { if (val.get(Calendar.YEAR) > 280000000) { throw new ArithmeticException("Calendar value too large for accurate calculations"); } - + if (field == Calendar.MILLISECOND) { return; } @@ -1111,7 +1111,7 @@ public class DateUtils { * * @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_SUNDAY}, * {@link DateUtils#RANGE_MONTH_MONDAY}, * {@link DateUtils#RANGE_WEEK_SUNDAY}, * {@link DateUtils#RANGE_WEEK_MONDAY}, @@ -1142,7 +1142,7 @@ public class DateUtils { * * @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_SUNDAY}, * {@link DateUtils#RANGE_MONTH_MONDAY}, * {@link DateUtils#RANGE_WEEK_SUNDAY}, * {@link DateUtils#RANGE_WEEK_MONDAY}, @@ -1254,23 +1254,23 @@ public class DateUtils { throw new ClassCastException("Could not iterate based on " + focus); } } - + /** - * <p>Returns the number of milliseconds within the + * <p>Returns the number of milliseconds within the * fragment. All datefields greater than the fragment will be ignored.</p> - * + * * <p>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, + * 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).</p> - * - * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both - * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * + * <p>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.</p> - * + * A fragment less than or equal to a SECOND field will return 0.</p> + * * <ul> * <li>January 1, 2008 7:15:10.538 with Calendar.SECOND as fragment will return 538</li> * <li>January 6, 2008 7:15:10.538 with Calendar.SECOND as fragment will return 538</li> @@ -1278,34 +1278,34 @@ public class DateUtils { * <li>January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 * (a millisecond cannot be split in milliseconds)</li> * </ul> - * + * * @param date the date to work with, not null - * @param fragment the {@code Calendar} field part of date to calculate + * @param fragment the {@code Calendar} field part of date to calculate * @return number of milliseconds within the fragment of date * @throws IllegalArgumentException if the date is <code>null</code> or * fragment is not supported * @since 2.4 */ public static long getFragmentInMilliseconds(final Date date, final int fragment) { - return getFragment(date, fragment, TimeUnit.MILLISECONDS); + return getFragment(date, fragment, TimeUnit.MILLISECONDS); } - + /** - * <p>Returns the number of seconds within the - * fragment. All datefields greater than the fragment will be ignored.</p> - * + * <p>Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.</p> + * * <p>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, + * 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).</p> - * - * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both - * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * be all seconds of the past hour(s) and minutes(s).</p> + * + * <p>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.</p> - * + * A fragment less than or equal to a SECOND field will return 0.</p> + * * <ul> * <li>January 1, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10 * (equivalent to deprecated date.getSeconds())</li> @@ -1316,9 +1316,9 @@ public class DateUtils { * <li>January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 * (a millisecond cannot be split in seconds)</li> * </ul> - * + * * @param date the date to work with, not null - * @param fragment the {@code Calendar} field part of date to calculate + * @param fragment the {@code Calendar} field part of date to calculate * @return number of seconds within the fragment of date * @throws IllegalArgumentException if the date is <code>null</code> or * fragment is not supported @@ -1327,23 +1327,23 @@ public class DateUtils { public static long getFragmentInSeconds(final Date date, final int fragment) { return getFragment(date, fragment, TimeUnit.SECONDS); } - + /** - * <p>Returns the number of minutes within the - * fragment. All datefields greater than the fragment will be ignored.</p> - * + * <p>Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.</p> + * * <p>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).</p> - * - * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both - * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * 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).</p> + * + * <p>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.</p> - * + * A fragment less than or equal to a MINUTE field will return 0.</p> + * * <ul> * <li>January 1, 2008 7:15:10.538 with Calendar.HOUR_OF_DAY as fragment will return 15 * (equivalent to deprecated date.getMinutes())</li> @@ -1354,34 +1354,34 @@ public class DateUtils { * <li>January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 * (a millisecond cannot be split in minutes)</li> * </ul> - * + * * @param date the date to work with, not null - * @param fragment the {@code Calendar} field part of date to calculate + * @param fragment the {@code Calendar} field part of date to calculate * @return number of minutes within the fragment of date - * @throws IllegalArgumentException if the date is <code>null</code> or + * @throws IllegalArgumentException if the date is <code>null</code> or * fragment is not supported * @since 2.4 */ public static long getFragmentInMinutes(final Date date, final int fragment) { return getFragment(date, fragment, TimeUnit.MINUTES); } - + /** - * <p>Returns the number of hours within the - * fragment. All datefields greater than the fragment will be ignored.</p> - * + * <p>Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.</p> + * * <p>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).</p> - * - * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both - * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * 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).</p> + * + * <p>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.</p> - * + * A fragment less than or equal to a HOUR field will return 0.</p> + * * <ul> * <li>January 1, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 7 * (equivalent to deprecated date.getHours())</li> @@ -1392,34 +1392,34 @@ public class DateUtils { * <li>January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 * (a millisecond cannot be split in hours)</li> * </ul> - * + * * @param date the date to work with, not null - * @param fragment the {@code Calendar} field part of date to calculate + * @param fragment the {@code Calendar} field part of date to calculate * @return number of hours within the fragment of date - * @throws IllegalArgumentException if the date is <code>null</code> or + * @throws IllegalArgumentException if the date is <code>null</code> or * fragment is not supported * @since 2.4 */ public static long getFragmentInHours(final Date date, final int fragment) { return getFragment(date, fragment, TimeUnit.HOURS); } - + /** - * <p>Returns the number of days within the - * fragment. All datefields greater than the fragment will be ignored.</p> - * + * <p>Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.</p> + * * <p>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).</p> - * - * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both - * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * 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).</p> + * + * <p>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.</p> - * + * A fragment less than or equal to a DAY field will return 0.</p> + * * <ul> * <li>January 28, 2008 with Calendar.MONTH as fragment will return 28 * (equivalent to deprecated date.getDay())</li> @@ -1430,11 +1430,11 @@ public class DateUtils { * <li>January 28, 2008 with Calendar.MILLISECOND as fragment will return 0 * (a millisecond cannot be split in days)</li> * </ul> - * + * * @param date the date to work with, not null - * @param fragment the {@code Calendar} field part of date to calculate + * @param fragment the {@code Calendar} field part of date to calculate * @return number of days within the fragment of date - * @throws IllegalArgumentException if the date is <code>null</code> or + * @throws IllegalArgumentException if the date is <code>null</code> or * fragment is not supported * @since 2.4 */ @@ -1443,21 +1443,21 @@ public class DateUtils { } /** - * <p>Returns the number of milliseconds within the - * fragment. All datefields greater than the fragment will be ignored.</p> - * + * <p>Returns the number of milliseconds within the + * fragment. All datefields greater than the fragment will be ignored.</p> + * * <p>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, + * 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).</p> - * - * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both - * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * be all seconds of the past hour(s), minutes(s) and second(s).</p> + * + * <p>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.</p> - * + * A fragment less than or equal to a MILLISECOND field will return 0.</p> + * * <ul> * <li>January 1, 2008 7:15:10.538 with Calendar.SECOND as fragment will return 538 * (equivalent to calendar.get(Calendar.MILLISECOND))</li> @@ -1468,11 +1468,11 @@ public class DateUtils { * <li>January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 * (a millisecond cannot be split in milliseconds)</li> * </ul> - * + * * @param calendar the calendar to work with, not null - * @param fragment the {@code Calendar} field part of calendar to calculate + * @param fragment the {@code Calendar} field part of calendar to calculate * @return number of milliseconds within the fragment of date - * @throws IllegalArgumentException if the date is <code>null</code> or + * @throws IllegalArgumentException if the date is <code>null</code> or * fragment is not supported * @since 2.4 */ @@ -1480,21 +1480,21 @@ public class DateUtils { return getFragment(calendar, fragment, TimeUnit.MILLISECONDS); } /** - * <p>Returns the number of seconds within the - * fragment. All datefields greater than the fragment will be ignored.</p> - * + * <p>Returns the number of seconds within the + * fragment. All datefields greater than the fragment will be ignored.</p> + * * <p>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, + * 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).</p> - * - * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both - * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * be all seconds of the past hour(s) and minutes(s).</p> + * + * <p>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.</p> - * + * A fragment less than or equal to a SECOND field will return 0.</p> + * * <ul> * <li>January 1, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10 * (equivalent to calendar.get(Calendar.SECOND))</li> @@ -1505,34 +1505,34 @@ public class DateUtils { * <li>January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 * (a millisecond cannot be split in seconds)</li> * </ul> - * + * * @param calendar the calendar to work with, not null - * @param fragment the {@code Calendar} field part of calendar to calculate + * @param fragment the {@code Calendar} field part of calendar to calculate * @return number of seconds within the fragment of date - * @throws IllegalArgumentException if the date is <code>null</code> or + * @throws IllegalArgumentException if the date is <code>null</code> or * fragment is not supported * @since 2.4 */ public static long getFragmentInSeconds(final Calendar calendar, final int fragment) { return getFragment(calendar, fragment, TimeUnit.SECONDS); } - + /** - * <p>Returns the number of minutes within the - * fragment. All datefields greater than the fragment will be ignored.</p> - * + * <p>Returns the number of minutes within the + * fragment. All datefields greater than the fragment will be ignored.</p> + * * <p>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).</p> - * - * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both - * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * 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).</p> + * + * <p>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.</p> - * + * A fragment less than or equal to a MINUTE field will return 0.</p> + * * <ul> * <li>January 1, 2008 7:15:10.538 with Calendar.HOUR_OF_DAY as fragment will return 15 * (equivalent to calendar.get(Calendar.MINUTES))</li> @@ -1543,34 +1543,34 @@ public class DateUtils { * <li>January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 * (a millisecond cannot be split in minutes)</li> * </ul> - * + * * @param calendar the calendar to work with, not null - * @param fragment the {@code Calendar} field part of calendar to calculate + * @param fragment the {@code Calendar} field part of calendar to calculate * @return number of minutes within the fragment of date - * @throws IllegalArgumentException if the date is <code>null</code> or + * @throws IllegalArgumentException if the date is <code>null</code> or * fragment is not supported * @since 2.4 */ public static long getFragmentInMinutes(final Calendar calendar, final int fragment) { return getFragment(calendar, fragment, TimeUnit.MINUTES); } - + /** - * <p>Returns the number of hours within the - * fragment. All datefields greater than the fragment will be ignored.</p> - * + * <p>Returns the number of hours within the + * fragment. All datefields greater than the fragment will be ignored.</p> + * * <p>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).</p> - * - * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both - * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * 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).</p> + * + * <p>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.</p> - * + * A fragment less than or equal to a HOUR field will return 0.</p> + * * <ul> * <li>January 1, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 7 * (equivalent to calendar.get(Calendar.HOUR_OF_DAY))</li> @@ -1581,34 +1581,34 @@ public class DateUtils { * <li>January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 * (a millisecond cannot be split in hours)</li> * </ul> - * + * * @param calendar the calendar to work with, not null - * @param fragment the {@code Calendar} field part of calendar to calculate + * @param fragment the {@code Calendar} field part of calendar to calculate * @return number of hours within the fragment of date - * @throws IllegalArgumentException if the date is <code>null</code> or + * @throws IllegalArgumentException if the date is <code>null</code> or * fragment is not supported * @since 2.4 */ public static long getFragmentInHours(final Calendar calendar, final int fragment) { return getFragment(calendar, fragment, TimeUnit.HOURS); } - + /** - * <p>Returns the number of days within the - * fragment. All datefields greater than the fragment will be ignored.</p> - * + * <p>Returns the number of days within the + * fragment. All datefields greater than the fragment will be ignored.</p> + * * <p>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).</p> - * - * <p>Valid fragments are: Calendar.YEAR, Calendar.MONTH, both - * Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, + * 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).</p> + * + * <p>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.</p> - * + * A fragment less than or equal to a DAY field will return 0.</p> + * * <ul> * <li>January 28, 2008 with Calendar.MONTH as fragment will return 28 * (equivalent to calendar.get(Calendar.DAY_OF_MONTH))</li> @@ -1621,26 +1621,26 @@ public class DateUtils { * <li>January 28, 2008 with Calendar.MILLISECOND as fragment will return 0 * (a millisecond cannot be split in days)</li> * </ul> - * + * * @param calendar the calendar to work with, not null - * @param fragment the {@code Calendar} field part of calendar to calculate + * @param fragment the {@code Calendar} field part of calendar to calculate * @return number of days within the fragment of date - * @throws IllegalArgumentException if the date is <code>null</code> or + * @throws IllegalArgumentException if the date is <code>null</code> 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 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 <code>null</code> or + * @throws IllegalArgumentException if the date is <code>null</code> or * fragment is not supported * @since 2.4 */ @@ -1653,24 +1653,24 @@ public class DateUtils { /** * 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 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 <code>null</code> or + * @throws IllegalArgumentException if the date is <code>null</code> 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"); + 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: @@ -1687,7 +1687,7 @@ public class DateUtils { // 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: @@ -1707,11 +1707,11 @@ public class DateUtils { } return result; } - + /** - * Determines if two calendars are equal up to no more than the specified + * Determines if two calendars are equal up to no more than the specified * most significant field. - * + * * @param cal1 the first calendar, not <code>null</code> * @param cal2 the second calendar, not <code>null</code> * @param field the field from {@code Calendar} @@ -1726,9 +1726,9 @@ public class DateUtils { } /** - * Determines if two dates are equal up to no more than the specified + * Determines if two dates are equal up to no more than the specified * most significant field. - * + * * @param date1 the first date, not <code>null</code> * @param date2 the second date, not <code>null</code> * @param field the field from {@code Calendar} @@ -1743,13 +1743,13 @@ public class DateUtils { } /** - * Determines how two calendars compare up to no more than the specified + * Determines how two calendars compare up to no more than the specified * most significant field. - * + * * @param cal1 the first calendar, not <code>null</code> * @param cal2 the second calendar, not <code>null</code> * @param field the field from {@code Calendar} - * @return a negative integer, zero, or a positive integer as the first + * @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 <code>null</code> * @see #truncate(Calendar, int) @@ -1763,13 +1763,13 @@ public class DateUtils { } /** - * Determines how two dates compare up to no more than the specified + * Determines how two dates compare up to no more than the specified * most significant field. - * + * * @param date1 the first date, not <code>null</code> * @param date2 the second date, not <code>null</code> * @param field the field from <code>Calendar</code> - * @return a negative integer, zero, or a positive integer as the first + * @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 <code>null</code> * @see #truncate(Calendar, int) @@ -1793,9 +1793,9 @@ public class DateUtils { static class DateIterator implements Iterator<Calendar> { private final Calendar endFinal; private final Calendar spot; - + /** - * Constructs a DateIterator that ranges from one date to another. + * Constructs a DateIterator that ranges from one date to another. * * @param startFinal start date (inclusive) * @param endFinal end date (inclusive) @@ -1833,7 +1833,7 @@ public class DateUtils { /** * Always throws UnsupportedOperationException. - * + * * @throws UnsupportedOperationException * @see java.util.Iterator#remove() */
http://git-wip-us.apache.org/repos/asf/commons-lang/blob/1da8ccdb/src/main/java/org/apache/commons/lang3/time/DurationFormatUtils.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/lang3/time/DurationFormatUtils.java b/src/main/java/org/apache/commons/lang3/time/DurationFormatUtils.java index d139666..564ea16 100644 --- a/src/main/java/org/apache/commons/lang3/time/DurationFormatUtils.java +++ b/src/main/java/org/apache/commons/lang3/time/DurationFormatUtils.java @@ -5,9 +5,9 @@ * 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. @@ -26,7 +26,7 @@ import org.apache.commons.lang3.StringUtils; import org.apache.commons.lang3.Validate; /** - * <p>Duration formatting utilities and constants. The following table describes the tokens + * <p>Duration formatting utilities and constants. The following table describes the tokens * used in the pattern language for formatting. </p> * <table border="1" summary="Pattern Tokens"> * <tr><th>character</th><th>duration element</th></tr> @@ -62,7 +62,7 @@ public class DurationFormatUtils { /** * <p>Pattern used with <code>FastDateFormat</code> and <code>SimpleDateFormat</code> * for the ISO 8601 period format used in durations.</p> - * + * * @see org.apache.commons.lang3.time.FastDateFormat * @see java.text.SimpleDateFormat */ @@ -71,7 +71,7 @@ public class DurationFormatUtils { //----------------------------------------------------------------------- /** * <p>Formats the time gap as a string.</p> - * + * * <p>The format used is ISO 8601-like: {@code HH:mm:ss.SSS}.</p> * * @param durationMillis the duration to format @@ -84,12 +84,12 @@ public class DurationFormatUtils { /** * <p>Formats the time gap as a string.</p> - * + * * <p>The format used is the ISO 8601 period format.</p> - * + * * <p>This method formats durations using the days and lower fields of the * ISO format pattern, such as P7D6TH5M4.321S.</p> - * + * * @param durationMillis the duration to format * @return the formatted duration, not null * @throws java.lang.IllegalArgumentException if durationMillis is negative @@ -100,10 +100,10 @@ public class DurationFormatUtils { /** * <p>Formats the time gap as a string, using the specified format, and padding with zeros.</p> - * + * * <p>This method formats durations using the days and lower fields of the * format pattern. Months and larger are not used.</p> - * + * * @param durationMillis the duration to format * @param format the way in which to format the duration, not null * @return the formatted duration, not null @@ -116,10 +116,10 @@ public class DurationFormatUtils { /** * <p>Formats the time gap as a string, using the specified format. * Padding the left hand side of numbers with zeroes is optional.</p> - * + * * <p>This method formats durations using the days and lower fields of the * format pattern. Months and larger are not used.</p> - * + * * @param durationMillis the duration to format * @param format the way in which to format the duration, not null * @param padWithZeros whether to pad the left hand side of numbers with 0's @@ -127,7 +127,7 @@ public class DurationFormatUtils { * @throws java.lang.IllegalArgumentException if durationMillis is negative */ public static String formatDuration(final long durationMillis, final String format, final boolean padWithZeros) { - Validate.inclusiveBetween(0, Long.MAX_VALUE, durationMillis, "durationMillis must not be negative"); + Validate.inclusiveBetween(0, Long.MAX_VALUE, durationMillis, "durationMillis must not be negative"); final Token[] tokens = lexx(format); @@ -136,7 +136,7 @@ public class DurationFormatUtils { long minutes = 0; long seconds = 0; long milliseconds = durationMillis; - + if (Token.containsTokenWithValue(tokens, d) ) { days = milliseconds / DateUtils.MILLIS_PER_DAY; milliseconds = milliseconds - (days * DateUtils.MILLIS_PER_DAY); @@ -159,10 +159,10 @@ public class DurationFormatUtils { /** * <p>Formats an elapsed time into a pluralization correct string.</p> - * + * * <p>This method formats durations using the days and lower fields of the * format pattern. Months and larger are not used.</p> - * + * * @param durationMillis the elapsed time to report in milliseconds * @param suppressLeadingZeroElements suppresses leading 0 elements * @param suppressTrailingZeroElements suppresses trailing 0 elements @@ -175,7 +175,7 @@ public class DurationFormatUtils { final boolean suppressTrailingZeroElements) { // This method is generally replaceable by the format method, but - // there are a series of tweaks and special cases that require + // there are a series of tweaks and special cases that require // trickery to replicate. String duration = formatDuration(durationMillis, "d' days 'H' hours 'm' minutes 's' seconds'"); if (suppressLeadingZeroElements) { @@ -225,9 +225,9 @@ public class DurationFormatUtils { //----------------------------------------------------------------------- /** * <p>Formats the time gap as a string.</p> - * + * * <p>The format used is the ISO 8601 period format.</p> - * + * * @param startMillis the start of the duration to format * @param endMillis the end of the duration to format * @return the formatted duration, not null @@ -240,7 +240,7 @@ public class DurationFormatUtils { /** * <p>Formats the time gap as a string, using the specified format. * Padding the left hand side of numbers with zeroes is optional. - * + * * @param startMillis the start of the duration * @param endMillis the end of the duration * @param format the way in which to format the duration, not null @@ -253,20 +253,20 @@ public class DurationFormatUtils { /** * <p>Formats the time gap as a string, using the specified format. - * Padding the left hand side of numbers with zeroes is optional and + * Padding the left hand side of numbers with zeroes is optional and * the timezone may be specified. </p> * - * <p>When calculating the difference between months/days, it chooses to - * calculate months first. So when working out the number of months and - * days between January 15th and March 10th, it choose 1 month and - * 23 days gained by choosing January->February = 1 month and then - * calculating days forwards, and not the 1 month and 26 days gained by - * choosing March -> February = 1 month and then calculating days + * <p>When calculating the difference between months/days, it chooses to + * calculate months first. So when working out the number of months and + * days between January 15th and March 10th, it choose 1 month and + * 23 days gained by choosing January->February = 1 month and then + * calculating days forwards, and not the 1 month and 26 days gained by + * choosing March -> February = 1 month and then calculating days * backwards. </p> * * <p>For more control, the <a href="http://joda-time.sf.net/";>Joda-Time</a> * library is recommended.</p> - * + * * @param startMillis the start of the duration * @param endMillis the end of the duration * @param format the way in which to format the duration, not null @@ -275,20 +275,20 @@ public class DurationFormatUtils { * @return the formatted duration, not null * @throws java.lang.IllegalArgumentException if startMillis is greater than endMillis */ - public static String formatPeriod(final long startMillis, final long endMillis, final String format, final boolean padWithZeros, + public static String formatPeriod(final long startMillis, final long endMillis, final String format, final boolean padWithZeros, final TimeZone timezone) { Validate.isTrue(startMillis <= endMillis, "startMillis must not be greater than endMillis"); - - - // Used to optimise for differences under 28 days and - // called formatDuration(millis, format); however this did not work - // over leap years. - // TODO: Compare performance to see if anything was lost by - // losing this optimisation. - + + + // Used to optimise for differences under 28 days and + // called formatDuration(millis, format); however this did not work + // over leap years. + // TODO: Compare performance to see if anything was lost by + // losing this optimisation. + final Token[] tokens = lexx(format); - // timezones get funky around 0, so normalizing everything to GMT + // timezones get funky around 0, so normalizing everything to GMT // stops the hours being off final Calendar start = Calendar.getInstance(timezone); start.setTime(new Date(startMillis)); @@ -321,7 +321,7 @@ public class DurationFormatUtils { hours += 24; days -= 1; } - + if (Token.containsTokenWithValue(tokens, M)) { while (days < 0) { days += start.getActualMaximum(Calendar.DAY_OF_MONTH); @@ -349,42 +349,42 @@ public class DurationFormatUtils { // target is end-year -1 target -= 1; } - + while (start.get(Calendar.YEAR) != target) { days += start.getActualMaximum(Calendar.DAY_OF_YEAR) - start.get(Calendar.DAY_OF_YEAR); - + // Not sure I grok why this is needed, but the brutal tests show it is if (start instanceof GregorianCalendar && start.get(Calendar.MONTH) == Calendar.FEBRUARY && start.get(Calendar.DAY_OF_MONTH) == 29) { days += 1; } - + start.add(Calendar.YEAR, 1); - + days += start.get(Calendar.DAY_OF_YEAR); } - + years = 0; } - + while( start.get(Calendar.MONTH) != end.get(Calendar.MONTH) ) { days += start.getActualMaximum(Calendar.DAY_OF_MONTH); start.add(Calendar.MONTH, 1); } - - months = 0; + + months = 0; while (days < 0) { days += start.getActualMaximum(Calendar.DAY_OF_MONTH); months -= 1; start.add(Calendar.MONTH, 1); } - + } - // The rest of this code adds in values that - // aren't requested. This allows the user to ask for the + // The rest of this code adds in values that + // aren't requested. This allows the user to ask for the // number of months and get the real count and not just 0->11. if (!Token.containsTokenWithValue(tokens, d)) { @@ -410,7 +410,7 @@ public class DurationFormatUtils { //----------------------------------------------------------------------- /** * <p>The internal method to do the formatting.</p> - * + * * @param tokens the tokens * @param years the number of years * @param months the number of months @@ -486,7 +486,7 @@ public class DurationFormatUtils { static final Object m = "m"; static final Object s = "s"; static final Object S = "S"; - + /** * Parses a classic date format string into Tokens * @@ -602,7 +602,7 @@ public class DurationFormatUtils { } /** - * Wraps a token around a repeated number of a value, for example it would + * Wraps a token around a repeated number of a value, for example it would * store 'yyyy' as a value for y and a count of 4. * * @param value to wrap @@ -616,7 +616,7 @@ public class DurationFormatUtils { /** * Adds another one of the value */ - void increment() { + void increment() { count++; } @@ -631,7 +631,7 @@ public class DurationFormatUtils { /** * Gets the particular value this token represents. - * + * * @return Object value */ Object getValue() { @@ -666,9 +666,9 @@ public class DurationFormatUtils { } /** - * Returns a hash code for the token equal to the - * hash code for the token's value. Thus 'TT' and 'TTTT' - * will have the same hash code. + * Returns a hash code for the token equal to the + * hash code for the token's value. Thus 'TT' and 'TTTT' + * will have the same hash code. * * @return The hash code for the token */ http://git-wip-us.apache.org/repos/asf/commons-lang/blob/1da8ccdb/src/main/java/org/apache/commons/lang3/time/FastDateFormat.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/lang3/time/FastDateFormat.java b/src/main/java/org/apache/commons/lang3/time/FastDateFormat.java index e7a25ac..b859932 100644 --- a/src/main/java/org/apache/commons/lang3/time/FastDateFormat.java +++ b/src/main/java/org/apache/commons/lang3/time/FastDateFormat.java @@ -30,16 +30,16 @@ import java.util.TimeZone; * <p>FastDateFormat is a fast and thread-safe version of * {@link java.text.SimpleDateFormat}.</p> * - * <p>To obtain an instance of FastDateFormat, use one of the static factory methods: - * {@link #getInstance(String, TimeZone, Locale)}, {@link #getDateInstance(int, TimeZone, Locale)}, - * {@link #getTimeInstance(int, TimeZone, Locale)}, or {@link #getDateTimeInstance(int, int, TimeZone, Locale)} + * <p>To obtain an instance of FastDateFormat, use one of the static factory methods: + * {@link #getInstance(String, TimeZone, Locale)}, {@link #getDateInstance(int, TimeZone, Locale)}, + * {@link #getTimeInstance(int, TimeZone, Locale)}, or {@link #getDateTimeInstance(int, int, TimeZone, Locale)} * </p> - * + * * <p>Since FastDateFormat is thread safe, you can use a static member instance:</p> * <code> * private static final FastDateFormat DATE_FORMATTER = FastDateFormat.getDateTimeInstance(FastDateFormat.LONG, FastDateFormat.SHORT); * </code> - * + * * <p>This class can be used as a direct replacement to * {@code SimpleDateFormat} in most formatting and parsing situations. * This class is especially useful in multi-threaded server environments. @@ -70,7 +70,7 @@ import java.util.TimeZone; * @since 2.0 */ public class FastDateFormat extends Format implements DateParser, DatePrinter { - + /** * Required for serialization support. * @@ -81,19 +81,19 @@ public class FastDateFormat extends Format implements DateParser, DatePrinter { /** * FULL locale dependent date or time style. */ - + public static final int FULL = DateFormat.FULL; - + /** * LONG locale dependent date or time style. */ public static final int LONG = DateFormat.LONG; - + /** * MEDIUM locale dependent date or time style. */ public static final int MEDIUM = DateFormat.MEDIUM; - + /** * SHORT locale dependent date or time style. */ http://git-wip-us.apache.org/repos/asf/commons-lang/blob/1da8ccdb/src/main/java/org/apache/commons/lang3/time/FastDateParser.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/lang3/time/FastDateParser.java b/src/main/java/org/apache/commons/lang3/time/FastDateParser.java index 9cf1a1c..bcb5118 100644 --- a/src/main/java/org/apache/commons/lang3/time/FastDateParser.java +++ b/src/main/java/org/apache/commons/lang3/time/FastDateParser.java @@ -43,14 +43,14 @@ import java.util.regex.Pattern; * <p>FastDateParser is a fast and thread-safe version of * {@link java.text.SimpleDateFormat}.</p> * - * <p>To obtain a proxy to a FastDateParser, use {@link FastDateFormat#getInstance(String, TimeZone, Locale)} + * <p>To obtain a proxy to a FastDateParser, use {@link FastDateFormat#getInstance(String, TimeZone, Locale)} * or another variation of the factory methods of {@link FastDateFormat}.</p> - * + * * <p>Since FastDateParser is thread safe, you can use a static member instance:</p> * <code> * private static final DateParser DATE_PARSER = FastDateFormat.getInstance("yyyy-MM-dd"); * </code> - * + * * <p>This class can be used as a direct replacement for * <code>SimpleDateFormat</code> in most parsing situations. * This class is especially useful in multi-threaded server environments. @@ -103,8 +103,8 @@ public class FastDateParser implements DateParser, Serializable { /** * <p>Constructs a new FastDateParser.</p> - * - * Use {@link FastDateFormat#getInstance(String, TimeZone, Locale)} or another variation of the + * + * Use {@link FastDateFormat#getInstance(String, TimeZone, Locale)} or another variation of the * factory methods of {@link FastDateFormat} to get a cached FastDateParser instance. * * @param pattern non-null {@link java.text.SimpleDateFormat} compatible @@ -381,8 +381,8 @@ public class FastDateParser implements DateParser, Serializable { /** * This implementation updates the ParsePosition if the parse succeeds. - * However, it sets the error index to the position before the failed field unlike - * the method {@link java.text.SimpleDateFormat#parse(String, ParsePosition)} which sets + * However, it sets the error index to the position before the failed field unlike + * the method {@link java.text.SimpleDateFormat#parse(String, ParsePosition)} which sets * the error index to after the failed field. * <p> * To determine if the parse has succeeded, the caller must check if the current parse position @@ -405,7 +405,7 @@ public class FastDateParser implements DateParser, Serializable { * Upon success, the ParsePosition index is updated to indicate how much of the source text was consumed. * Not all source text needs to be consumed. Upon parse failure, ParsePosition error index is updated to * the offset of the source text which does not match the supplied format. - * + * * @param source The text to parse. * @param pos On input, the position in the source to start parsing, on output, updated position. * @param calendar The calendar into which to set parsed fields. @@ -566,7 +566,7 @@ public class FastDateParser implements DateParser, Serializable { return getLocaleSpecificStrategy(Calendar.ERA, definingCalendar); case 'H': // Hour in day (0-23) return HOUR_OF_DAY_STRATEGY; - case 'K': // Hour in am/pm (0-11) + case 'K': // Hour in am/pm (0-11) return HOUR_STRATEGY; case 'M': return width>=3 ?getLocaleSpecificStrategy(Calendar.MONTH, definingCalendar) :NUMBER_MONTH_STRATEGY; @@ -632,7 +632,7 @@ public class FastDateParser implements DateParser, Serializable { final ConcurrentMap<Locale, Strategy> cache = getCache(field); Strategy strategy = cache.get(locale); if (strategy == null) { - strategy = field == Calendar.ZONE_OFFSET + strategy = field == Calendar.ZONE_OFFSET ? new TimeZoneStrategy(locale) : new CaseInsensitiveTextStrategy(field, definingCalendar, locale); final Strategy inCache = cache.putIfAbsent(locale, strategy); @@ -701,7 +701,7 @@ public class FastDateParser implements DateParser, Serializable { CaseInsensitiveTextStrategy(final int field, final Calendar definingCalendar, final Locale locale) { this.field = field; this.locale = locale; - + final StringBuilder regex = new StringBuilder(); regex.append("((?iu)"); lKeyValues = appendDisplayNames(definingCalendar, locale, field, regex); @@ -903,9 +903,9 @@ public class FastDateParser implements DateParser, Serializable { } } } - + private static class ISO8601TimeZoneStrategy extends PatternStrategy { - // Z, +hh, -hh, +hhmm, -hhmm, +hh:mm or -hh:mm + // Z, +hh, -hh, +hhmm, -hhmm, +hh:mm or -hh:mm /** * Construct a Strategy that parses a TimeZone @@ -914,7 +914,7 @@ public class FastDateParser implements DateParser, Serializable { ISO8601TimeZoneStrategy(final String pattern) { createPattern(pattern); } - + /** * {@inheritDoc} */ @@ -926,14 +926,14 @@ public class FastDateParser implements DateParser, Serializable { cal.setTimeZone(TimeZone.getTimeZone("GMT" + value)); } } - + private static final Strategy ISO_8601_1_STRATEGY = new ISO8601TimeZoneStrategy("(Z|(?:[+-]\\d{2}))"); private static final Strategy ISO_8601_2_STRATEGY = new ISO8601TimeZoneStrategy("(Z|(?:[+-]\\d{2}\\d{2}))"); private static final Strategy ISO_8601_3_STRATEGY = new ISO8601TimeZoneStrategy("(Z|(?:[+-]\\d{2}(?::)\\d{2}))"); /** * Factory method for ISO8601TimeZoneStrategies. - * + * * @param tokenLen a token indicating the length of the TimeZone String to be formatted. * @return a ISO8601TimeZoneStrategy that can format TimeZone String of length {@code tokenLen}. If no such * strategy exists, an IllegalArgumentException will be thrown. http://git-wip-us.apache.org/repos/asf/commons-lang/blob/1da8ccdb/src/main/java/org/apache/commons/lang3/time/FastDatePrinter.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/lang3/time/FastDatePrinter.java b/src/main/java/org/apache/commons/lang3/time/FastDatePrinter.java index fafa71c..b603fac 100644 --- a/src/main/java/org/apache/commons/lang3/time/FastDatePrinter.java +++ b/src/main/java/org/apache/commons/lang3/time/FastDatePrinter.java @@ -37,14 +37,14 @@ import org.apache.commons.lang3.exception.ExceptionUtils; * <p>FastDatePrinter is a fast and thread-safe version of * {@link java.text.SimpleDateFormat}.</p> * - * <p>To obtain a FastDatePrinter, use {@link FastDateFormat#getInstance(String, TimeZone, Locale)} + * <p>To obtain a FastDatePrinter, use {@link FastDateFormat#getInstance(String, TimeZone, Locale)} * or another variation of the factory methods of {@link FastDateFormat}.</p> - * + * * <p>Since FastDatePrinter is thread safe, you can use a static member instance:</p> * <code> * private static final DatePrinter DATE_PRINTER = FastDateFormat.getInstance("yyyy-MM-dd"); * </code> - * + * * <p>This class can be used as a direct replacement to * {@code SimpleDateFormat} in most formatting situations. * This class is especially useful in multi-threaded server environments. @@ -63,7 +63,7 @@ import org.apache.commons.lang3.exception.ExceptionUtils; * ISO 8601 extended format time zones (eg. {@code +08:00} or {@code -11:00}). * This introduces a minor incompatibility with Java 1.4, but at a gain of * useful functionality.</p> - * + * * <p>Starting with JDK7, ISO 8601 support was added using the pattern {@code 'X'}. * To maintain compatibility, {@code 'ZZ'} will continue to be supported, but using * one of the {@code 'X'} formats is recommended. @@ -139,7 +139,7 @@ public class FastDatePrinter implements DatePrinter, Serializable { //----------------------------------------------------------------------- /** * <p>Constructs a new FastDatePrinter.</p> - * Use {@link FastDateFormat#getInstance(String, TimeZone, Locale)} or another variation of the + * Use {@link FastDateFormat#getInstance(String, TimeZone, Locale)} or another variation of the * factory methods of {@link FastDateFormat} to get a cached FastDatePrinter instance. * * @param pattern {@link java.text.SimpleDateFormat} compatible pattern @@ -276,9 +276,9 @@ public class FastDatePrinter implements DatePrinter, Serializable { case 'K': // hour in am/pm (0..11) rule = selectNumberRule(Calendar.HOUR, tokenLen); break; - case 'X': // ISO 8601 + case 'X': // ISO 8601 rule = Iso8601_Rule.getRule(tokenLen); - break; + break; case 'z': // time zone (text) if (tokenLen >= 4) { rule = new TimeZoneNameRule(mTimeZone, mLocale, TimeZone.LONG); @@ -632,7 +632,7 @@ public class FastDatePrinter implements DatePrinter, Serializable { } final FastDatePrinter other = (FastDatePrinter) obj; return mPattern.equals(other.mPattern) - && mTimeZone.equals(other.mTimeZone) + && mTimeZone.equals(other.mTimeZone) && mLocale.equals(other.mLocale); } @@ -1347,7 +1347,7 @@ public class FastDatePrinter implements DatePrinter, Serializable { TimeZoneNameRule(final TimeZone timeZone, final Locale locale, final int style) { mLocale = locale; mStyle = style; - + mStandard = getTimeZoneDisplay(timeZone, false, style, locale); mDaylight = getTimeZoneDisplay(timeZone, true, style, locale); } @@ -1384,7 +1384,7 @@ public class FastDatePrinter implements DatePrinter, Serializable { private static class TimeZoneNumberRule implements Rule { static final TimeZoneNumberRule INSTANCE_COLON = new TimeZoneNumberRule(true); static final TimeZoneNumberRule INSTANCE_NO_COLON = new TimeZoneNumberRule(false); - + final boolean mColon; /** @@ -1409,7 +1409,7 @@ public class FastDatePrinter implements DatePrinter, Serializable { */ @Override public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException { - + int offset = calendar.get(Calendar.ZONE_OFFSET) + calendar.get(Calendar.DST_OFFSET); if (offset < 0) { @@ -1436,9 +1436,9 @@ public class FastDatePrinter implements DatePrinter, Serializable { * or {@code +/-HH:MM}.</p> */ private static class Iso8601_Rule implements Rule { - + // Sign TwoDigitHours or Z - static final Iso8601_Rule ISO8601_HOURS = new Iso8601_Rule(3); + static final Iso8601_Rule ISO8601_HOURS = new Iso8601_Rule(3); // Sign TwoDigitHours Minutes or Z static final Iso8601_Rule ISO8601_HOURS_MINUTES = new Iso8601_Rule(5); // Sign TwoDigitHours : Minutes or Z @@ -1460,10 +1460,10 @@ public class FastDatePrinter implements DatePrinter, Serializable { case 3: return Iso8601_Rule.ISO8601_HOURS_COLON_MINUTES; default: - throw new IllegalArgumentException("invalid number of X"); + throw new IllegalArgumentException("invalid number of X"); } - } - + } + final int length; /** @@ -1493,7 +1493,7 @@ public class FastDatePrinter implements DatePrinter, Serializable { buffer.append("Z"); return; } - + if (offset < 0) { buffer.append('-'); offset = -offset; @@ -1507,7 +1507,7 @@ public class FastDatePrinter implements DatePrinter, Serializable { if (length<5) { return; } - + if (length==6) { buffer.append(':'); } http://git-wip-us.apache.org/repos/asf/commons-lang/blob/1da8ccdb/src/main/java/org/apache/commons/lang3/time/FormatCache.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/lang3/time/FormatCache.java b/src/main/java/org/apache/commons/lang3/time/FormatCache.java index 22850f6..f6ff481 100644 --- a/src/main/java/org/apache/commons/lang3/time/FormatCache.java +++ b/src/main/java/org/apache/commons/lang3/time/FormatCache.java @@ -5,9 +5,9 @@ * 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. @@ -29,27 +29,27 @@ import org.apache.commons.lang3.Validate; /** * <p>FormatCache is a cache and factory for {@link Format}s.</p> - * + * * @since 3.0 */ // TODO: Before making public move from getDateTimeInstance(Integer,...) to int; or some other approach. abstract class FormatCache<F extends Format> { - + /** * No date or no time. Used in same parameters as DateFormat.SHORT or DateFormat.LONG */ static final int NONE= -1; - - private final ConcurrentMap<MultipartKey, F> cInstanceCache + + private final ConcurrentMap<MultipartKey, F> cInstanceCache = new ConcurrentHashMap<>(7); - - private static final ConcurrentMap<MultipartKey, String> cDateTimeInstanceCache + + private static final ConcurrentMap<MultipartKey, String> cDateTimeInstanceCache = new ConcurrentHashMap<>(7); /** * <p>Gets a formatter instance using the default pattern in the * default timezone and locale.</p> - * + * * @return a date/time formatter */ public F getInstance() { @@ -59,7 +59,7 @@ abstract class FormatCache<F extends Format> { /** * <p>Gets a formatter instance using the specified pattern, time zone * and locale.</p> - * + * * @param pattern {@link java.text.SimpleDateFormat} compatible * pattern, non-null * @param timeZone the time zone, null means use the default TimeZone @@ -78,22 +78,22 @@ abstract class FormatCache<F extends Format> { } final MultipartKey key = new MultipartKey(pattern, timeZone, locale); F format = cInstanceCache.get(key); - if (format == null) { + if (format == null) { format = createInstance(pattern, timeZone, locale); final F previousValue= cInstanceCache.putIfAbsent(key, format); if (previousValue != null) { // another thread snuck in and did the same work // we should return the instance that is in ConcurrentMap - format= previousValue; + format= previousValue; } } return format; } - + /** * <p>Create a format instance using the specified pattern, time zone * and locale.</p> - * + * * @param pattern {@link java.text.SimpleDateFormat} compatible pattern, this will not be null. * @param timeZone time zone, this will not be null. * @param locale locale, this will not be null. @@ -102,11 +102,11 @@ abstract class FormatCache<F extends Format> { * or <code>null</code> */ abstract protected F createInstance(String pattern, TimeZone timeZone, Locale locale); - + /** * <p>Gets a date/time formatter instance using the specified style, * time zone and locale.</p> - * + * * @param dateStyle date style: FULL, LONG, MEDIUM, or SHORT, null indicates no date in format * @param timeStyle time style: FULL, LONG, MEDIUM, or SHORT, null indicates no time in format * @param timeZone optional time zone, overrides time zone of @@ -116,7 +116,7 @@ abstract class FormatCache<F extends Format> { * @throws IllegalArgumentException if the Locale has no date/time * pattern defined */ - // This must remain private, see LANG-884 + // This must remain private, see LANG-884 private F getDateTimeInstance(final Integer dateStyle, final Integer timeStyle, final TimeZone timeZone, Locale locale) { if (locale == null) { locale = Locale.getDefault(); @@ -128,7 +128,7 @@ abstract class FormatCache<F extends Format> { /** * <p>Gets a date/time formatter instance using the specified style, * time zone and locale.</p> - * + * * @param dateStyle date style: FULL, LONG, MEDIUM, or SHORT * @param timeStyle time style: FULL, LONG, MEDIUM, or SHORT * @param timeZone optional time zone, overrides time zone of @@ -146,7 +146,7 @@ abstract class FormatCache<F extends Format> { /** * <p>Gets a date formatter instance using the specified style, * time zone and locale.</p> - * + * * @param dateStyle date style: FULL, LONG, MEDIUM, or SHORT * @param timeZone optional time zone, overrides time zone of * formatted date, null means use default Locale @@ -163,7 +163,7 @@ abstract class FormatCache<F extends Format> { /** * <p>Gets a time formatter instance using the specified style, * time zone and locale.</p> - * + * * @param timeStyle time style: FULL, LONG, MEDIUM, or SHORT * @param timeZone optional time zone, overrides time zone of * formatted date, null means use default Locale @@ -179,7 +179,7 @@ abstract class FormatCache<F extends Format> { /** * <p>Gets a date/time format for the specified styles and locale.</p> - * + * * @param dateStyle date style: FULL, LONG, MEDIUM, or SHORT, null indicates no date in format * @param timeStyle time style: FULL, LONG, MEDIUM, or SHORT, null indicates no time in format * @param locale The non-null locale of the desired format @@ -195,10 +195,10 @@ abstract class FormatCache<F extends Format> { try { DateFormat formatter; if (dateStyle == null) { - formatter = DateFormat.getTimeInstance(timeStyle.intValue(), locale); + formatter = DateFormat.getTimeInstance(timeStyle.intValue(), locale); } else if (timeStyle == null) { - formatter = DateFormat.getDateInstance(dateStyle.intValue(), locale); + formatter = DateFormat.getDateInstance(dateStyle.intValue(), locale); } else { formatter = DateFormat.getDateTimeInstance(dateStyle.intValue(), timeStyle.intValue(), locale);
