cesium_nxmap/_cesium@1.72.0@cesium/Source/Core/TimeInterval.js

import Check from "./Check.js";
import defaultValue from "./defaultValue.js";
import defined from "./defined.js";
import DeveloperError from "./DeveloperError.js";
import JulianDate from "./JulianDate.js";

/**
 * An interval defined by a start and a stop time; optionally including those times as part of the interval.
 * Arbitrary data can optionally be associated with each instance for used with {@link TimeIntervalCollection}.
 *
 * @alias TimeInterval
 * @constructor
 *
 * @param {Object} [options] Object with the following properties:
 * @param {JulianDate} [options.start=new JulianDate()] The start time of the interval.
 * @param {JulianDate} [options.stop=new JulianDate()] The stop time of the interval.
 * @param {Boolean} [options.isStartIncluded=true] <code>true</code> if <code>options.start</code> is included in the interval, <code>false</code> otherwise.
 * @param {Boolean} [options.isStopIncluded=true] <code>true</code> if <code>options.stop</code> is included in the interval, <code>false</code> otherwise.
 * @param {Object} [options.data] Arbitrary data associated with this interval.
 *
 * @example
 * // Create an instance that spans August 1st, 1980 and is associated
 * // with a Cartesian position.
 * var timeInterval = new Cesium.TimeInterval({
 *     start : Cesium.JulianDate.fromIso8601('1980-08-01T00:00:00Z'),
 *     stop : Cesium.JulianDate.fromIso8601('1980-08-02T00:00:00Z'),
 *     isStartIncluded : true,
 *     isStopIncluded : false,
 *     data : Cesium.Cartesian3.fromDegrees(39.921037, -75.170082)
 * });
 *
 * @example
 * // Create two instances from ISO 8601 intervals with associated numeric data
 * // then compute their intersection, summing the data they contain.
 * var left = Cesium.TimeInterval.fromIso8601({
 *     iso8601 : '2000/2010',
 *     data : 2
 * });
 *
 * var right = Cesium.TimeInterval.fromIso8601({
 *     iso8601 : '1995/2005',
 *     data : 3
 * });
 *
 * //The result of the below intersection will be an interval equivalent to
 * //var intersection = Cesium.TimeInterval.fromIso8601({
 * //  iso8601 : '2000/2005',
 * //  data : 5
 * //});
 * var intersection = new Cesium.TimeInterval();
 * Cesium.TimeInterval.intersect(left, right, intersection, function(leftData, rightData) {
 *     return leftData + rightData;
 * });
 *
 * @example
 * // Check if an interval contains a specific time.
 * var dateToCheck = Cesium.JulianDate.fromIso8601('1982-09-08T11:30:00Z');
 * var containsDate = Cesium.TimeInterval.contains(timeInterval, dateToCheck);
 */
function TimeInterval(options) {
  options = defaultValue(options, defaultValue.EMPTY_OBJECT);
  /**
   * Gets or sets the start time of this interval.
   * @type {JulianDate}
   */
  this.start = defined(options.start)
    ? JulianDate.clone(options.start)
    : new JulianDate();

  /**
   * Gets or sets the stop time of this interval.
   * @type {JulianDate}
   */
  this.stop = defined(options.stop)
    ? JulianDate.clone(options.stop)
    : new JulianDate();

  /**
   * Gets or sets the data associated with this interval.
   * @type {*}
   */
  this.data = options.data;

  /**
   * Gets or sets whether or not the start time is included in this interval.
   * @type {Boolean}
   * @default true
   */
  this.isStartIncluded = defaultValue(options.isStartIncluded, true);

  /**
   * Gets or sets whether or not the stop time is included in this interval.
   * @type {Boolean}
   * @default true
   */
  this.isStopIncluded = defaultValue(options.isStopIncluded, true);
}

Object.defineProperties(TimeInterval.prototype, {
  /**
   * Gets whether or not this interval is empty.
   * @memberof TimeInterval.prototype
   * @type {Boolean}
   * @readonly
   */
  isEmpty: {
    get: function () {
      var stopComparedToStart = JulianDate.compare(this.stop, this.start);
      return (
        stopComparedToStart < 0 ||
        (stopComparedToStart === 0 &&
          (!this.isStartIncluded || !this.isStopIncluded))
      );
    },
  },
});

