FastDateParser
Date: 2017-02-08

org.apache.commons.lang3.time

## Class FastDateParser

- java.lang.Object
- - org.apache.commons.lang3.time.FastDateParser

- All Implemented Interfaces:
    java.io.Serializable, DateParser

      public class FastDateParser
      extends java.lang.Object
      implements DateParser, java.io.Serializable

  FastDateParser is a fast and thread-safe version of `SimpleDateFormat`.

  To obtain a proxy to a FastDateParser, use `FastDateFormat.getInstance(String, TimeZone, Locale)` or another variation of the factory methods of `FastDateFormat`.

  Since FastDateParser is thread safe, you can use a static member instance:

  `private static final DateParser DATE_PARSER = FastDateFormat.getInstance("yyyy-MM-dd");`

  This class can be used as a direct replacement for `SimpleDateFormat` in most parsing situations. This class is especially useful in multi-threaded server environments. `SimpleDateFormat` is not thread-safe in any JDK version, nor will it be as Sun has closed the bug/RFE.

  Only parsing is supported by this class, but all patterns are compatible with SimpleDateFormat.

  The class operates in lenient mode, so for example a time of 90 minutes is treated as 1 hour 30 minutes.

  Timing tests indicate this class is as about as fast as SimpleDateFormat in single thread applications and about 25% faster in multi-thread applications.

  Since:
    3.2
  See Also:
    `FastDatePrinter`, Serialized Form

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `FastDateParser(java.lang.String pattern, java.util.TimeZone timeZone, java.util.Locale locale)` Constructs a new FastDateParser.
    `protected` | `FastDateParser(java.lang.String pattern, java.util.TimeZone timeZone, java.util.Locale locale, java.util.Date centuryStart)` Constructs a new FastDateParser.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object obj)` Compare another object for equality with this object.
    `java.util.Locale` | `getLocale()` Get the locale used by this parser.
    `java.lang.String` | `getPattern()` Get the pattern used by this parser.
    `java.util.TimeZone` | `getTimeZone()` Get the time zone used by this parser.
    `int` | `hashCode()` Return a hashcode compatible with equals.
    `java.util.Date` | `parse(java.lang.String source)` Equivalent to DateFormat.parse(String).
    `java.util.Date` | `parse(java.lang.String source, java.text.ParsePosition pos)` This implementation updates the ParsePosition if the parse succeeds.
    `boolean` | `parse(java.lang.String source, java.text.ParsePosition pos, java.util.Calendar calendar)` Parse a formatted date string according to the format.
    `java.lang.Object` | `parseObject(java.lang.String source)` Parses text from a string to produce a Date.
    `java.lang.Object` | `parseObject(java.lang.String source, java.text.ParsePosition pos)` Parse a date/time string according to the given parse position.
    `java.lang.String` | `toString()` Get a string version of this formatter.

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

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

- - ### Constructor Detail

    - #### FastDateParser

          protected FastDateParser(java.lang.String pattern,
                        java.util.TimeZone timeZone,
                        java.util.Locale locale)

      Constructs a new FastDateParser.

      Use `FastDateFormat.getInstance(String, TimeZone, Locale)` or another variation of the factory methods of `FastDateFormat` to get a cached FastDateParser instance.
      Parameters:
        `pattern` - non-null `SimpleDateFormat` compatible pattern
        `timeZone` - non-null time zone to use
        `locale` - non-null locale

    - #### FastDateParser

          protected FastDateParser(java.lang.String pattern,
                        java.util.TimeZone timeZone,
                        java.util.Locale locale,
                        java.util.Date centuryStart)

      Constructs a new FastDateParser.

      Parameters:
        `pattern` - non-null `SimpleDateFormat` compatible pattern
        `timeZone` - non-null time zone to use
        `locale` - non-null locale
        `centuryStart` - The start of the century for 2 digit year parsing
      Since:
        3.5

  - ### Method Detail

    - #### getPattern

          public java.lang.String getPattern()

      Description copied from interface: `DateParser`

      Get the pattern used by this parser.

      Specified by:
        `getPattern` in interface `DateParser`
      Returns:
        the pattern, `SimpleDateFormat` compatible

    - #### getTimeZone

          public java.util.TimeZone getTimeZone()

      Description copied from interface: `DateParser`

      Get the time zone used by this parser.

      The default `TimeZone` used to create a `Date` when the `TimeZone` is not specified by the format pattern.

      Specified by:
        `getTimeZone` in interface `DateParser`
      Returns:
        the time zone

    - #### getLocale

          public java.util.Locale getLocale()

      Description copied from interface: `DateParser`

      Get the locale used by this parser.

      Specified by:
        `getLocale` in interface `DateParser`
      Returns:
        the locale

    - #### equals

          public boolean equals(java.lang.Object obj)

      Compare another object for equality with this object.

      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `obj` - the object to compare to
      Returns:
        `true`if equal to this instance

    - #### hashCode

          public int hashCode()

      Return a hashcode compatible with equals.

      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        a hashcode compatible with equals

    - #### toString

          public java.lang.String toString()

      Get a string version of this formatter.

      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a debugging string

    - #### parseObject

          public java.lang.Object parseObject(java.lang.String source)
                                       throws java.text.ParseException

      Description copied from interface: `DateParser`
      Parses text from a string to produce a Date.
      Specified by:
        `parseObject` in interface `DateParser`
      Parameters:
        `source` - A `String` whose beginning should be parsed.
      Returns:
        a `java.util.Date` object
      Throws:
        `java.text.ParseException` - if the beginning of the specified string cannot be parsed.
      See Also:
        `Format.parseObject(String)`

    - #### parse

          public java.util.Date parse(java.lang.String source)
                               throws java.text.ParseException

      Description copied from interface: `DateParser`
      Equivalent to DateFormat.parse(String). See `DateFormat.parse(String)` for more information.
      Specified by:
        `parse` in interface `DateParser`
      Parameters:
        `source` - A `String` whose beginning should be parsed.
      Returns:
        A `Date` parsed from the string
      Throws:
        `java.text.ParseException` - if the beginning of the specified string cannot be parsed.

    - #### parseObject

          public java.lang.Object parseObject(java.lang.String source,
                                     java.text.ParsePosition pos)

      Description copied from interface: `DateParser`
      Parse a date/time string according to the given parse position.
      Specified by:
        `parseObject` in interface `DateParser`
      Parameters:
        `source` - A `String` whose beginning should be parsed.
        `pos` - the parse position
      Returns:
        a `java.util.Date` object
      See Also:
        `DateFormat.parseObject(String, ParsePosition)`

    - #### parse

          public java.util.Date parse(java.lang.String source,
                             java.text.ParsePosition pos)

      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 `SimpleDateFormat.parse(String, ParsePosition)` which sets the error index to after the failed field.

      To determine if the parse has succeeded, the caller must check if the current parse position given by `ParsePosition.getIndex()` has been updated. If the input buffer has been fully parsed, then the index will point to just after the end of the input buffer.

      Specified by:
        `parse` in interface `DateParser`
      Parameters:
        `source` - A `String`, part of which should be parsed.
        `pos` - A `ParsePosition` object with index and error index information as described above.
      Returns:
        A `Date` parsed from the string. In case of error, returns null.
      See Also:
        `DateParser.parse(java.lang.String, java.text.ParsePosition)`

    - #### parse

          public boolean parse(java.lang.String source,
                      java.text.ParsePosition pos,
                      java.util.Calendar calendar)

      Parse a formatted date string according to the format. Updates the Calendar with parsed fields. 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.
      Specified by:
        `parse` in interface `DateParser`
      Parameters:
        `source` - The text to parse.
        `pos` - On input, the position in the source to start parsing, on output, updated position.
        `calendar` - The calendar into which to set parsed fields.
      Returns:
        true, if source has been parsed (pos parsePosition is updated); otherwise false (and pos errorIndex is updated)
      Throws:
        `java.lang.IllegalArgumentException` - when Calendar has been set to be not lenient, and a parsed field is out of range.