Package com.norconex.commons.lang.time

# Class ZonedDateTimeParser

java.lang.Object
com.norconex.commons.lang.time.ZonedDateTimeParser

public class ZonedDateTimeParser extends Object

Parses a string representation of a date to a `ZonedDateTime`.

## Supported date string formats

- A string parsable by `DateTimeFormatter`, as per the format specified in `getFormat()`. If the parser format represents a date without time, it will be set at the beginning of the day (midnight). If no format is explicitly set on the parser, parsing using other supported formats will be attempted before throwing a `DateTimeException`.
- Digits only, representing milliseconds (EPOCH date).
- `TODAY[-+]9[YMDhms]` (see "Relative Dates" below)
- `NOW[-+]9[YMDhms]` (see "Relative Dates" below)

## Time zones

You can dictate which time zone the returned date-time should be, with `setZoneId(ZoneId)`.

If no zone id is set on the parser but the parser date format has a zone symbol, the returned date-time value will be set to the time zone detected in the date string value (if present). If no time zone is detected, the returned date-time zone will be UTC.

If a zone id is set on the parser and no time zone was parsed from the date strings, the returned date-time will be set to the parser zone id. Date strings with detected time zones will be converted to the parser zone id.

## Relative dates

Date string values can be moment in time relative to the current date using the `TODAY` or `NOW` keyword (case sensitive), optionally followed by a number of time units to add/remove. `TODAY` is the current day without the hours, minutes, and seconds (midnight), where as `NOW` is the current day with the hours, minutes, and seconds. The time units that can be added or subtracted are (case sensitive):

- Y: Year
- M: Month
- D: Day
- h: Hour
- m: Minute
- s: Second

For example, if today's date is July 1st 2023 and you want to represent a year ago (without time), the format value would be: `TODAY-1Y`.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `ZonedDateTimeParser.TimeUnit`
  `static class`
  `ZonedDateTimeParser.ZonedDateTimeParserBuilder`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static ZonedDateTimeParser.ZonedDateTimeParserBuilder`
  `builder()`
  `protected boolean`
  `canEqual(Object other)`
  `boolean`
  `equals(Object o)`
  `String`
  `getFormat()`
  `Locale`
  `getLocale()`
  `ZoneId`
  `getZoneId()`
  `int`
  `hashCode()`
  `ZonedDateTime`
  `parse(String dateString)`
  Parses a string representation of a date.
  `void`
  `setFormat(String format)`
  `void`
  `setLocale(Locale locale)`
  `void`
  `setZoneId(ZoneId zoneId)`
  `String`
  `toString()`

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

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Method Details

  - ### parse

    public ZonedDateTime parse(String dateString)
    Parses a string representation of a date.
    Parameters:
      `dateString` - representation of a date
    Returns:
      a zoned date-time or null if the date string is blank.
    Throws:
      `DateTimeException` - if the date string cannot be parsed

  - ### builder

    public static ZonedDateTimeParser.ZonedDateTimeParserBuilder builder()

  - ### getFormat

    public String getFormat()

  - ### getLocale

    public Locale getLocale()

  - ### getZoneId

    public ZoneId getZoneId()

  - ### setFormat

    public void setFormat(String format)

  - ### setLocale

    public void setLocale(Locale locale)

  - ### setZoneId

    public void setZoneId(ZoneId zoneId)

  - ### equals

    public boolean equals(Object o)
    Overrides:
      `equals` in class `Object`

  - ### canEqual

    protected boolean canEqual(Object other)

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`