public final class

Partial

extends AbstractPartial
implements Serializable ReadablePartial

java.lang.Object
↳	org.joda.time.base.AbstractPartial
	↳	org.joda.time.Partial

Class Overview

Partial is an immutable partial datetime supporting any set of datetime fields.

A Partial instance can be used to hold any combination of fields. The instance does not contain a time zone, so any datetime is local.

A Partial can be matched against an instant using isMatch(ReadableInstant). This method compares each field on this partial with those of the instant and determines if the partial matches the instant. Given this definition, an empty Partial instance represents any datetime and always matches.

Calculations on Partial are performed using a Chronology. This chronology is set to be in the UTC time zone for all calculations.

Each individual field can be queried in two ways:

get(DateTimeFieldType.monthOfYear())
property(DateTimeFieldType.monthOfYear()).get()

The second technique also provides access to other useful methods on the field:

numeric value - monthOfYear().get()
text value - monthOfYear().getAsText()
short text value - monthOfYear().getAsShortText()
maximum/minimum values - monthOfYear().getMaximumValue()
add/subtract - monthOfYear().addToCopy()
set - monthOfYear().setCopy()

Partial is thread-safe and immutable, provided that the Chronology is as well. All standard Chronology classes supplied are thread-safe and immutable.

Summary

Nested Classes
class	Partial.Property	The property class for `Partial`.

Public Constructors
	Partial() Constructs a Partial with no fields or values, which can be considered to represent any date.
	Partial(Chronology chrono) Constructs a Partial with no fields or values, which can be considered to represent any date.
	Partial(DateTimeFieldType type, int value) Constructs a Partial with the specified field and value.
	Partial(DateTimeFieldType type, int value, Chronology chronology) Constructs a Partial with the specified field and value.
	Partial(DateTimeFieldType[] types, int[] values) Constructs a Partial with the specified fields and values.
	Partial(DateTimeFieldType[] types, int[] values, Chronology chronology) Constructs a Partial with the specified fields and values.
	Partial(ReadablePartial partial) Constructs a Partial by copying all the fields and types from another partial.

Public Methods
Chronology	getChronology() Gets the chronology of the partial which is never null.
DateTimeFieldType	getFieldType(int index) Gets the field type at the specified index.
DateTimeFieldType[]	getFieldTypes() Gets an array of the field type of each of the fields that this partial supports.
DateTimeFormatter	getFormatter() Gets a formatter suitable for the fields in this partial.
int	getValue(int index) Gets the value of the field at the specifed index.
int[]	getValues() Gets an array of the value of each of the fields that this partial supports.
boolean	isMatch(ReadableInstant instant) Does this partial match the specified instant.
boolean	isMatch(ReadablePartial partial) Does this partial match the specified partial.
Partial	minus(ReadablePeriod period) Gets a copy of this instance with the specified period take away.
Partial	plus(ReadablePeriod period) Gets a copy of this instance with the specified period added.
Partial.Property	property(DateTimeFieldType type) Gets the property object for the specified type, which contains many useful methods for getting and manipulating the partial.
int	size() Gets the number of fields in this partial.
String	toString() Output the date in an appropriate ISO8601 format.
String	toString(String pattern, Locale locale) Output the date using the specified format pattern.
String	toString(String pattern) Output the date using the specified format pattern.
String	toStringList() Gets a string version of the partial that lists all the fields.
Partial	with(DateTimeFieldType fieldType, int value) Gets a copy of this date with the specified field set to a new value.
Partial	withChronologyRetainFields(Chronology newChronology) Creates a new Partial instance with the specified chronology.
Partial	withField(DateTimeFieldType fieldType, int value) Gets a copy of this Partial with the specified field set to a new value.
Partial	withFieldAddWrapped(DurationFieldType fieldType, int amount) Gets a copy of this Partial with the value of the specified field increased.
Partial	withFieldAdded(DurationFieldType fieldType, int amount) Gets a copy of this Partial with the value of the specified field increased.
Partial	withPeriodAdded(ReadablePeriod period, int scalar) Gets a copy of this Partial with the specified period added.
Partial	without(DateTimeFieldType fieldType) Gets a copy of this date with the specified field removed.

Protected Methods
DateTimeField	getField(int index, Chronology chrono) Gets the field for a specific index in the chronology specified.

[Expand]

Inherited Methods

From class org.joda.time.base.AbstractPartial