var scratchInterval = {
  start: undefined,
  stop: undefined,
  isStartIncluded: undefined,
  isStopIncluded: undefined,
  data: undefined,
};

/**
 * Creates a new instance from a {@link http://en.wikipedia.org/wiki/ISO_8601|ISO 8601} interval.
 *
 * @throws DeveloperError if options.iso8601 does not match proper formatting.
 *
 * @param {Object} options Object with the following properties:
 * @param {String} options.iso8601 An ISO 8601 interval.
 * @param {Boolean} [options.isStartIncluded=true] <code>true</code> if <code>options.start</code> is included in the interval, <code>false</code> otherwise.
 * @param {Boolean} [options.isStopIncluded=true] <code>true</code> if <code>options.stop</code> is included in the interval, <code>false</code> otherwise.
 * @param {Object} [options.data] Arbitrary data associated with this interval.
 * @param {TimeInterval} [result] An existing instance to use for the result.
 * @returns {TimeInterval} The modified result parameter or a new instance if none was provided.
 */
TimeInterval.fromIso8601 = function (options, result) {
  //>>includeStart('debug', pragmas.debug);
  Check.typeOf.object("options", options);
  Check.typeOf.string("options.iso8601", options.iso8601);
  //>>includeEnd('debug');

  var dates = options.iso8601.split("/");
  if (dates.length !== 2) {
    throw new DeveloperError(
      "options.iso8601 is an invalid ISO 8601 interval."
    );
  }
  var start = JulianDate.fromIso8601(dates[0]);
  var stop = JulianDate.fromIso8601(dates[1]);
  var isStartIncluded = defaultValue(options.isStartIncluded, true);
  var isStopIncluded = defaultValue(options.isStopIncluded, true);
  var data = options.data;

  if (!defined(result)) {
    scratchInterval.start = start;
    scratchInterval.stop = stop;
    scratchInterval.isStartIncluded = isStartIncluded;
    scratchInterval.isStopIncluded = isStopIncluded;
    scratchInterval.data = data;
    return new TimeInterval(scratchInterval);
  }

  result.start = start;
  result.stop = stop;
  result.isStartIncluded = isStartIncluded;
  result.isStopIncluded = isStopIncluded;
  result.data = data;
  return result;
};

/**
 * Creates an ISO8601 representation of the provided interval.
 *
 * @param {TimeInterval} timeInterval The interval to be converted.
 * @param {Number} [precision] The number of fractional digits used to represent the seconds component.  By default, the most precise representation is used.
 * @returns {String} The ISO8601 representation of the provided interval.
 */
TimeInterval.toIso8601 = function (timeInterval, precision) {
  //>>includeStart('debug', pragmas.debug);
  Check.typeOf.object("timeInterval", timeInterval);
  //>>includeEnd('debug');

  return (
    JulianDate.toIso8601(timeInterval.start, precision) +
    "/" +
    JulianDate.toIso8601(timeInterval.stop, precision)
  );
};

/**
 * Duplicates the provided instance.
 *
 * @param {TimeInterval} [timeInterval] The instance to clone.
 * @param {TimeInterval} [result] An existing instance to use for the result.
 * @returns {TimeInterval} The modified result parameter or a new instance if none was provided.
 */
TimeInterval.clone = function (timeInterval, result) {
  if (!defined(timeInterval)) {
    return undefined;
  }
  if (!defined(result)) {
    return new TimeInterval(timeInterval);
  }
  result.start = timeInterval.start;
  result.stop = timeInterval.stop;
  result.isStartIncluded = timeInterval.isStartIncluded;
  result.isStopIncluded = timeInterval.isStopIncluded;
  result.data = timeInterval.data;
  return result;
};

/**
 * Compares two instances and returns <code>true</code> if they are equal, <code>false</code> otherwise.
 *
 * @param {TimeInterval} [left] The first instance.
 * @param {TimeInterval} [right] The second instance.
 * @param {TimeInterval.DataComparer} [dataComparer] A function which compares the data of the two intervals.  If omitted, reference equality is used.
 * @returns {Boolean} <code>true</code> if the dates are equal; otherwise, <code>false</code>.
 */
