Package org.zkoss.util

## Class Dates

- java.lang.Object
- - org.zkoss.util.Dates

-     public class Dates
      extends java.lang.Object

  Utilities for java.util.Date
  Author:
    henrichen, tomyeh

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Dates()` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static java.util.Date` | `add​(java.util.Date when, java.util.TimeZone tz, int field, int amount)` | Date Arithmetic function.
    `static java.util.Date` | `beginOfDate​(java.util.Date when, java.util.TimeZone tz)` | Given a date, a proper TimeZone, return the beginning date of the specified date and TimeZone.
    `static java.util.Date` | `beginOfMonth()` | Return the beginning date of this month.
    `static java.util.Date` | `beginOfMonth​(java.util.Date when, java.util.TimeZone tz)` | Given a date, a proper TimeZone, return the beginning date of the month of the specified date and TimeZone.
    `static java.util.Date` | `beginOfYear()` | Return the beginning date of this year.
    `static java.util.Date` | `beginOfYear​(java.util.Date when, java.util.TimeZone tz)` | Given a date, a proper TimeZone, return the beginning date of the month of the specified date and TimeZone.
    `static int` | `dayMonthOfDate​(java.util.Date when, java.util.TimeZone tz)` | Get the day of month of a date.
    `static java.util.Date` | `endOfDate​(java.util.Date when, java.util.TimeZone tz)` | Given a date, a proper TimeZone, return the last millisecond date of the specified date and TimeZone.
    `static java.util.Date` | `endOfMonth()` | Return the ending date of this month.
    `static java.util.Date` | `endOfMonth​(java.util.Date when, java.util.TimeZone tz)` | Given a date, a proper TimeZone, return the ending date of the month of the specified date and TimeZone.
    `static java.util.Date` | `endOfYear()` | Return the ending date of this year.
    `static java.util.Date` | `endOfYear​(java.util.Date when, java.util.TimeZone tz)` | Given a date, a proper TimeZone, return the ending date of the month of the specified date and TimeZone.
    `static long` | `getTimezoneOffset​(java.util.TimeZone timezone, java.util.Date date)` | Returns the timezone offset.
    `static boolean` | `isBeginOfMonth​(java.util.Date when, java.util.TimeZone tz)` | Whether the given date in the specified TimeZone is the first day of that month.
    `static boolean` | `isEndOfMonth​(java.util.Date when, java.util.TimeZone tz)` | Whether the given date in the specified TimeZone is the last day of that month.
    `static boolean` | `isRounded​(java.util.Date date, int precision)` | Tests whether a date is rounded.
    `static int` | `localizedYearOfDate​(java.util.Date when, java.util.Locale locale, java.util.TimeZone tz)` | Get the year of a date in the specified locale.
    `static java.util.Date` | `merge​(java.util.Date datePart, java.util.Date timePart, java.util.TimeZone tz)` | merge the date part and time part of two specified dates into a date.
    `static int` | `monthOfDate​(java.util.Date when, java.util.TimeZone tz)` | Get the month of a date.
    `static int` | `monthOfDatePlus1​(java.util.Date when, java.util.TimeZone tz)` | Get the month of a date.
    `static java.util.Date` | `now()` | Returns the current time without rounding.
    `static java.util.Date` | `now​(int precision)` | Returns the current time but rounding to the specified precision of milliseconds.
    `static java.util.Date` | `previousDate​(java.util.Date when)` | Given a date, return the previous date of the given date (24 hrs before).
    `static long` | `round​(long time, int precision)` | Rounds a date represented in long to the specified precision of milliseconds.
    `static java.util.Date` | `round​(java.util.Date date, int precision)` | Truncates date to the nearest precision milliseconds.
    `static long` | `subtract​(java.util.Date date2, java.util.TimeZone tz, int field, java.util.Date date1)` | Date Arithmetic function (date2 - date1). subtract a date from another date, return the difference as the required fields.
    `static java.util.Date` | `today()` | Returns today by setting time to 0:0:0.
    `static short` | `twoMonthShort()` | Return the ending date of this year.
    `static short` | `twoMonthShort​(java.util.Date when, java.util.TimeZone tz)` | Given a date, a proper TimeZone, return the two month int. e.g. 1, 3, 5, 7, 9, 11.
    `static int` | `yearOfDate​(java.util.Date when, java.util.TimeZone tz)` | Get the year of a date.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Dates

          public Dates()

  - ### Method Detail

    - #### round

          public static final java.util.Date round​(java.util.Date date,
                                                   int precision)

      Truncates date to the nearest precision milliseconds. MS SQLServer2000 with only the maximum accuracy of 1/300 seconds would not be able to store up to one millisecond accuracy. That is, User must round the millisecond to some less precisions; or the data in that db would be inconsistent with that in memory. It is useful to store a Date object in a database. Without rounding, if you want to get it back and compare with the one in the memory. See `now(int)` for details.
      Parameters:
        `precision` - the divider of the precision(e.g. 10 for precision of 10 milliseconds;i.e. all millisecond less than 10 would be truncated)
      See Also:
        `now(int)`, `round(long, int)`

    - #### round

          public static final long round​(long time,
                                         int precision)

      Rounds a date represented in long to the specified precision of milliseconds.
      Parameters:
        `time` - the date represented in long.
        `precision` - the divider of the precision(e.g. 10 for precision of 10 milliseconds;i.e. all millisecond less than 10 would be truncated)
      See Also:
        `now(int)`, `round(Date, int)`

    - #### isRounded

          public static final boolean isRounded​(java.util.Date date,
                                                int precision)

      Tests whether a date is rounded. It is mainly used for debugging.

    - #### now

          public static final java.util.Date now​(int precision)

      Returns the current time but rounding to the specified precision of milliseconds. It is useful if you want to create the current time which will be stored in the database and want to compare it with something with what you store in the database. Otherwise, that you get back the one you store might be different, because the resolution of database timestamp is usually less than one millisecond, e.g., MS SQL: 0.003 second.

      If you don't cache it in the memory (remember entity beans always cache by the container), you don't need to round. If you are not sure, round it.

      See Also:
        `round(Date, int)`

    - #### now

          public static final java.util.Date now()

      Returns the current time without rounding.

    - #### today

          public static final java.util.Date today()

      Returns today by setting time to 0:0:0.

    - #### previousDate

          public static final java.util.Date previousDate​(java.util.Date when)

      Given a date, return the previous date of the given date (24 hrs before).

    - #### beginOfMonth

          public static final java.util.Date beginOfMonth()

      Return the beginning date of this month.

    - #### beginOfMonth

          public static final java.util.Date beginOfMonth​(java.util.Date when,
                                                          java.util.TimeZone tz)

      Given a date, a proper TimeZone, return the beginning date of the month of the specified date and TimeZone. If TimeZone is null, meaning use default TimeZone of the JVM.

    - #### endOfMonth

          public static final java.util.Date endOfMonth()

      Return the ending date of this month.

    - #### endOfMonth

          public static final java.util.Date endOfMonth​(java.util.Date when,
                                                        java.util.TimeZone tz)

      Given a date, a proper TimeZone, return the ending date of the month of the specified date and TimeZone. If TimeZone is null, meaning use default TimeZone of the JVM.

    - #### isEndOfMonth

          public static final boolean isEndOfMonth​(java.util.Date when,
                                                   java.util.TimeZone tz)

      Whether the given date in the specified TimeZone is the last day of that month. If TimeZone is null, meaning use default TimeZone of the JVM.

    - #### isBeginOfMonth

          public static final boolean isBeginOfMonth​(java.util.Date when,
                                                     java.util.TimeZone tz)

      Whether the given date in the specified TimeZone is the first day of that month. If TimeZone is null, meaning use default TimeZone of the JVM.

    - #### beginOfDate

          public static final java.util.Date beginOfDate​(java.util.Date when,
                                                         java.util.TimeZone tz)

      Given a date, a proper TimeZone, return the beginning date of the specified date and TimeZone. If TimeZone is null, meaning use Default TimeZone of the JVM.

    - #### endOfDate

          public static final java.util.Date endOfDate​(java.util.Date when,
                                                       java.util.TimeZone tz)

      Given a date, a proper TimeZone, return the last millisecond date of the specified date and TimeZone. If TimeZone is null, meaning use Default TimeZone of the JVM.

    - #### beginOfYear

          public static final java.util.Date beginOfYear()

      Return the beginning date of this year.

    - #### beginOfYear

          public static final java.util.Date beginOfYear​(java.util.Date when,
                                                         java.util.TimeZone tz)

      Given a date, a proper TimeZone, return the beginning date of the month of the specified date and TimeZone. If TimeZone is null, meaning use default TimeZone of the JVM.

    - #### endOfYear

          public static final java.util.Date endOfYear()

      Return the ending date of this year.

    - #### endOfYear

          public static final java.util.Date endOfYear​(java.util.Date when,
                                                       java.util.TimeZone tz)

      Given a date, a proper TimeZone, return the ending date of the month of the specified date and TimeZone. If TimeZone is null, meaning use default TimeZone of the JVM.

    - #### twoMonthShort

          public static final short twoMonthShort()

      Return the ending date of this year.

    - #### twoMonthShort

          public static final short twoMonthShort​(java.util.Date when,
                                                  java.util.TimeZone tz)

      Given a date, a proper TimeZone, return the two month int. e.g. 1, 3, 5, 7, 9, 11. If TimeZone is null, meaning use default TimeZone of the JVM.

    - #### yearOfDate

          public static final int yearOfDate​(java.util.Date when,
                                             java.util.TimeZone tz)

      Get the year of a date.
      Parameters:
        `when` - The date.
        `tz` - The time zone; if null, the current time zone is assumed.
      See Also:
        `localizedYearOfDate(java.util.Date, java.util.Locale, java.util.TimeZone)`

    - #### localizedYearOfDate

          public static final int localizedYearOfDate​(java.util.Date when,
                                                      java.util.Locale locale,
                                                      java.util.TimeZone tz)

      Get the year of a date in the specified locale.

      Currently, only Locale.ZH_TW is supported, i.e., "year - 1911" and it's may be less than 0. Otherwise, it is the same as `yearOfDate(java.util.Date, java.util.TimeZone)`.

      Parameters:
        `when` - The date.
        `locale` - the locale; if null, the current locale is assumed.
        `tz` - The time zone; if null, the current time zone is assumed.
      See Also:
        `yearOfDate(java.util.Date, java.util.TimeZone)`

    - #### monthOfDate

          public static final int monthOfDate​(java.util.Date when,
                                              java.util.TimeZone tz)

      Get the month of a date. The first month of the year is JANUARY which is 0.
      Parameters:
        `when` - The date.
        `tz` - The time zone; if null, the current time zone is assumed.

    - #### monthOfDatePlus1

          public static final int monthOfDatePlus1​(java.util.Date when,
                                                   java.util.TimeZone tz)

      Get the month of a date. The first month of the year is JANUARY which is 1.
      Parameters:
        `when` - The date.
        `tz` - The time zone; if null, the current time zone is assumed.

    - #### dayMonthOfDate

          public static final int dayMonthOfDate​(java.util.Date when,
                                                 java.util.TimeZone tz)

      Get the day of month of a date. The first day of the month has value 1.
      Parameters:
        `when` - The date.
        `tz` - The time zone; if null, the current time zone is assumed.

    - #### add

          public static final java.util.Date add​(java.util.Date when,
                                                 java.util.TimeZone tz,
                                                 int field,
                                                 int amount)

      Date Arithmetic function. Adds the specified (signed) amount of time to the given date, based on the calendar's rules.
      Parameters:
        `when` - The based date.
        `tz` - The time zone; if null, the current time zone is assumed.
        `field` - The time field.
        `amount` - The amount of date or time to be added to the field.

    - #### subtract

          public static final long subtract​(java.util.Date date2,
                                            java.util.TimeZone tz,
                                            int field,
                                            java.util.Date date1)

      Date Arithmetic function (date2 - date1). subtract a date from another date, return the difference as the required fields. E.g. if specified Calendar.Date, the smaller range of fields is ignored and this method return the difference of days.
      Parameters:
        `date2` - The date2.
        `tz` - The time zone.
        `field` - The time field; e.g., Calendar.DATE, Calendar.YEAR, it's default value is Calendar.DATE
        `date1` - The date1.

    - #### merge

          public static final java.util.Date merge​(java.util.Date datePart,
                                                   java.util.Date timePart,
                                                   java.util.TimeZone tz)

      merge the date part and time part of two specified dates into a date.
      Parameters:
        `datePart` - The date part date.
        `timePart` - The time part date.
        `tz` - The time zone.

    - #### getTimezoneOffset

          public static final long getTimezoneOffset​(java.util.TimeZone timezone,
                                                     java.util.Date date)

      Returns the timezone offset.
      Parameters:
        `timezone` - The time zone.
        `date` -
      Returns:
        long