int	compareTo(Object partial) Compares this partial with another returning an integer indicating the order.
boolean	equals(Object partial) Compares this ReadablePartial with another returning true if the chronology, field types and values are equal.
int	get(DateTimeFieldType type) Get the value of one of the fields of a datetime.
DateTimeField	getField(int index) Gets the field at the specifed index.
abstract DateTimeField	getField(int index, Chronology chrono) Gets the field for a specific index in the chronology specified.
DateTimeFieldType	getFieldType(int index) Gets the field type at the specifed index.
DateTimeFieldType[]	getFieldTypes() Gets an array of the field types that this partial supports.
DateTimeField[]	getFields() Gets an array of the fields that this partial supports.
int[]	getValues() Gets an array of the value of each of the fields that this partial supports.
int	hashCode() Gets a hash code for the ReadablePartial that is compatible with the equals method.
int	indexOf(DurationFieldType type) Gets the index of the first fields to have the specified duration, or -1 if the field is unsupported.
int	indexOf(DateTimeFieldType type) Gets the index of the specified field, or -1 if the field is unsupported.
int	indexOfSupported(DurationFieldType type) Gets the index of the first fields to have the specified duration, throwing an exception if the field is unsupported.
int	indexOfSupported(DateTimeFieldType type) Gets the index of the specified field, throwing an exception if the field is unsupported.
boolean	isAfter(ReadablePartial partial) Is this partial later than the specified partial.
boolean	isBefore(ReadablePartial partial) Is this partial earlier than the specified partial.
boolean	isEqual(ReadablePartial partial) Is this partial the same as the specified partial.
boolean	isSupported(DateTimeFieldType type) Checks whether the field specified is supported by this partial.
DateTime	toDateTime(ReadableInstant baseInstant) Resolves this partial against another complete instant to create a new full instant.
String	toString(DateTimeFormatter formatter) Uses the specified formatter to convert this partial to a String.

From class java.lang.Object

From interface java.lang.Comparable

From interface org.joda.time.ReadablePartial

abstract boolean	equals(Object partial) Compares this partial with the specified object for equality based on the supported fields, chronology and values.
abstract int	get(DateTimeFieldType field) Gets the value of one of the fields.
abstract Chronology	getChronology() Gets the chronology of the partial which is never null.
abstract DateTimeField	getField(int index) Gets the field at the specified index.
abstract DateTimeFieldType	getFieldType(int index) Gets the field type at the specified index.
abstract int	getValue(int index) Gets the value at the specified index.
abstract int	hashCode() Gets a hash code for the partial that is compatible with the equals method.
abstract boolean	isSupported(DateTimeFieldType field) Checks whether the field type specified is supported by this partial.
abstract int	size() Gets the number of fields that this partial supports.
abstract DateTime	toDateTime(ReadableInstant baseInstant) Converts this partial to a full datetime by resolving it against another datetime.
abstract String	toString() Get the value as a String in a recognisable ISO8601 format, only displaying supported fields.

Public Constructors

public Partial ()

Constructs a Partial with no fields or values, which can be considered to represent any date.

This is most useful when constructing partials, for example:

 Partial p = new Partial()
     .with(DateTimeFieldType.dayOfWeek(), 5)
     .with(DateTimeFieldType.hourOfDay(), 12)
     .with(DateTimeFieldType.minuteOfHour(), 20);

Note that, although this is a clean way to write code, it is fairly inefficient internally.

The constructor uses the default ISO chronology.

public Partial (Chronology chrono)

Constructs a Partial with no fields or values, which can be considered to represent any date.

This is most useful when constructing partials, for example:

 Partial p = new Partial(chrono)
     .with(DateTimeFieldType.dayOfWeek(), 5)
     .with(DateTimeFieldType.hourOfDay(), 12)
     .with(DateTimeFieldType.minuteOfHour(), 20);

Note that, although this is a clean way to write code, it is fairly inefficient internally.

Parameters

chrono	the chronology, null means ISO

public Partial (DateTimeFieldType type, int value)

Constructs a Partial with the specified field and value.

The constructor uses the default ISO chronology.

Parameters

type	the single type to create the partial from, not null
value	the value to store

Throws

IllegalArgumentException	if the type or value is invalid

public Partial (DateTimeFieldType type, int value, Chronology chronology)

Constructs a Partial with the specified field and value.

The constructor uses the specified chronology.

Parameters

type	the single type to create the partial from, not null
value	the value to store
chronology	the chronology, null means ISO

Throws

IllegalArgumentException	if the type or value is invalid

public Partial (DateTimeFieldType[] types, int[] values)

Constructs a Partial with the specified fields and values. The fields must be specified in the order largest to smallest.

The constructor uses the specified chronology.

Parameters

types	the types to create the partial from, not null
values	the values to store, not null

Throws

IllegalArgumentException	if the types or values are invalid

public Partial (DateTimeFieldType[] types, int[] values, Chronology chronology)

Constructs a Partial with the specified fields and values. The fields must be specified in the order largest to smallest.

The constructor uses the specified chronology.

Parameters