TimeInterval.equals = function (left, right, dataComparer) {
  return (
    left === right ||
    (defined(left) &&
      defined(right) &&
      ((left.isEmpty && right.isEmpty) ||
        (left.isStartIncluded === right.isStartIncluded &&
          left.isStopIncluded === right.isStopIncluded &&
          JulianDate.equals(left.start, right.start) &&
          JulianDate.equals(left.stop, right.stop) &&
          (left.data === right.data ||
            (defined(dataComparer) && dataComparer(left.data, right.data))))))
  );
};

/**
 * Compares two instances and returns <code>true</code> if they are within <code>epsilon</code> seconds of
 * each other.  That is, in order for the dates to be considered equal (and for
 * this function to return <code>true</code>), the absolute value of the difference between them, in
 * seconds, must be less than <code>epsilon</code>.
 *
 * @param {TimeInterval} [left] The first instance.
 * @param {TimeInterval} [right] The second instance.
 * @param {Number} [epsilon=0] The maximum number of seconds that should separate the two instances.
 * @param {TimeInterval.DataComparer} [dataComparer] A function which compares the data of the two intervals.  If omitted, reference equality is used.
 * @returns {Boolean} <code>true</code> if the two dates are within <code>epsilon</code> seconds of each other; otherwise <code>false</code>.
 */
TimeInterval.equalsEpsilon = function (left, right, epsilon, dataComparer) {
  epsilon = defaultValue(epsilon, 0);

  return (
    left === right ||
    (defined(left) &&
      defined(right) &&
      ((left.isEmpty && right.isEmpty) ||
        (left.isStartIncluded === right.isStartIncluded &&
          left.isStopIncluded === right.isStopIncluded &&
          JulianDate.equalsEpsilon(left.start, right.start, epsilon) &&
          JulianDate.equalsEpsilon(left.stop, right.stop, epsilon) &&
          (left.data === right.data ||
            (defined(dataComparer) && dataComparer(left.data, right.data))))))
  );
};

/**
 * Computes the intersection of two intervals, optionally merging their data.
 *
 * @param {TimeInterval} left The first interval.
 * @param {TimeInterval} [right] The second interval.
 * @param {TimeInterval} [result] An existing instance to use for the result.
 * @param {TimeInterval.MergeCallback} [mergeCallback] A function which merges the data of the two intervals. If omitted, the data from the left interval will be used.
 * @returns {TimeInterval} The modified result parameter.
 */
TimeInterval.intersect = function (left, right, result, mergeCallback) {
  //>>includeStart('debug', pragmas.debug);
  Check.typeOf.object("left", left);
  //>>includeEnd('debug');

  if (!defined(right)) {
    return TimeInterval.clone(TimeInterval.EMPTY, result);
  }

  var leftStart = left.start;
  var leftStop = left.stop;

  var rightStart = right.start;
  var rightStop = right.stop;

  var intersectsStartRight =
    JulianDate.greaterThanOrEquals(rightStart, leftStart) &&
    JulianDate.greaterThanOrEquals(leftStop, rightStart);
  var intersectsStartLeft =
    !intersectsStartRight &&
    JulianDate.lessThanOrEquals(rightStart, leftStart) &&
    JulianDate.lessThanOrEquals(leftStart, rightStop);

  if (!intersectsStartRight && !intersectsStartLeft) {
    return TimeInterval.clone(TimeInterval.EMPTY, result);
  }

  var leftIsStartIncluded = left.isStartIncluded;
  var leftIsStopIncluded = left.isStopIncluded;
  var rightIsStartIncluded = right.isStartIncluded;
  var rightIsStopIncluded = right.isStopIncluded;
  var leftLessThanRight = JulianDate.lessThan(leftStop, rightStop);

  if (!defined(result)) {
    result = new TimeInterval();
  }

  result.start = intersectsStartRight ? rightStart : leftStart;
  result.isStartIncluded =
    (leftIsStartIncluded && rightIsStartIncluded) ||
    (!JulianDate.equals(rightStart, leftStart) &&
      ((intersectsStartRight && rightIsStartIncluded) ||
        (intersectsStartLeft && leftIsStartIncluded)));
  result.stop = leftLessThanRight ? leftStop : rightStop;
  result.isStopIncluded = leftLessThanRight
    ? leftIsStopIncluded
    : (leftIsStopIncluded && rightIsStopIncluded) ||
      (!JulianDate.equals(rightStop, leftStop) && rightIsStopIncluded);
  result.data = defined(mergeCallback)
    ? mergeCallback(left.data, right.data)
    : left.data;
  return result;
};

