com.dlsc.flexgantt.model

## Class TimeSpan

- java.lang.Object
- - com.dlsc.flexgantt.model.TimeSpan

- All Implemented Interfaces:
    ITimeSpan, Serializable, Comparable<ITimeSpan>

      public class TimeSpan
      extends Object
      implements ITimeSpan

  An implementation of the `ITimeSpan` interface.
  Since:
    1.0
  Author:
    Dirk Lemmermann
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static TimeSpan` | `ALL` A time span, which covers the entire possible horizon from time point 0 until `Long.MAX_VALUE`.
    `static ITimeSpan` | `DEFAULT_TIME_SPAN` Stores a default time span instance, where the start time is the current system time and the end time is the current system time plus one year.
    `static TimeSpan` | `UNDEFINED` An undefined time span, which gets used in various algorithms to express that no valid time span has been calculated, yet.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TimeSpan()` Constructs a new time span where the start and end time are equal to zero.
    `TimeSpan(Calendar time)` Constructs a new time span where the start and end times are equal to the milliseconds of the given calendar object.
    `TimeSpan(Calendar start, Calendar end)` Constructs a new time span where the start and end times are based on the given calendar objects.
    `TimeSpan(Date date)` Constructs a new time span where the start and end times are equal to the give date.
    `TimeSpan(Date start, Date end)` Constructs a new time span with the given start and end dates.
    `TimeSpan(int year, int month, int date)` Constructs a new time point for the given year, month and date.
    `TimeSpan(int startYear, int startMonth, int startDate, int endYear, int endMonth, int endDate)` Constructs a new time span for the given year, month and date.
    `TimeSpan(int startYear, int startMonth, int startDate, int endYear, int endMonth, int endDate, TimeZone timeZone)` Constructs a new time span for the given year, month and date.
    `TimeSpan(int year, int month, int date, TimeZone timeZone)` Constructs a new time point for the given year, month and date.
    `TimeSpan(ITimeSpan span)` Constructs a new time span based on an already existing time span.
    `TimeSpan(long time)` Constructs a new time span where the start time and the end time are both equal to given time.
    `TimeSpan(long start, long end)` Constructs a new time span with the given start and end.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compareTo(ITimeSpan span)`
    `boolean` | `contains(ITimeSpan span)` Checks whether the time span contains the given time span.
    `boolean` | `contains(long time)` Checks whether the time span contains the given time point.
    `boolean` | `endsAfter(ITimeSpan span)` Checks whether the given time span ends after this time span.
    `boolean` | `endsBefore(ITimeSpan span)` Checks whether the given time span ends before this time span.
    `boolean` | `equalDuration(ITimeSpan span)` Checks whether the given time span has exactly the same duration as this time span.
    `boolean` | `equals(ITimeSpan span)` Two time spans are considered equal if their start times and their end times are identical.
    `boolean` | `equals(Object o)`
    `long` | `getDuration()` Calculates the total duration of this time span.
    `Calendar` | `getEndCalendar()` Returns a new calendar object based on the current end time.
    `Calendar` | `getEndCalendar(TimeZone timeZone)` Returns a new calendar object based on the current end time.
    `Date` | `getEndDate()` Returns a new date object based on the current end time.
    `long` | `getEndTime()` Returns the time span's end time.
    `Calendar` | `getStartCalendar()` Returns a new calendar object based on the current start time.
    `Calendar` | `getStartCalendar(TimeZone timeZone)` Returns a new calendar object based on the current start time.
    `Date` | `getStartDate()` Returns a new date object based on the current start time.
    `long` | `getStartTime()` Returns the time span's start time.
    `ITimeSpan` | `intersection(ITimeSpan span)` Returns the intersection between the time span and the given time span.
    `boolean` | `intersects(ITimeSpan span)` Checks whether the given time span intersects with this time span.
    `boolean` | `isActivity()` Determines whether this time span represents an activity.
    `boolean` | `isEvent()` Determines whether this time span represents an event.
    `boolean` | `isUndefined()` Checks whether this time span is undefined.
    `TimeSpan` | `move(long delta)` Constructs a new time span based on this span where the given (delta) milliseconds are added to (or subtracted from if negative) the start and end time of this time span.
    `boolean` | `startsAfter(ITimeSpan span)` Checks whether the given time span starts after this time span.
    `boolean` | `startsBefore(ITimeSpan span)` Checks whether the given time span starts before this time span.
    `String` | `toString()`
    `String` | `toString(DateFormat format)` Returns a compact string representation of the time span.
    `ITimeSpan` | `union(ITimeSpan span)` The union of two time spans is a new time span, where the start time of the new span is the minimum start time and the end time is the maximum end time of the two spans.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### UNDEFINED

          public static final TimeSpan UNDEFINED

      An undefined time span, which gets used in various algorithms to express that no valid time span has been calculated, yet. This could for example be the case when there are no timeline objects in a Gantt chart row and the algorithm tries to calculate the time span used by that row.
      Since:
        1.0

    - #### ALL

          public static final TimeSpan ALL

      A time span, which covers the entire possible horizon from time point 0 until `Long.MAX_VALUE`.
      Since:
        1.1

    - #### DEFAULT_TIME_SPAN

          public static final ITimeSpan DEFAULT_TIME_SPAN

      Stores a default time span instance, where the start time is the current system time and the end time is the current system time plus one year. Both start time and time time will be rounded down to the beginning of their days.
      Since:
        1.0

  - ### Constructor Detail

    - #### TimeSpan

          public TimeSpan(long start,
                          long end)

      Constructs a new time span with the given start and end.
      Parameters:
        `start` - the start time of the time span
        `end` - the end time of the time span
      Since:
        1.0

    - #### TimeSpan

          public TimeSpan(long time)

      Constructs a new time span where the start time and the end time are both equal to given time.
      Parameters:
        `time` - the start and end time of the time span
      Since:
        1.0

    - #### TimeSpan

          public TimeSpan(ITimeSpan span)

      Constructs a new time span based on an already existing time span.
      Parameters:
        `span` - the original time span
      Since:
        1.0

    - #### TimeSpan

          public TimeSpan(Date start,
                          Date end)

      Constructs a new time span with the given start and end dates.
      Parameters:
        `start` - the start time of the time span
        `end` - the end time of the time span
      Since:
        1.0
      See Also:
        `Date.getTime()`

    - #### TimeSpan

          public TimeSpan(Date date)

      Constructs a new time span where the start and end times are equal to the give date.
      Parameters:
        `date` - the start and end date of the time span
      Since:
        1.0
      See Also:
        `Date.getTime()`

    - #### TimeSpan

          public TimeSpan(Calendar start,
                          Calendar end)

      Constructs a new time span where the start and end times are based on the given calendar objects.
      Parameters:
        `start` - the start time of the time span
        `end` - the end time of the time span
      Since:
        1.0
      See Also:
        `Calendar.getTimeInMillis()`

    - #### TimeSpan

          public TimeSpan(Calendar time)

      Constructs a new time span where the start and end times are equal to the milliseconds of the given calendar object.
      Parameters:
        `time` - the start and end time of the time span
      Since:
        1.0
      See Also:
        `Calendar.getTimeInMillis()`

    - #### TimeSpan

          public TimeSpan(int year,
                          int month,
                          int date,
                          TimeZone timeZone)

      Constructs a new time point for the given year, month and date. Hours, minutes, seconds and milliseconds all default to 0.
      Parameters:
        `year` - the year of the time point
        `month` - the month of the time point (note: months start with 0, January = 0)
        `date` - the day of the time point
        `timeZone` - the time zone for which to create a time span
      Since:
        1.1.7

    - #### TimeSpan

          public TimeSpan(int year,
                          int month,
                          int date)

      Constructs a new time point for the given year, month and date. Hours, minutes, seconds and milliseconds all default to 0. This constructor uses the default time zone.
      Parameters:
        `year` - the year of the time point
        `month` - the month of the time point (note: months start with 0, January = 0)
        `date` - the day of the time point
      Since:
        1.0

    - #### TimeSpan

          public TimeSpan(int startYear,
                          int startMonth,
                          int startDate,
                          int endYear,
                          int endMonth,
                          int endDate,
                          TimeZone timeZone)

      Constructs a new time span for the given year, month and date. Hours, minutes, seconds and milliseconds all default to 0.
      Parameters:
        `startYear` - the start year of the time span
        `startMonth` - the start month of the time span (note: months start with 0, January = 0)
        `startDate` - the start date of the time span
        `endYear` - the end year of the time span
        `endMonth` - the end month of the time span (note: months start with 0, January = 0)
        `endDate` - the end date of the time span
        `timeZone` - the time zone for which to create a time span
      Since:
        1.1.7

    - #### TimeSpan

          public TimeSpan(int startYear,
                          int startMonth,
                          int startDate,
                          int endYear,
                          int endMonth,
                          int endDate)

      Constructs a new time span for the given year, month and date. Hours, minutes, seconds and milliseconds all default to 0. This constructor uses the default time zone.
      Parameters:
        `startYear` - the start year of the time span
        `startMonth` - the start month of the time span (note: months start with 0, January = 0)
        `startDate` - the start date of the time span
        `endYear` - the end year of the time span
        `endMonth` - the end month of the time span (note: months start with 0, January = 0)
        `endDate` - the end date of the time span
      Since:
        1.0

    - #### TimeSpan

          public TimeSpan()

      Constructs a new time span where the start and end time are equal to zero.
      Since:
        1.0

  - ### Method Detail

    - #### getStartTime

          public long getStartTime()

      Description copied from interface: `ITimeSpan`
      Returns the time span's start time. In order for a time span to be valid the end time has to be larger or equal to the end time.
      Specified by:
        `getStartTime` in interface `ITimeSpan`
      Returns:
        the start time
      See Also:
        `ITimeSpan.getEndTime()`

    - #### getStartDate

          public Date getStartDate()

      Returns a new date object based on the current start time.
      Returns:
        the time span's start time as a `Date`
      Since:
        1.0

    - #### getStartCalendar

          public Calendar getStartCalendar()

      Returns a new calendar object based on the current start time.
      Returns:
        the time span's start time as a `Calendar`
      Since:
        1.1
      See Also:
        `getStartTime()`, `getStartDate()`

    - #### getStartCalendar

          public Calendar getStartCalendar(TimeZone timeZone)

      Returns a new calendar object based on the current start time.
      Parameters:
        `timeZone` - the time zone to use
      Returns:
        the time span's start time as a `Calendar`
      Since:
        1.1.7
      See Also:
        `getStartTime()`, `getStartDate()`

    - #### getEndTime

          public long getEndTime()

      Description copied from interface: `ITimeSpan`
      Returns the time span's end time. The end time is guaranteed to be larger or equal to the start time.
      Specified by:
        `getEndTime` in interface `ITimeSpan`
      Returns:
        the end time
      See Also:
        `ITimeSpan.getStartTime()`

    - #### getEndDate

          public Date getEndDate()

      Returns a new date object based on the current end time.
      Returns:
        the time span's end time as a `Date`
      Since:
        1.0
      See Also:
        `getEndTime()`, `getEndCalendar()`

    - #### getEndCalendar

          public Calendar getEndCalendar()

      Returns a new calendar object based on the current end time.
      Returns:
        the time span's end time as a `Calendar`
      Since:
        1.1
      See Also:
        `getEndTime()`, `getEndDate()`

    - #### getEndCalendar

          public Calendar getEndCalendar(TimeZone timeZone)

      Returns a new calendar object based on the current end time.
      Parameters:
        `timeZone` - the time zone to use
      Returns:
        the time span's end time as a `Calendar`
      Since:
        1.1.7
      See Also:
        `getEndTime()`, `getEndDate()`

    - #### compareTo

          public int compareTo(ITimeSpan span)

      Specified by:
        `compareTo` in interface `Comparable<ITimeSpan>`

    - #### contains

          public boolean contains(ITimeSpan span)

      Description copied from interface: `ITimeSpan`
      Checks whether the time span contains the given time span. One time span A contains time span B if A.start <= B.start and A.end >= B.end.
      Specified by:
        `contains` in interface `ITimeSpan`
      Parameters:
        `span` - the time span to test for containment
      Returns:
        TRUE if the given time span is completely contained
      See Also:
        `ITimeSpan.intersects(ITimeSpan)`

    - #### contains

          public boolean contains(long time)

      Description copied from interface: `ITimeSpan`
      Checks whether the time span contains the given time point. One time span A contains time point TP if A.start <= TP and A.end >= TP.
      Specified by:
        `contains` in interface `ITimeSpan`
      Parameters:
        `time` - the time point to test for containment
      Returns:
        TRUE if the given time point is contained
      See Also:
        `ITimeSpan.contains(ITimeSpan)`, `ITimeSpan.intersects(ITimeSpan)`

    - #### endsAfter

          public boolean endsAfter(ITimeSpan span)

      Description copied from interface: `ITimeSpan`
      Checks whether the given time span ends after this time span. One time span A ends after time span B if A.end > B.end.
      Specified by:
        `endsAfter` in interface `ITimeSpan`
      Parameters:
        `span` - the time span to test
      Returns:
        TRUE if the given time span ends after this time span
      See Also:
        `ITimeSpan.endsBefore(ITimeSpan)`

    - #### endsBefore

          public boolean endsBefore(ITimeSpan span)

      Description copied from interface: `ITimeSpan`
      Checks whether the given time span ends before this time span. One time span A ends before time span B if A.end < B.end.
      Specified by:
        `endsBefore` in interface `ITimeSpan`
      Parameters:
        `span` - the time span to test
      Returns:
        TRUE if the given time span ends before this time span
      See Also:
        `ITimeSpan.endsAfter(ITimeSpan)`

    - #### equalDuration

          public boolean equalDuration(ITimeSpan span)

      Description copied from interface: `ITimeSpan`
      Checks whether the given time span has exactly the same duration as this time span.
      Specified by:
        `equalDuration` in interface `ITimeSpan`
      Parameters:
        `span` - the time span to test
      Returns:
        TRUE if the given time span has the same duration as this span
      See Also:
        `ITimeSpan.getDuration()`

    - #### getDuration

          public long getDuration()

      Description copied from interface: `ITimeSpan`
      Calculates the total duration of this time span. The duration is the difference between the end time and the start time.
      Specified by:
        `getDuration` in interface `ITimeSpan`
      Returns:
        the duration of this span in milliseconds
      See Also:
        `ITimeSpan.equalDuration(ITimeSpan)`

    - #### intersects

          public boolean intersects(ITimeSpan span)

      Description copied from interface: `ITimeSpan`
      Checks whether the given time span intersects with this time span. One time span A intersects with time span B if B.start < A.end <= B.end.
      Specified by:
        `intersects` in interface `ITimeSpan`
      Parameters:
        `span` - the time span to test for intersection
      Returns:
        TRUE if the given time span intersects with this time span
      See Also:
        `ITimeSpan.contains(ITimeSpan)`

    - #### intersection

          public ITimeSpan intersection(ITimeSpan span)

      Description copied from interface: `ITimeSpan`
      Returns the intersection between the time span and the given time span. The intersection of two time spans A and B is defined as the maximum of the two start times and the minimum of the two end times. This method has to return an undefined time span (see `ITimeSpan.isUndefined()`) if the two time spans do not intersect at all.
      Specified by:
        `intersection` in interface `ITimeSpan`
      Parameters:
        `span` - the time span for which to calculate the intersection
      Returns:
        the intersection (the time span in common) of the time span and the given time span

    - #### isActivity

          public boolean isActivity()

      Description copied from interface: `ITimeSpan`
      Determines whether this time span represents an activity. An activity has a duration (as opposed to an event). Implementors of this interface are free to choose other criteria for events.
      Specified by:
        `isActivity` in interface `ITimeSpan`
      Returns:
        TRUE if the time span's duration is larger than zero
      See Also:
        `ITimeSpan.isEvent()`

    - #### isEvent

          public boolean isEvent()

      Description copied from interface: `ITimeSpan`
      Determines whether this time span represents an event. An event is commonly represented by a time span where the duration is equal to zero (as opposed to an activity). Implementors of this interface are free to choose other criteria for events.
      Specified by:
        `isEvent` in interface `ITimeSpan`
      Returns:
        TRUE if the time span's duration is equal to zero
      See Also:
        `ITimeSpan.isEvent()`

    - #### move

          public TimeSpan move(long delta)

      Description copied from interface: `ITimeSpan`
      Constructs a new time span based on this span where the given (delta) milliseconds are added to (or subtracted from if negative) the start and end time of this time span.
      Specified by:
        `move` in interface `ITimeSpan`
      Parameters:
        `delta` - the amount of milliseconds to add to or subtract from the new time span's start and end time
      Returns:
        a time span moved by 'delta' milliseconds

    - #### startsAfter

          public boolean startsAfter(ITimeSpan span)

      Description copied from interface: `ITimeSpan`
      Checks whether the given time span starts after this time span. One time span A starts after time span B if A.start > B.start.
      Specified by:
        `startsAfter` in interface `ITimeSpan`
      Parameters:
        `span` - the time span to test
      Returns:
        TRUE if the given time span starts after this time span
      See Also:
        `ITimeSpan.startsBefore(ITimeSpan)`

    - #### startsBefore

          public boolean startsBefore(ITimeSpan span)

      Description copied from interface: `ITimeSpan`
      Checks whether the given time span starts before this time span. One time span A starts before time span B if A.start < B.start.
      Specified by:
        `startsBefore` in interface `ITimeSpan`
      Parameters:
        `span` - the time span to test
      Returns:
        TRUE if the given time span starts before this time span
      See Also:
        `ITimeSpan.startsAfter(ITimeSpan)`

    - #### union

          public ITimeSpan union(ITimeSpan span)

      Description copied from interface: `ITimeSpan`
      The union of two time spans is a new time span, where the start time of the new span is the minimum start time and the end time is the maximum end time of the two spans. Special checks are required when one or both of the time spans are undefined (`ITimeSpan.isUndefined()`). If only one of the spans is undefined then the other span becomes the result of the union operation. If both of them are undefined then the result will be undefined, too.
      Specified by:
        `union` in interface `ITimeSpan`
      Parameters:
        `span` - the second time span for the union
      Returns:
        a new time span object based on the minimum start and maximum end time of this time span and the given time span

    - #### isUndefined

          public boolean isUndefined()

      Description copied from interface: `ITimeSpan`
      Checks whether this time span is undefined. Undefined time spans can be used in time span calculations to indicate that no time span has been computed, yet (example: the method `ITimeSpan.union(ITimeSpan)` first checks whether the span on which the method gets called is undefined. If so and the given second time span is not undefined then the result of the union operation will be a copy of the second span).
      Specified by:
        `isUndefined` in interface `ITimeSpan`
      Returns:
        TRUE if the time span is undefined

    - #### equals

          public boolean equals(ITimeSpan span)

      Description copied from interface: `ITimeSpan`
      Two time spans are considered equal if their start times and their end times are identical.
      Specified by:
        `equals` in interface `ITimeSpan`
      Parameters:
        `span` - the time span to test
      Returns:
        TRUE if this time span and the given time span have the same start and end times

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### toString

          public String toString(DateFormat format)

      Description copied from interface: `ITimeSpan`
      Returns a compact string representation of the time span. The method uses the given date formatting object.
      Specified by:
        `toString` in interface `ITimeSpan`
      Parameters:
        `format` - the formatter used to create a date string
      Returns:
        a nicely formatted text representation of the time span

Copyright © 2006–2020 Dirk Lemmermann Software & Consulting. All rights reserved.