types	the types to create the partial from, not null
values	the values to store, not null
chronology	the chronology, null means ISO

Throws

IllegalArgumentException	if the types or values are invalid

public Partial (ReadablePartial partial)

Constructs a Partial by copying all the fields and types from another partial.

This is most useful when copying from a YearMonthDay or TimeOfDay.

Public Methods

public Chronology getChronology ()

Gets the chronology of the partial which is never null.

The Chronology is the calculation engine behind the partial and provides conversion and validation of the fields in a particular calendar system.

Returns

the chronology, never null

public DateTimeFieldType getFieldType (int index)

Gets the field type at the specified index.

Parameters

index	the index to retrieve

Returns

the field at the specified index

Throws

IndexOutOfBoundsException	if the index is invalid

public DateTimeFieldType[] getFieldTypes ()

Gets an array of the field type of each of the fields that this partial supports.

The fields are returned largest to smallest.

Returns

the array of field types (cloned), largest to smallest

public DateTimeFormatter getFormatter ()

Gets a formatter suitable for the fields in this partial.

If there is no appropriate ISO format, null is returned. This method may return a formatter that does not display all the fields of the partial. This might occur when you have overlapping fields, such as dayOfWeek and dayOfMonth.

Returns

a formatter suitable for the fields in this partial, null if none is suitable

public int getValue (int index)

Gets the value of the field at the specifed index.

Parameters

index	the index

Returns

the value

Throws

IndexOutOfBoundsException	if the index is invalid

public int[] getValues ()

Gets an array of the value of each of the fields that this partial supports.

The fields are returned largest to smallest. Each value corresponds to the same array index as getFieldTypes()

Returns

the current values of each field (cloned), largest to smallest

public boolean isMatch (ReadableInstant instant)

Does this partial match the specified instant.

A match occurs when all the fields of this partial are the same as the corresponding fields on the specified instant.

Parameters

instant	an instant to check against, null means now in default zone

Returns

true if this partial matches the specified instant

public boolean isMatch (ReadablePartial partial)

Does this partial match the specified partial.

A match occurs when all the fields of this partial are the same as the corresponding fields on the specified partial.

Parameters

partial	a partial to check against, must not be null

Returns

true if this partial matches the specified partial

Throws

IllegalArgumentException	if the partial is null
IllegalArgumentException	if the fields of the two partials do not match

public Partial minus (ReadablePeriod period)

Gets a copy of this instance with the specified period take away.

If the amount is zero or null, then this is returned.

Parameters

period	the period to reduce this instant by

Returns

a copy of this instance with the period taken away

Throws

ArithmeticException	if the new datetime exceeds the capacity of a long

public Partial plus (ReadablePeriod period)

Gets a copy of this instance with the specified period added.

If the amount is zero or null, then this is returned.

Parameters

period	the duration to add to this one, null means zero

Returns

a copy of this instance with the period added

Throws

ArithmeticException	if the new datetime exceeds the capacity of a long

public Partial.Property property (DateTimeFieldType type)

Gets the property object for the specified type, which contains many useful methods for getting and manipulating the partial.

Parameters

type	the field type to get the property for, not null

Returns

the property object

Throws

IllegalArgumentException	if the field is null or unsupported

public int size ()

Gets the number of fields in this partial.

Returns

the field count

public String toString ()

Output the date in an appropriate ISO8601 format.

This method will output the partial in one of two ways. If getFormatter()

If there is no appropriate ISO format a dump of the fields is output via toStringList().

Returns

ISO8601 formatted string

public String toString (String pattern, Locale locale)

Output the date using the specified format pattern. Unsupported fields will appear as special unicode characters.

Parameters

pattern	the pattern specification, null means use `toString`
locale	Locale to use, null means default

public String toString (String pattern)

Output the date using the specified format pattern. Unsupported fields will appear as special unicode characters.

Parameters

pattern	the pattern specification, null means use `toString`

public String toStringList ()

Gets a string version of the partial that lists all the fields.

This method exists to provide a better debugging toString than the standard toString. This method lists all the fields and their values in a style similar to the collections framework.

Returns

a toString format that lists all the fields

public Partial with (DateTimeFieldType fieldType, int value)

Gets a copy of this date with the specified field set to a new value.

If this partial did not previously support the field, the new one will. Contrast this behaviour with withField(DateTimeFieldType, int).

For example, if the field type is dayOfMonth then the day would be changed/added in the returned instance.

Parameters

fieldType	the field type to set, not null
value	the value to set

Returns

a copy of this instance with the field set

Throws

IllegalArgumentException	if the value is null or invalid

public Partial withChronologyRetainFields (Chronology newChronology)

Creates a new Partial instance with the specified chronology. This instance is immutable and unaffected by this method call.

