Class DateTimeParserBucket
- java.lang.Object
-
- org.joda.time.format.DateTimeParserBucket
-
public class DateTimeParserBucket extends java.lang.Object
DateTimeParserBucket is an advanced class, intended mainly for parser implementations. It can also be used during normal parsing operations to capture more information about the parse.This class allows fields to be saved in any order, but be physically set in a consistent order. This is useful for parsing against formats that allow field values to contradict each other.
Field values are applied in an order where the "larger" fields are set first, making their value less likely to stick. A field is larger than another when it's range duration is longer. If both ranges are the same, then the larger field has the longer duration. If it cannot be determined which field is larger, then the fields are set in the order they were saved.
For example, these fields were saved in this order: dayOfWeek, monthOfYear, dayOfMonth, dayOfYear. When computeMillis is called, the fields are set in this order: monthOfYear, dayOfYear, dayOfMonth, dayOfWeek.
DateTimeParserBucket is mutable and not thread-safe.
- Since:
- 1.0
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) static class
DateTimeParserBucket.SavedField
(package private) class
DateTimeParserBucket.SavedState
-
Field Summary
Fields Modifier and Type Field Description private Chronology
iChrono
The chronology to use for parsing.private java.lang.Integer
iDefaultPivotYear
The default pivot year from the constructor.private int
iDefaultYear
Used for parsing month/day without year.private DateTimeZone
iDefaultZone
The default zone from the constructor.private java.util.Locale
iLocale
The locale to use for parsing.private long
iMillis
The initial millis.private java.lang.Integer
iOffset
The parsed offset.private java.lang.Integer
iPivotYear
Used for parsing two-digit years.private DateTimeParserBucket.SavedField[]
iSavedFields
private int
iSavedFieldsCount
private boolean
iSavedFieldsShared
private java.lang.Object
iSavedState
private DateTimeZone
iZone
The parsed zone, initialised to formatter zone.
-
Constructor Summary
Constructors Constructor Description DateTimeParserBucket(long instantLocal, Chronology chrono, java.util.Locale locale)
Deprecated.Use longer constructorDateTimeParserBucket(long instantLocal, Chronology chrono, java.util.Locale locale, java.lang.Integer pivotYear)
Deprecated.Use longer constructorDateTimeParserBucket(long instantLocal, Chronology chrono, java.util.Locale locale, java.lang.Integer pivotYear, int defaultYear)
Constructs a bucket, with the option of specifying the pivot year for two-digit year parsing.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description (package private) static int
compareReverse(DurationField a, DurationField b)
long
computeMillis()
Computes the parsed datetime by setting the saved fields.long
computeMillis(boolean resetFields)
Computes the parsed datetime by setting the saved fields.long
computeMillis(boolean resetFields, java.lang.CharSequence text)
Computes the parsed datetime by setting the saved fields.long
computeMillis(boolean resetFields, java.lang.String text)
Computes the parsed datetime by setting the saved fields.(package private) long
doParseMillis(InternalParser parser, java.lang.CharSequence text)
Chronology
getChronology()
Gets the chronology of the bucket, which will be a local (UTC) chronology.java.util.Locale
getLocale()
Returns the locale to be used during parsing.int
getOffset()
Deprecated.use Integer versionjava.lang.Integer
getOffsetInteger()
Returns the time zone offset in milliseconds used by computeMillis.java.lang.Integer
getPivotYear()
Returns the default year used when information is incomplete.DateTimeZone
getZone()
Returns the time zone used by computeMillis.private DateTimeParserBucket.SavedField
obtainSaveField()
long
parseMillis(DateTimeParser parser, java.lang.CharSequence text)
Parses a datetime from the given text, returning the number of milliseconds since the epoch, 1970-01-01T00:00:00Z.void
reset()
Resets the state back to that when the object was constructed.boolean
restoreState(java.lang.Object savedState)
Restores the state of this bucket from a previously saved state.void
saveField(DateTimeField field, int value)
Saves a datetime field value.void
saveField(DateTimeFieldType fieldType, int value)
Saves a datetime field value.void
saveField(DateTimeFieldType fieldType, java.lang.String text, java.util.Locale locale)
Saves a datetime field text value.java.lang.Object
saveState()
Saves the state of this bucket, returning it in an opaque object.void
setOffset(int offset)
Deprecated.use Integer versionvoid
setOffset(java.lang.Integer offset)
Set a time zone offset to be used when computeMillis is called.void
setPivotYear(java.lang.Integer pivotYear)
Deprecated.this method should never have been publicvoid
setZone(DateTimeZone zone)
Set a time zone to be used when computeMillis is called.private static void
sort(DateTimeParserBucket.SavedField[] array, int high)
Sorts elements [0,high).
-
-
-
Field Detail
-
iChrono
private final Chronology iChrono
The chronology to use for parsing.
-
iMillis
private final long iMillis
The initial millis.
-
iLocale
private final java.util.Locale iLocale
The locale to use for parsing.
-
iDefaultYear
private final int iDefaultYear
Used for parsing month/day without year.
-
iDefaultZone
private final DateTimeZone iDefaultZone
The default zone from the constructor.
-
iDefaultPivotYear
private final java.lang.Integer iDefaultPivotYear
The default pivot year from the constructor.
-
iZone
private DateTimeZone iZone
The parsed zone, initialised to formatter zone.
-
iOffset
private java.lang.Integer iOffset
The parsed offset.
-
iPivotYear
private java.lang.Integer iPivotYear
Used for parsing two-digit years.
-
iSavedFields
private DateTimeParserBucket.SavedField[] iSavedFields
-
iSavedFieldsCount
private int iSavedFieldsCount
-
iSavedFieldsShared
private boolean iSavedFieldsShared
-
iSavedState
private java.lang.Object iSavedState
-
-
Constructor Detail
-
DateTimeParserBucket
@Deprecated public DateTimeParserBucket(long instantLocal, Chronology chrono, java.util.Locale locale)
Deprecated.Use longer constructorConstructs a bucket.- Parameters:
instantLocal
- the initial millis from 1970-01-01T00:00:00, local timechrono
- the chronology to uselocale
- the locale to use
-
DateTimeParserBucket
@Deprecated public DateTimeParserBucket(long instantLocal, Chronology chrono, java.util.Locale locale, java.lang.Integer pivotYear)
Deprecated.Use longer constructorConstructs a bucket, with the option of specifying the pivot year for two-digit year parsing.- Parameters:
instantLocal
- the initial millis from 1970-01-01T00:00:00, local timechrono
- the chronology to uselocale
- the locale to usepivotYear
- the pivot year to use when parsing two-digit years- Since:
- 1.1
-
DateTimeParserBucket
public DateTimeParserBucket(long instantLocal, Chronology chrono, java.util.Locale locale, java.lang.Integer pivotYear, int defaultYear)
Constructs a bucket, with the option of specifying the pivot year for two-digit year parsing.- Parameters:
instantLocal
- the initial millis from 1970-01-01T00:00:00, local timechrono
- the chronology to uselocale
- the locale to usepivotYear
- the pivot year to use when parsing two-digit yearsdefaultYear
- the default year to use when parsing month-day- Since:
- 2.0
-
-
Method Detail
-
reset
public void reset()
Resets the state back to that when the object was constructed.This resets the state of the bucket, allowing a single bucket to be re-used for many parses. The bucket must not be shared between threads.
- Since:
- 2.4
-
parseMillis
public long parseMillis(DateTimeParser parser, java.lang.CharSequence text)
Parses a datetime from the given text, returning the number of milliseconds since the epoch, 1970-01-01T00:00:00Z.This parses the text using the parser into this bucket. The bucket is reset before parsing begins, allowing the bucket to be re-used. The bucket must not be shared between threads.
- Parameters:
parser
- the parser to use, seeDateTimeFormatter.getParser()
, not nulltext
- text to parse, not null- Returns:
- parsed value expressed in milliseconds since the epoch
- Throws:
java.lang.UnsupportedOperationException
- if parsing is not supportedjava.lang.IllegalArgumentException
- if the text to parse is invalid- Since:
- 2.4
-
doParseMillis
long doParseMillis(InternalParser parser, java.lang.CharSequence text)
-
getChronology
public Chronology getChronology()
Gets the chronology of the bucket, which will be a local (UTC) chronology.
-
getLocale
public java.util.Locale getLocale()
Returns the locale to be used during parsing.- Returns:
- the locale to use
-
getZone
public DateTimeZone getZone()
Returns the time zone used by computeMillis.
-
setZone
public void setZone(DateTimeZone zone)
Set a time zone to be used when computeMillis is called.
-
getOffset
@Deprecated public int getOffset()
Deprecated.use Integer versionReturns the time zone offset in milliseconds used by computeMillis.
-
getOffsetInteger
public java.lang.Integer getOffsetInteger()
Returns the time zone offset in milliseconds used by computeMillis.
-
setOffset
@Deprecated public void setOffset(int offset)
Deprecated.use Integer versionSet a time zone offset to be used when computeMillis is called.
-
setOffset
public void setOffset(java.lang.Integer offset)
Set a time zone offset to be used when computeMillis is called.
-
getPivotYear
public java.lang.Integer getPivotYear()
Returns the default year used when information is incomplete.This is used for two-digit years and when the largest parsed field is months or days.
A null value for two-digit years means to use the value from DateTimeFormatterBuilder. A null value for month/day only parsing will cause the default of 2000 to be used.
- Returns:
- Integer value of the pivot year, null if not set
- Since:
- 1.1
-
setPivotYear
@Deprecated public void setPivotYear(java.lang.Integer pivotYear)
Deprecated.this method should never have been publicSets the pivot year to use when parsing two digit years.If the value is set to null, this will indicate that default behaviour should be used.
- Parameters:
pivotYear
- the pivot year to use- Since:
- 1.1
-
saveField
public void saveField(DateTimeField field, int value)
Saves a datetime field value.- Parameters:
field
- the field, whose chronology must match that of this bucketvalue
- the value
-
saveField
public void saveField(DateTimeFieldType fieldType, int value)
Saves a datetime field value.- Parameters:
fieldType
- the field typevalue
- the value
-
saveField
public void saveField(DateTimeFieldType fieldType, java.lang.String text, java.util.Locale locale)
Saves a datetime field text value.- Parameters:
fieldType
- the field typetext
- the text valuelocale
- the locale to use
-
obtainSaveField
private DateTimeParserBucket.SavedField obtainSaveField()
-
saveState
public java.lang.Object saveState()
Saves the state of this bucket, returning it in an opaque object. Call restoreState to undo any changes that were made since the state was saved. Calls to saveState may be nested.- Returns:
- opaque saved state, which may be passed to restoreState
-
restoreState
public boolean restoreState(java.lang.Object savedState)
Restores the state of this bucket from a previously saved state. The state object passed into this method is not consumed, and it can be used later to restore to that state again.- Parameters:
savedState
- opaque saved state, returned from saveState- Returns:
- true state object is valid and state restored
-
computeMillis
public long computeMillis()
Computes the parsed datetime by setting the saved fields. This method is idempotent, but it is not thread-safe.- Returns:
- milliseconds since 1970-01-01T00:00:00Z
- Throws:
java.lang.IllegalArgumentException
- if any field is out of range
-
computeMillis
public long computeMillis(boolean resetFields)
Computes the parsed datetime by setting the saved fields. This method is idempotent, but it is not thread-safe.- Parameters:
resetFields
- false by default, but when true, unsaved field values are cleared- Returns:
- milliseconds since 1970-01-01T00:00:00Z
- Throws:
java.lang.IllegalArgumentException
- if any field is out of range
-
computeMillis
public long computeMillis(boolean resetFields, java.lang.String text)
Computes the parsed datetime by setting the saved fields. This method is idempotent, but it is not thread-safe.- Parameters:
resetFields
- false by default, but when true, unsaved field values are clearedtext
- optional text being parsed, to be included in any error message- Returns:
- milliseconds since 1970-01-01T00:00:00Z
- Throws:
java.lang.IllegalArgumentException
- if any field is out of range- Since:
- 1.3
-
computeMillis
public long computeMillis(boolean resetFields, java.lang.CharSequence text)
Computes the parsed datetime by setting the saved fields. This method is idempotent, but it is not thread-safe.- Parameters:
resetFields
- false by default, but when true, unsaved field values are clearedtext
- optional text being parsed, to be included in any error message- Returns:
- milliseconds since 1970-01-01T00:00:00Z
- Throws:
java.lang.IllegalArgumentException
- if any field is out of range- Since:
- 2.4
-
sort
private static void sort(DateTimeParserBucket.SavedField[] array, int high)
Sorts elements [0,high). Calling java.util.Arrays isn't always the right choice since it always creates an internal copy of the array, even if it doesn't need to. If the array slice is small enough, an insertion sort is chosen instead, but it doesn't need a copy!This method has a modified version of that insertion sort, except it doesn't create an unnecessary array copy. If high is over 10, then java.util.Arrays is called, which will perform a merge sort, which is faster than insertion sort on large lists.
The end result is much greater performance when computeMillis is called. Since the amount of saved fields is small, the insertion sort is a better choice. Additional performance is gained since there is no extra array allocation and copying. Also, the insertion sort here does not perform any casting operations. The version in java.util.Arrays performs casts within the insertion sort loop.
-
compareReverse
static int compareReverse(DurationField a, DurationField b)
-
-