Class DateTimeFields

  • All Implemented Interfaces:
    Serializable, Iterable<DateTimeFieldRule<?>>, Calendrical, CalendricalMatcher

    public final class DateTimeFields
    extends Object
    implements Calendrical, CalendricalMatcher, Iterable<DateTimeFieldRule<?>>, Serializable
    A set of date-time fields.

    Instances of this class store a map of field-value pairs. Together these specify constraints on the dates and times that match. For example, if an instance stores 'DayOfMonth=13' and 'DayOfWeek=Friday' then it represents and matches only dates of Friday the Thirteenth.

    All the values will be within the valid range for the field. However, there is no cross validation between fields. Thus, it is possible for the date-time represented to never exist. For example, if an instance stores 'DayOfMonth=31' and 'MonthOfYear=February' then there will never be a matching date.

    Author:
    Michael Nascimento Santos, Stephen Colebourne
    See Also:
    Serialized Form
    • Field Detail

      • EMPTY

        public static final DateTimeFields EMPTY
        A singleton empty DateTimeFields, placing no restrictions on the date-time.
    • Method Detail

      • of

        public static DateTimeFields of​(DateTimeFieldRule<?> fieldRule,
                                        int value)
        Obtains an instance of DateTimeFields from a field-value pair.

        This factory allows the creation of a fields object with a single field-value pair. The value must be within the valid range for the field.

        Parameters:
        fieldRule - the rule, not null
        value - the field value, may be invalid
        Returns:
        the fields instance, never null
        Throws:
        NullPointerException - if the field rule is null
        IllegalCalendarFieldValueException - if the value is invalid
      • of

        public static DateTimeFields of​(DateTimeFieldRule<?> fieldRule1,
                                        int value1,
                                        DateTimeFieldRule<?> fieldRule2,
                                        int value2)
        Obtains an instance of DateTimeFields from two field-value pairs.

        This factory allows the creation of a fields object with two field-value pairs. Each value must be within the valid range for that field.

        The two fields are not cross-validated. Thus, you can specify MonthOfYear of June and DayOfMonth of 31, which is a date that can never occur.

        Parameters:
        fieldRule1 - the first rule, not null
        value1 - the first field value
        fieldRule2 - the second rule, not null
        value2 - the second field value
        Returns:
        the fields instance, never null
        Throws:
        NullPointerException - if either field rule is null
        IllegalCalendarFieldValueException - if either value is invalid
      • of

        public static DateTimeFields of​(Map<DateTimeFieldRule<?>,​Integer> fieldValueMap)
        Obtains an instance of DateTimeFields from a map of field-value pairs.

        This factory allows the creation of a fields object from a map of field-value pairs. Each value must be within the valid range for that field.

        The fields are not cross-validated. Thus, you can specify MonthOfYear of June and DayOfMonth of 31, which is a date that can never occur.

        Parameters:
        fieldValueMap - a map of fields that will be used to create a field set, not updated by this factory, not null, contains no nulls
        Returns:
        the fields instance, never null
        Throws:
        NullPointerException - if the map contains null keys or values
        IllegalCalendarFieldValueException - if any value is invalid
      • size

        public int size()
        Returns the size of the map of fields to values.

        This method returns the number of field-value pairs stored.

        Returns:
        number of field-value pairs, zero or greater
      • contains

        public boolean contains​(DateTimeFieldRule<?> fieldRule)
        Checks if this object contains a mapping for the specified field.

        This method returns true if a value can be obtained for the specified field.

        Parameters:
        fieldRule - the field to query, null returns false
        Returns:
        true if the field is supported, false otherwise
      • get

        public <T> T get​(CalendricalRule<T> rule)
        Gets the value of the specified calendrical rule.

        This method queries the value of the specified calendrical rule. If the value cannot be returned for the rule from this instance then an attempt is made to derive the value. If that fails, null will be returned.

        Specified by:
        get in interface Calendrical
        Parameters:
        rule - the rule to use, not null
        Returns:
        the value for the rule, null if the value cannot be returned
      • getInt

        public int getInt​(DateTimeFieldRule<?> rule)
        Gets the value for the specified field throwing an exception if the field is not in the field-value map.

        The value will be within the valid range for the field.

        No attempt is made to derive values. The result is simply based on the contents of the stored field-value map. If you want to derive a value then use get(javax.time.calendar.CalendricalRule<T>) or a CalendricalMerger.

        Parameters:
        rule - the rule to query from the map, not null
        Returns:
        the value mapped to the specified field
        Throws:
        UnsupportedRuleException - if the field is not in the map
      • getQuiet

        public Integer getQuiet​(DateTimeFieldRule<?> fieldRule)
        Gets the value for the specified field quietly returning null if the field is not in the field-value map.

        The value will be within the valid range for the field.

        Parameters:
        fieldRule - the rule to query from the map, null returns null
        Returns:
        the value mapped to the specified field, null if not present
      • with

        public DateTimeFields with​(DateTimeFieldRule<?> fieldRule,
                                   int value)
        Returns a copy of this DateTimeFields with the specified field value.

        If this instance already has a value for the field then the value is replaced. Otherwise the value is added to the map.

        This instance is immutable and unaffected by this method call.

        Parameters:
        fieldRule - the field to set in the returned object, not null
        value - the value to set in the returned set of fields
        Returns:
        a new, updated DateTimeFields, never null
        Throws:
        NullPointerException - if DateTimeFieldRule is null
        IllegalCalendarFieldValueException - if the value is invalid
      • with

        public DateTimeFields with​(DateTimeFields fields)
        Returns a copy of this DateTimeFields with the specified fields added.

        If this instance already has a value for the field then the value is replaced. Otherwise the value is added.

        This instance is immutable and unaffected by this method call.

        Parameters:
        fields - the fields to add to the returned object, not null
        Returns:
        a new, updated DateTimeFields, never null
      • withFieldRemoved

        public DateTimeFields withFieldRemoved​(DateTimeFieldRule<?> fieldRule)
        Returns a copy of this object with the specified field removed.

        If this instance does not contain the field then the returned instance is the same as this one.

        This instance is immutable and unaffected by this method call.

        Parameters:
        fieldRule - the field to remove from the returned object, not null
        Returns:
        a new, updated DateTimeFields, never null
      • matchesCalendrical

        public boolean matchesCalendrical​(Calendrical calendrical)
        Checks if the fields in this object match those in the specified calendrical.

        This implementation checks that all calendrical fields in this object match.

        Specified by:
        matchesCalendrical in interface CalendricalMatcher
        Parameters:
        calendrical - the calendrical to match, not null
        Returns:
        true if the calendrical fields match, false otherwise
      • toFieldValueMap

        public SortedMap<DateTimeFieldRule<?>,​Integer> toFieldValueMap()
        Converts this object to a map of fields to values.

        The returned map will never be null, however it may be empty. It is independent of this object - changes will not be reflected back.

        Returns:
        an independent, modifiable copy of the field-value map, never null
      • equals

        public boolean equals​(Object obj)
        Is this object equal to the specified object.

        This compares the map of field-value pairs.

        Overrides:
        equals in class Object
        Parameters:
        obj - the other fields to compare to, null returns false
        Returns:
        true if this instance is equal to the specified field set
      • hashCode

        public int hashCode()
        A hash code for these fields.
        Overrides:
        hashCode in class Object
        Returns:
        a suitable hash code
      • toString

        public String toString()
        Outputs the fields as a String.

        The output will consist of the field-value map in standard map format.

        Overrides:
        toString in class Object
        Returns:
        the formatted date-time string, never null