This method retains the values of the fields, thus the result will typically refer to a different instant.

The time zone of the specified chronology is ignored, as Partial operates without a time zone.

Parameters

newChronology	the new chronology, null means ISO

Returns

a copy of this datetime with a different chronology

Throws

IllegalArgumentException	if the values are invalid for the new chronology

public Partial withField (DateTimeFieldType fieldType, int value)

Gets a copy of this Partial with the specified field set to a new value.

If this partial does not support the field, an exception is thrown. Contrast this behaviour with with(DateTimeFieldType, int).

For example, if the field type is dayOfMonth then the day would be changed in the returned instance if supported.

Parameters

fieldType	the field type to set, not null
value	the value to set

Returns

a copy of this instance with the field set

Throws

IllegalArgumentException	if the value is null or invalid

public Partial withFieldAddWrapped (DurationFieldType fieldType, int amount)

Gets a copy of this Partial with the value of the specified field increased. If this partial does not support the field, an exception is thrown.

If the addition is zero, then this is returned. The addition will overflow into larger fields (eg. minute to hour). If the maximum is reached, the addition will wra.

Parameters

fieldType	the field type to add to, not null
amount	the amount to add

Returns

a copy of this instance with the field updated

Throws

IllegalArgumentException	if the value is null or invalid
ArithmeticException	if the new datetime exceeds the capacity

public Partial withFieldAdded (DurationFieldType fieldType, int amount)

Gets a copy of this Partial with the value of the specified field increased. If this partial does not support the field, an exception is thrown.

If the addition is zero, then this is returned. The addition will overflow into larger fields (eg. minute to hour). However, it will not wrap around if the top maximum is reached.

Parameters

fieldType	the field type to add to, not null
amount	the amount to add

Returns

a copy of this instance with the field updated

Throws

IllegalArgumentException	if the value is null or invalid
ArithmeticException	if the new datetime exceeds the capacity

public Partial withPeriodAdded (ReadablePeriod period, int scalar)

Gets a copy of this Partial with the specified period added.

If the addition is zero, then this is returned. Fields in the period that aren't present in the partial are ignored.

This method is typically used to add multiple copies of complex period instances. Adding one field is best achieved using the method withFieldAdded(DurationFieldType, int).

Parameters

period	the period to add to this one, null means zero
scalar	the amount of times to add, such as -1 to subtract once

Returns

a copy of this instance with the period added

Throws

ArithmeticException	if the new datetime exceeds the capacity

public Partial without (DateTimeFieldType fieldType)

Gets a copy of this date with the specified field removed.

If this partial did not previously support the field, no error occurs.

Parameters

fieldType	the field type to remove, may be null

Returns

a copy of this instance with the field removed

Protected Methods

protected DateTimeField getField (int index, Chronology chrono)

Gets the field for a specific index in the chronology specified.

Parameters

index	the index to retrieve
chrono	the chronology to use

Returns

the field

Throws

IndexOutOfBoundsException	if the index is invalid

Interfaces

Classes

Exceptions

Partial

Class Overview

Summary

Public Constructors

public Partial ()

public Partial (Chronology chrono)

Parameters

public Partial (DateTimeFieldType type, int value)

Parameters

Throws

public Partial (DateTimeFieldType type, int value, Chronology chronology)

Parameters

Throws

public Partial (DateTimeFieldType[] types, int[] values)

Parameters

Throws

public Partial (DateTimeFieldType[] types, int[] values, Chronology chronology)

Parameters

Throws

public Partial (ReadablePartial partial)

Public Methods

public Chronology getChronology ()

Returns

public DateTimeFieldType getFieldType (int index)

Parameters

Returns

Throws

public DateTimeFieldType[] getFieldTypes ()

Returns

public DateTimeFormatter getFormatter ()

Returns

public int getValue (int index)

Parameters

Returns

Throws

public int[] getValues ()

Returns

public boolean isMatch (ReadableInstant instant)

Parameters

Returns

public boolean isMatch (ReadablePartial partial)

Parameters

Returns

Throws

public Partial minus (ReadablePeriod period)

Parameters

Returns

Throws

public Partial plus (ReadablePeriod period)

Parameters

Returns

Throws

public Partial.Property property (DateTimeFieldType type)

Parameters

Returns

Throws

public int size ()

Returns

public String toString ()

Returns

public String toString (String pattern, Locale locale)

Parameters

See Also

public String toString (String pattern)

Parameters

See Also

public String toStringList ()

Returns

public Partial with (DateTimeFieldType fieldType, int value)

Parameters

Returns

Throws

public Partial withChronologyRetainFields (Chronology newChronology)

Parameters

Returns

Throws

public Partial withField (DateTimeFieldType fieldType, int value)