TimeSpanInterface.php

<?php

namespace Icecave\Chrono\TimeSpan;

use DateInterval;
use Icecave\Chrono\Interval\IntervalInterface;
use Icecave\Chrono\TimePointInterface;

/**
 * A common interface for non-anchored blocks of time (periods and durations).
 */
interface TimeSpanInterface
{
    /**
     * @return bool True if the time span is zero seconds in length; otherwise, false.
     */
    public function isEmpty();

    /**
     * @return TimeSpanInterface
     */
    public function inverse();

    /**
     * Resolve the time span to a total number of seconds, using the given time point as the start of the span.
     *
     * @param TimePointInterface $timePoint The start of the time span.
     *
     * @return int The total number of seconds.
     */
    public function resolveToSeconds(TimePointInterface $timePoint);

    /**
     * Resolve the time span to a {@see Duration}, using the given time point as the start of the span.
     *
     * @param TimePointInterface $timePoint The start of the time span.
     *
     * @return Duration
     */
    public function resolveToDuration(TimePointInterface $timePoint);

    /**
     * Resolve the time span to a {@see Period}, using the given time point as the start of the span.
     *
     * @param TimePointInterface $timePoint The start of the time span.
     *
     * @return Period
     */
    public function resolveToPeriod(TimePointInterface $timePoint);

    /**
     * Resolve the time span an an {@see IntervalInterface} starting at the given time point, with a length equal to this time span.
     *
     * @param TimePointInterface $timePoint The start of the interval.
     *
     * @return IntervalInterface The end of the time span.
     */
    public function resolveToInterval(TimePointInterface $timePoint);

    /**
     * Resolve the time span to a time point after the given time point by the length of this span.
     *
     * @param TimePointInterface $timePoint The start of the time span.
     *
     * @return TimePointInterface
     */
    public function resolveToTimePoint(TimePointInterface $timePoint);

    /**
     * @return DateInterval A native PHP DateInterval instance representing this span.
     */
    public function nativeDateInterval();

    /**
     * @return string
     */
    public function string();

    /**
     * @return string
     */
    public function __toString();
}