/**
 * Checks if the specified date is inside the provided interval.
 *
 * @param {TimeInterval} timeInterval The interval.
 * @param {JulianDate} julianDate The date to check.
 * @returns {Boolean} <code>true</code> if the interval contains the specified date, <code>false</code> otherwise.
 */
TimeInterval.contains = function (timeInterval, julianDate) {
  //>>includeStart('debug', pragmas.debug);
  Check.typeOf.object("timeInterval", timeInterval);
  Check.typeOf.object("julianDate", julianDate);
  //>>includeEnd('debug');

  if (timeInterval.isEmpty) {
    return false;
  }

  var startComparedToDate = JulianDate.compare(timeInterval.start, julianDate);
  if (startComparedToDate === 0) {
    return timeInterval.isStartIncluded;
  }

  var dateComparedToStop = JulianDate.compare(julianDate, timeInterval.stop);
  if (dateComparedToStop === 0) {
    return timeInterval.isStopIncluded;
  }

  return startComparedToDate < 0 && dateComparedToStop < 0;
};

/**
 * Duplicates this instance.
 *
 * @param {TimeInterval} [result] An existing instance to use for the result.
 * @returns {TimeInterval} The modified result parameter or a new instance if none was provided.
 */
TimeInterval.prototype.clone = function (result) {
  return TimeInterval.clone(this, result);
};

/**
 * Compares this instance against the provided instance componentwise and returns
 * <code>true</code> if they are equal, <code>false</code> otherwise.
 *
 * @param {TimeInterval} [right] The right hand side interval.
 * @param {TimeInterval.DataComparer} [dataComparer] A function which compares the data of the two intervals.  If omitted, reference equality is used.
 * @returns {Boolean} <code>true</code> if they are equal, <code>false</code> otherwise.
 */
TimeInterval.prototype.equals = function (right, dataComparer) {
  return TimeInterval.equals(this, right, dataComparer);
};

/**
 * Compares this instance against the provided instance componentwise and returns
 * <code>true</code> if they are within the provided epsilon,
 * <code>false</code> otherwise.
 *
 * @param {TimeInterval} [right] The right hand side interval.
 * @param {Number} [epsilon=0] The epsilon to use for equality testing.
 * @param {TimeInterval.DataComparer} [dataComparer] A function which compares the data of the two intervals.  If omitted, reference equality is used.
 * @returns {Boolean} <code>true</code> if they are within the provided epsilon, <code>false</code> otherwise.
 */
TimeInterval.prototype.equalsEpsilon = function (right, epsilon, dataComparer) {
  return TimeInterval.equalsEpsilon(this, right, epsilon, dataComparer);
};

/**
 * Creates a string representing this TimeInterval in ISO8601 format.
 *
 * @returns {String} A string representing this TimeInterval in ISO8601 format.
 */
TimeInterval.prototype.toString = function () {
  return TimeInterval.toIso8601(this);
};

/**
 * An immutable empty interval.
 *
 * @type {TimeInterval}
 * @constant
 */
TimeInterval.EMPTY = Object.freeze(
  new TimeInterval({
    start: new JulianDate(),
    stop: new JulianDate(),
    isStartIncluded: false,
    isStopIncluded: false,
  })
);

/**
 * Function interface for merging interval data.
 * @callback TimeInterval.MergeCallback
 *
 * @param {*} leftData The first data instance.
 * @param {*} rightData The second data instance.
 * @returns {*} The result of merging the two data instances.
 */

/**
 * Function interface for comparing interval data.
 * @callback TimeInterval.DataComparer
 * @param {*} leftData The first data instance.
 * @param {*} rightData The second data instance.
 * @returns {Boolean} <code>true</code> if the provided instances are equal, <code>false</code> otherwise.
 */
export default TimeInterval;