Package com.norconex.commons.lang.time

# Class DurationParser

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

public class DurationParser extends Object

Parse a textual representation of a duration and converts it into a `long` millisecond value.

If the string is made of digits only, it is assumed to be a millisecond and the value will remain the same.

The duration unit can be written in single character or full words. Some abbreviations are also accepted (e.g., "mo", "mos", "mth", "mths").

Languages supported are English (default) and French (since 2.0.0). Here is are acceptable values for each duration units.

## English:

- Y,yr,yrs,year,years
- M,mo,mos,mth,mths,month,months
- W,wk,wks,week,weeks
- D,day,days
- h,hs,hrs,hour,hours
- m,min,mins,minute,minutes
- s,sec,secs,second,seconds
- ms,msec,msecs,millis,millisecond,milliseconds

## French:

- A,an,ans,année,années
- M,mo,mos,mois
- S,sem,sems,semaine,semaines
- J,jour,jours,journée,journées
- h,hr,hrs,heure,heures
- m,min,mins,minute,minutes
- s,sec,secs,seconde,secondes
- ms,msec,msecs,millis,milliseconde,millisecondes

Single-character representation are case sensitive. Other terms are not. No distinction is made between plural and singular. Numeric values can be integers or decimals numbers (e.g., 2.5 months). One year uses the average of 365.2425 days and a month is 1/12th of that. A numeric value must be followed by a time unit. Other terms or characters are ignored.

## Examples:

All of the following will be parsed properly:

- 3 hours, 30 minute, and 30 seconds
- 6h10m23s
- 2.5hrs
- 10y9 months, 8 d, 7hrs, 6 minute, and 5.5 Seconds
- 2 ans et 3 mois

This class is thread-safe and immutable.

Since:
  1.13.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DurationParser()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected boolean`
  `canEqual(Object other)`
  `boolean`
  `equals(Object o)`
  `Locale`
  `getLocale()`
  `int`
  `hashCode()`
  `Duration`
  `parse(String duration)`
  Parses a text representation of a duration.
  `Duration`
  `parse(String duration, Duration defaultValue)`
  Parses a text representation of a duration.
  `long`
  `parseToMillis(String duration)`
  Parses a text representation of a duration.
  `long`
  `parseToMillis(String duration, long defaultValue)`
  Parses a text representation of a duration.
  `String`
  `toString()`
  `DurationParser`
  `withLocale(Locale locale)`
  Creates a copy if this parser with the given locale.

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

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

- ## Constructor Details

  - ### DurationParser

    public DurationParser()

- ## Method Details

  - ### withLocale

    public DurationParser withLocale(Locale locale)
    Creates a copy if this parser with the given locale. Default locale is English.
    Parameters:
      `locale` - locale
    Returns:
      duration parser copy

  - ### getLocale

    public Locale getLocale()

  - ### parse

    public Duration parse(String duration)
    Parses a text representation of a duration. If the value cannot be parsed, a `DurationParserException` is thrown. Default value is zero (no duration).
    Parameters:
      `duration` - the duration text to parse
    Returns:
      duration

  - ### parse

    public Duration parse(String duration, Duration defaultValue)
    Parses a text representation of a duration. If the value cannot be parsed, the default value is returned (no exception is thrown).
    Parameters:
      `duration` - the duration text to parse
      `defaultValue` - default value
    Returns:
      duration

  - ### parseToMillis

    public long parseToMillis(String duration)
    Parses a text representation of a duration. If the value cannot be parsed, a `DurationParserException` is thrown. Default value is zero (no duration)
    Parameters:
      `duration` - the duration text to parse
    Returns:
      milliseconds

  - ### parseToMillis

    public long parseToMillis(String duration, long defaultValue)
    Parses a text representation of a duration. If the value cannot be parsed, the default value is returned (no exception is thrown).
    Parameters:
      `duration` - the duration text to parse
      `defaultValue` - default value
    Returns:
      milliseconds

  - ### toString

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

  - ### 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`