Package org.zkoss.zul

Class DateRange

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<DateRange>
    public final class DateRange
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable<DateRange>
    An immutable value object representing a Date-based range, used as the value object of Daterangebox.

    Either end may be null to denote an open-ended range:

    • begin == null && end == null — empty range.
    • begin == null && end != null — open start ("before end").
    • begin != null && end == null — open end ("after begin").
    • both non-null — closed range.

    The class intentionally does not auto-swap when begin > end; the raw input is preserved so the UI layer can decide how to surface the inversion.

    Instances are Serializable and Comparable: ordering compares begin first then end, treating null as the smallest value.

    Since:
    10.4.0
    Author:
    peaker
    See Also:
    Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      DateRange​(java.util.Date begin, java.util.Date end)
      Constructs a new range.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(DateRange o)  
      boolean contains​(java.util.Date value)
      Tests whether the supplied date falls within this range.
      boolean equals​(java.lang.Object o)  
      java.util.Date getBegin()
      Returns the begin date, or null if the range has an open start.
      java.util.OptionalLong getDays()
      Returns the inclusive 24-hour-block count between begin and end.
      java.util.Date getEnd()
      Returns the end date, or null if the range has an open end.
      int hashCode()  
      boolean isClosed()  
      boolean isEmpty()  
      boolean isOpenEnd()  
      boolean isOpenStart()  
      static DateRange of​(java.util.Date begin, java.util.Date end)
      Static factory equivalent to DateRange(Date, Date).
      boolean overlaps​(DateRange other)
      Tests whether this range overlaps the supplied range.
      java.lang.String toString()
      Returns a debug representation in the form "yyyy-MM-dd ~ yyyy-MM-dd".

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • DateRange

        public DateRange​(java.util.Date begin,
                 java.util.Date end)
        Constructs a new range. Either begin or end may be null to denote an open-ended range.
        Parameters:
        begin - the begin date (inclusive), or null for open start
        end - the end date (inclusive), or null for open end

    • Method Detail

      • of

        public static DateRange of​(java.util.Date begin,
                           java.util.Date end)
        Static factory equivalent to DateRange(Date, Date).
        Parameters:
        begin - the begin date (inclusive), or null
        end - the end date (inclusive), or null
        Returns:
        a new DateRange

      • getBegin

        public java.util.Date getBegin()
        Returns the begin date, or null if the range has an open start.
        Returns:
        the begin date (defensive copy), or null

      • getEnd

        public java.util.Date getEnd()
        Returns the end date, or null if the range has an open end.
        Returns:
        the end date (defensive copy), or null

      • isEmpty

        public boolean isEmpty()
        Returns:
        true if both ends are null.

      • isOpenStart

        public boolean isOpenStart()
        Returns:
        true if begin is null but end is not.

      • isOpenEnd

        public boolean isOpenEnd()
        Returns:
        true if end is null but begin is not.

      • isClosed

        public boolean isClosed()
        Returns:
        true if both ends are non-null.

      • contains

        public boolean contains​(java.util.Date value)
        Tests whether the supplied date falls within this range. The comparison is null-safe and inclusive on both ends. null ends are treated as unbounded (negative or positive infinity respectively).
        Parameters:
        value - the date to test, may be null
        Returns:
        true if value is within the range

      • getDays

        public java.util.OptionalLong getDays()
        Returns the inclusive 24-hour-block count between begin and end. A range whose endpoints fall on the same UTC instant returns 1; each additional full 24 h adds 1.

        Wall-clock, not calendar-day, semantics. The result is derived from end - begin in milliseconds, divided by 24 h. A range like 2026-01-01 23:59 → 2026-01-02 00:01 spans two calendar dates but returns 1 because the wall-clock duration is only two minutes. Likewise a DST "spring forward" range whose endpoints both read 02:30 local time can return 0 because the underlying duration is 23 h. For zone-aware calendar-day counting use LocalDateRange.getDays() instead.

        Returns an empty OptionalLong when the range is not closed (either end is null). When the range is closed and inverted (end before begin) a non-positive value is wrapped in the optional — this class does not auto-swap. The optional return type is deliberate: it forces callers to acknowledge the "open-ended" case at compile time, replacing the previous Long.MIN_VALUE sentinel which collided with sub-24 h inverted ranges.

        Inverted-range semantics. The signed formula is diffMs >= 0 ? toDays(diffMs) + 1 : toDays(diffMs) - 1. The inclusive-count language only applies to forward ranges; for inverted ranges the returned value is a negative "signed inclusive count" (e.g. begin=Jan 5, end=Jan 4 → -2; begin=Jan 5 noon, end=Jan 5 morning → -1). Callers reasoning about magnitude should apply Math.abs(...); callers wanting only forward ranges should swap endpoints before calling, or check compareTo(...).

        Returns:
        the inclusive 24-h-block count for closed ranges (negative when inverted), or OptionalLong.empty() when either endpoint is null

      • overlaps

        public boolean overlaps​(DateRange other)
        Tests whether this range overlaps the supplied range. null ends are treated as unbounded. An empty range never overlaps.
        Parameters:
        other - the other range
        Returns:
        true if the two ranges share at least one instant

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • toString

        public java.lang.String toString()
        Returns a debug representation in the form "yyyy-MM-dd ~ yyyy-MM-dd". The yyyy-MM-dd pattern is locale-insensitive and the zone is UTC, so the same range prints identically across JVMs and locales — this is meant for logs and diagnostics, not user-facing display. For zone-aware formatting use the DateRange value together with the consumer's own SimpleDateFormat/DateTimeFormatter.
        Overrides:
        toString in class java.lang.Object

      • compareTo

        public int compareTo​(DateRange o)
        Specified by:
        compareTo in interface java.lang.Comparable<DateRange>