Package org.joda.time

Class Partial

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<ReadablePartial>, ReadablePartial
    public final class Partial
extends AbstractPartial
implements ReadablePartial, java.io.Serializable
    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.

    Since:
    1.1
    See Also:
    Serialized Form

    • Constructor Detail

      • Partial

        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.

      • Partial

        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

      • Partial

        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:
        java.lang.IllegalArgumentException - if the type or value is invalid

      • Partial

        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:
        java.lang.IllegalArgumentException - if the type or value is invalid

      • Partial

        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. For year and weekyear fields with equal duration, year is defined as being larger than weekyear.

        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:
        java.lang.IllegalArgumentException - if the types or values are invalid

      • Partial

        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. For year and weekyear fields with equal duration, year is defined as being larger than weekyear.

        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:
        java.lang.IllegalArgumentException - if the types or values are invalid

      • Partial

        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.

    • Method Detail

      • size

        public int size()
        Gets the number of fields in this partial.
        Specified by:
        size in interface ReadablePartial
        Returns:
        the field count

      • getChronology

        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.

        Specified by:
        getChronology in interface ReadablePartial
        Returns:
        the chronology, never null

      • getFieldType

        public DateTimeFieldType getFieldType​(int index)
        Gets the field type at the specified index.
        Specified by:
        getFieldType in interface ReadablePartial
        Overrides:
        getFieldType in class AbstractPartial
        Parameters:
        index - the index to retrieve
        Returns:
        the field at the specified index
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is invalid

      • getFieldTypes

        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.

        Overrides:
        getFieldTypes in class AbstractPartial
        Returns:
        the array of field types (cloned), largest to smallest

      • getValue

        public int getValue​(int index)
        Gets the value of the field at the specified index.
        Specified by:
        getValue in interface ReadablePartial
        Parameters:
        index - the index
        Returns:
        the value
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is invalid

      • getValues

        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()

        Overrides:
        getValues in class AbstractPartial
        Returns:
        the current values of each field (cloned), largest to smallest

      • withChronologyRetainFields

        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:
        java.lang.IllegalArgumentException - if the values are invalid for the new chronology

      • with

        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:
        java.lang.IllegalArgumentException - if the value is null or invalid

      • without

        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

      • withField

        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:
        java.lang.IllegalArgumentException - if the value is null or invalid

      • withFieldAdded

        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:
        java.lang.IllegalArgumentException - if the value is null or invalid
        java.lang.ArithmeticException - if the new datetime exceeds the capacity

      • withFieldAddWrapped

        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 wrap.

        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:
        java.lang.IllegalArgumentException - if the value is null or invalid
        java.lang.ArithmeticException - if the new datetime exceeds the capacity

      • withPeriodAdded

        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:
        java.lang.ArithmeticException - if the new datetime exceeds the capacity

      • plus

        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:
        java.lang.ArithmeticException - if the new datetime exceeds the capacity of a long

      • minus

        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:
        java.lang.ArithmeticException - if the new datetime exceeds the capacity of a long

      • property

        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.

        See also ReadablePartial.get(DateTimeFieldType).

        Parameters:
        type - the field type to get the property for, not null
        Returns:
        the property object
        Throws:
        java.lang.IllegalArgumentException - if the field is null or unsupported

      • isMatch

        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

      • isMatch

        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:
        java.lang.IllegalArgumentException - if the partial is null
        java.lang.IllegalArgumentException - if the fields of the two partials do not match
        Since:
        1.5

      • getFormatter

        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

      • toString

        public java.lang.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().

        Specified by:
        toString in interface ReadablePartial
        Overrides:
        toString in class java.lang.Object
        Returns:
        ISO8601 formatted string

      • toStringList

        public java.lang.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

      • toString

        public java.lang.String toString​(java.lang.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
        See Also:
        DateTimeFormat

      • toString

        public java.lang.String toString​(java.lang.String pattern,
                                 java.util.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
        See Also:
        DateTimeFormat