org.apache.lucene.document

## Class DateTools

- java.lang.Object
- - org.apache.lucene.document.DateTools

-     public class DateTools
      extends Object

  Provides support for converting dates to strings and vice-versa. The strings are structured so that lexicographic sorting orders them by date, which makes them suitable for use as field values and search terms.

  This class also helps you to limit the resolution of your dates. Do not save dates with a finer resolution than you really need, as then `TermRangeQuery` and `PrefixQuery` will require more memory and become slower.

  Another approach is `LongPoint`, which indexes the values in sorted order. For indexing a `Date` or `Calendar`, just get the unix timestamp as `long` using `Date.getTime()` or `Calendar.getTimeInMillis()` and index this as a numeric value with `LongPoint` and use `PointRangeQuery` to query it.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `DateTools.Resolution` Specifies the time granularity.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static String` | `dateToString(Date date, DateTools.Resolution resolution)` Converts a Date to a string suitable for indexing.
    `static Date` | `round(Date date, DateTools.Resolution resolution)` Limit a date's resolution.
    `static long` | `round(long time, DateTools.Resolution resolution)` Limit a date's resolution.
    `static Date` | `stringToDate(String dateString)` Converts a string produced by `timeToString` or `dateToString` back to a time, represented as a Date object.
    `static long` | `stringToTime(String dateString)` Converts a string produced by `timeToString` or `dateToString` back to a time, represented as the number of milliseconds since January 1, 1970, 00:00:00 GMT.
    `static String` | `timeToString(long time, DateTools.Resolution resolution)` Converts a millisecond time to a string suitable for indexing.

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

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

- - ### Method Detail

    - #### dateToString

          public static String dateToString(Date date,
                                            DateTools.Resolution resolution)

      Converts a Date to a string suitable for indexing.
      Parameters:
        `date` - the date to be converted
        `resolution` - the desired resolution, see `round(Date, DateTools.Resolution)`
      Returns:
        a string in format `yyyyMMddHHmmssSSS` or shorter, depending on `resolution`; using GMT as timezone

    - #### timeToString

          public static String timeToString(long time,
                                            DateTools.Resolution resolution)

      Converts a millisecond time to a string suitable for indexing.
      Parameters:
        `time` - the date expressed as milliseconds since January 1, 1970, 00:00:00 GMT
        `resolution` - the desired resolution, see `round(long, DateTools.Resolution)`
      Returns:
        a string in format `yyyyMMddHHmmssSSS` or shorter, depending on `resolution`; using GMT as timezone

    - #### stringToTime

          public static long stringToTime(String dateString)
                                   throws ParseException

      Converts a string produced by `timeToString` or `dateToString` back to a time, represented as the number of milliseconds since January 1, 1970, 00:00:00 GMT.
      Parameters:
        `dateString` - the date string to be converted
      Returns:
        the number of milliseconds since January 1, 1970, 00:00:00 GMT
      Throws:
        `ParseException` - if `dateString` is not in the expected format

    - #### stringToDate

          public static Date stringToDate(String dateString)
                                   throws ParseException

      Converts a string produced by `timeToString` or `dateToString` back to a time, represented as a Date object.
      Parameters:
        `dateString` - the date string to be converted
      Returns:
        the parsed time as a Date object
      Throws:
        `ParseException` - if `dateString` is not in the expected format

    - #### round

          public static Date round(Date date,
                                   DateTools.Resolution resolution)

      Limit a date's resolution. For example, the date `2004-09-21 13:50:11` will be changed to `2004-09-01 00:00:00` when using `Resolution.MONTH`.
      Parameters:
        `resolution` - The desired resolution of the date to be returned
      Returns:
        the date with all values more precise than `resolution` set to 0 or 1

    - #### round

          public static long round(long time,
                                   DateTools.Resolution resolution)

      Limit a date's resolution. For example, the date `1095767411000` (which represents 2004-09-21 13:50:11) will be changed to `1093989600000` (2004-09-01 00:00:00) when using `Resolution.MONTH`.
      Parameters:
        `resolution` - The desired resolution of the date to be returned
      Returns:
        the date with all values more precise than `resolution` set to 0 or 1, expressed as milliseconds since January 1, 1970, 00:00:00 GMT

Copyright © 2000-2024 Apache Software Foundation. All Rights Reserved.