std.datetime.interval

Category Functions
Main types Interval Direction
Special intervals everyDayOfWeek everyMonth everyDuration
Special intervals NegInfInterval PosInfInterval
Underlying ranges IntervalRange NegInfIntervalRange PosInfIntervalRange
Flags PopFirst

License:
Boost License 1.0.
Authors:
Jonathan M Davis
Source
std/datetime/interval.d
enum Direction: int;

Indicates a direction in time. One example of its use is Interval's expand function which uses it to indicate whether the interval should be expanded backwards (into the past), forwards (into the future), or both.

bwd

Backward.

fwd

Forward.

both

Both backward and forward.

alias PopFirst = std.typecons.Flag!"popFirst".Flag;

Used to indicate whether popFront should be called immediately upon creating a range. The idea is that for some functions used to generate a range for an interval, front is not necessarily a time point which would ever be generated by the range (e.g. if the range were every Sunday within an interval, but the interval started on a Monday), so there needs to be a way to deal with that. To get the first time point in the range to match what the function generates, then use PopFirst.yes to indicate that the range should have popFront called on it before the range is returned so that front is a time point which the function would generate. To let the first time point not match the generator function, use PopFront.no.

For instance, if the function used to generate a range of time points generated successive Easters (i.e. you're iterating over all of the Easters within the interval), the initial date probably isn't an Easter. Using PopFirst.yes would tell the function which returned the range that popFront was to be called so that front would then be an Easter - the next one generated by the function (which when iterating forward would be the Easter following the original front, while when iterating backward, it would be the Easter prior to the original front). If PopFirst.no were used, then front would remain the original time point and it would not necessarily be a time point which would be generated by the range-generating function (which in many cases is exactly what is desired - e.g. if iterating over every day starting at the beginning of the interval).

If set to PopFirst.no, then popFront is not called before returning the range.

Otherwise, if set to PopFirst.yes, then popFront is called before returning the range.

struct Interval(TP);

Represents an interval of time.

An Interval has a starting point and an end point. The interval of time is therefore the time starting at the starting point up to, but not including, the end point. e.g.

[January 5th, 2010 - March 10th, 2010)
[05:00:30 - 12:00:00)
[1982-01-04T08:59:00 - 2010-07-04T12:00:00)


A range can be obtained from an Interval, allowing iteration over that interval, with the exact time points which are iterated over depending on the function which generates the range.

pure this(U)(scope const TP begin, scope const U end)
Constraints: if (is(immutable(TP) == immutable(U)));
Parameters:
TP begin The time point which begins the interval.
U end The time point which ends (but is not included in) the interval.
Throws:
std.datetime.date.DateTimeException if end is before begin.
Example
Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1));
pure this(D)(scope const TP begin, scope const D duration)
Constraints: if (__traits(compiles, begin + duration));
Parameters:
TP begin The time point which begins the interval.
D duration The duration from the starting point to the end point.
Throws:
std.datetime.date.DateTimeException if the resulting end is before begin.
Example
assert(Interval!Date(Date(1996, 1, 2), dur!"days"(3)) ==
       Interval!Date(Date(1996, 1, 2), Date(1996, 1, 5)));
pure nothrow ref Interval opAssign(ref const Interval rhs);
Parameters:
Interval rhs The Interval to assign to this one.
pure nothrow ref Interval opAssign(Interval rhs);
Parameters:
Interval rhs The Interval to assign to this one.
const pure nothrow @property TP begin();

The starting point of the interval. It is included in the interval.

Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).begin ==
       Date(1996, 1, 2));
pure @property void begin(TP timePoint);

The starting point of the interval. It is included in the interval.

Parameters:
TP timePoint The time point to set begin to.
Throws:
std.datetime.date.DateTimeException if the resulting interval would be invalid.
const pure nothrow @property TP end();

The end point of the interval. It is excluded from the interval.

Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).end ==
       Date(2012, 3, 1));
pure @property void end(TP timePoint);

The end point of the interval. It is excluded from the interval.

Parameters:
TP timePoint The time point to set end to.
Throws:
std.datetime.date.DateTimeException if the resulting interval would be invalid.
const pure nothrow @property auto length();

Returns the duration between begin and end.

Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).length ==
       dur!"days"(5903));
const pure nothrow @property bool empty();

Whether the interval's length is 0, that is, whether begin == end.

Example
assert(Interval!Date(Date(1996, 1, 2), Date(1996, 1, 2)).empty);
assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).empty);
const pure bool contains(scope const TP timePoint);

Whether the given time point is within this interval.

Parameters:
TP timePoint The time point to check for inclusion in this interval.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Example
assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).contains(
            Date(1994, 12, 24)));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).contains(
            Date(2000, 1, 5)));
assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).contains(
            Date(2012, 3, 1)));
const pure bool contains(scope const Interval interval);

Whether the given interval is completely within this interval.

Parameters:
Interval interval The interval to check for inclusion in this interval.
Throws:
std.datetime.date.DateTimeException if either interval is empty.
Example
assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).contains(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).contains(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))));

assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).contains(
            Interval!Date(Date(1998, 2, 28), Date(2013, 5, 1))));
const pure bool contains(scope const PosInfInterval!TP interval);

Whether the given interval is completely within this interval.

Always returns false (unless this interval is empty), because an interval going to positive infinity can never be contained in a finite interval.

Parameters:
PosInfInterval!TP interval The interval to check for inclusion in this interval.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Example
assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).contains(
            PosInfInterval!Date(Date(1999, 5, 4))));
const pure bool contains(scope const NegInfInterval!TP interval);

Whether the given interval is completely within this interval.

Always returns false (unless this interval is empty), because an interval beginning at negative infinity can never be contained in a finite interval.

Parameters:
NegInfInterval!TP interval The interval to check for inclusion in this interval.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Example
assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).contains(
            NegInfInterval!Date(Date(1996, 5, 4))));
const pure bool isBefore(scope const TP timePoint);

Whether this interval is before the given time point.

Parameters:
TP timePoint The time point to check whether this interval is before it.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Example
assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isBefore(
            Date(1994, 12, 24)));

assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isBefore(
            Date(2000, 1, 5)));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isBefore(
            Date(2012, 3, 1)));
const pure bool isBefore(scope const Interval interval);

Whether this interval is before the given interval and does not intersect with it.

Parameters:
Interval interval The interval to check for against this interval.
Throws:
std.datetime.date.DateTimeException if either interval is empty.
Example
assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isBefore(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))));

assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isBefore(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isBefore(
            Interval!Date(Date(2012, 3, 1), Date(2013, 5, 1))));
const pure bool isBefore(scope const PosInfInterval!TP interval);

Whether this interval is before the given interval and does not intersect with it.

Parameters:
PosInfInterval!TP interval The interval to check for against this interval.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Example
assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isBefore(
            PosInfInterval!Date(Date(1999, 5, 4))));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isBefore(
            PosInfInterval!Date(Date(2013, 3, 7))));
const pure bool isBefore(scope const NegInfInterval!TP interval);

Whether this interval is before the given interval and does not intersect with it.

Always returns false (unless this interval is empty) because a finite interval can never be before an interval beginning at negative infinity.

Parameters:
NegInfInterval!TP interval The interval to check for against this interval.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Example
assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isBefore(
            NegInfInterval!Date(Date(1996, 5, 4))));
const pure bool isAfter(scope const TP timePoint);

Whether this interval is after the given time point.

Parameters:
TP timePoint The time point to check whether this interval is after it.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isAfter(
            Date(1994, 12, 24)));

assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isAfter(
            Date(2000, 1, 5)));

assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isAfter(
            Date(2012, 3, 1)));
const pure bool isAfter(scope const Interval interval);

Whether this interval is after the given interval and does not intersect it.

Parameters:
Interval interval The interval to check against this interval.
Throws:
std.datetime.date.DateTimeException if either interval is empty.
Example
assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isAfter(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))));

assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isAfter(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isAfter(
            Interval!Date(Date(1989, 3, 1), Date(1996, 1, 2))));
const pure bool isAfter(scope const PosInfInterval!TP interval);

Whether this interval is after the given interval and does not intersect it.

Always returns false (unless this interval is empty) because a finite interval can never be after an interval going to positive infinity.

Parameters:
PosInfInterval!TP interval The interval to check against this interval.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Example
assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isAfter(
            PosInfInterval!Date(Date(1999, 5, 4))));
const pure bool isAfter(scope const NegInfInterval!TP interval);

Whether this interval is after the given interval and does not intersect it.

Parameters:
NegInfInterval!TP interval The interval to check against this interval.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isAfter(
            NegInfInterval!Date(Date(1996, 1, 2))));
const pure bool intersects(scope const Interval interval);

Whether the given interval overlaps this interval.

Parameters:
Interval interval The interval to check for intersection with this interval.
Throws:
std.datetime.date.DateTimeException if either interval is empty.
Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).intersects(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).intersects(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))));

assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).intersects(
            Interval!Date(Date(1989, 3, 1), Date(1996, 1, 2))));
const pure bool intersects(scope const PosInfInterval!TP interval);

Whether the given interval overlaps this interval.

Parameters:
PosInfInterval!TP interval The interval to check for intersection with this interval.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).intersects(
            PosInfInterval!Date(Date(1999, 5, 4))));

assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).intersects(
            PosInfInterval!Date(Date(2012, 3, 1))));
const pure bool intersects(scope const NegInfInterval!TP interval);

Whether the given interval overlaps this interval.

Parameters:
NegInfInterval!TP interval The interval to check for intersection with this interval.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Example
assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).intersects(
            NegInfInterval!Date(Date(1996, 1, 2))));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).intersects(
            NegInfInterval!Date(Date(2000, 1, 2))));
const Interval intersection(scope const Interval interval);

Returns the intersection of two intervals

Parameters:
Interval interval The interval to intersect with this interval.
Throws:
std.datetime.date.DateTimeException if the two intervals do not intersect or if either interval is empty.
Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).intersection(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))) ==
       Interval!Date(Date(1996, 1 , 2), Date(2000, 8, 2)));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).intersection(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))) ==
       Interval!Date(Date(1999, 1 , 12), Date(2011, 9, 17)));
const Interval intersection(scope const PosInfInterval!TP interval);

Returns the intersection of two intervals

Parameters:
PosInfInterval!TP interval The interval to intersect with this interval.
Throws:
std.datetime.date.DateTimeException if the two intervals do not intersect or if this interval is empty.
Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).intersection(
            PosInfInterval!Date(Date(1990, 7, 6))) ==
       Interval!Date(Date(1996, 1 , 2), Date(2012, 3, 1)));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).intersection(
            PosInfInterval!Date(Date(1999, 1, 12))) ==
       Interval!Date(Date(1999, 1 , 12), Date(2012, 3, 1)));
const Interval intersection(scope const NegInfInterval!TP interval);

Returns the intersection of two intervals

Parameters:
NegInfInterval!TP interval The interval to intersect with this interval.
Throws:
std.datetime.date.DateTimeException if the two intervals do not intersect or if this interval is empty.
Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).intersection(
            NegInfInterval!Date(Date(1999, 7, 6))) ==
       Interval!Date(Date(1996, 1 , 2), Date(1999, 7, 6)));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).intersection(
            NegInfInterval!Date(Date(2013, 1, 12))) ==
       Interval!Date(Date(1996, 1 , 2), Date(2012, 3, 1)));
const pure bool isAdjacent(scope const Interval interval);

Whether the given interval is adjacent to this interval.

Parameters:
Interval interval The interval to check whether its adjecent to this interval.
Throws:
std.datetime.date.DateTimeException if either interval is empty.
Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isAdjacent(
            Interval!Date(Date(1990, 7, 6), Date(1996, 1, 2))));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isAdjacent(
            Interval!Date(Date(2012, 3, 1), Date(2013, 9, 17))));

assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isAdjacent(
            Interval!Date(Date(1989, 3, 1), Date(2012, 3, 1))));
const pure bool isAdjacent(scope const PosInfInterval!TP interval);

Whether the given interval is adjacent to this interval.

Parameters:
PosInfInterval!TP interval The interval to check whether its adjecent to this interval.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Example
assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isAdjacent(
            PosInfInterval!Date(Date(1999, 5, 4))));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isAdjacent(
            PosInfInterval!Date(Date(2012, 3, 1))));
const pure bool isAdjacent(scope const NegInfInterval!TP interval);

Whether the given interval is adjacent to this interval.

Parameters:
NegInfInterval!TP interval The interval to check whether its adjecent to this interval.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isAdjacent(
            NegInfInterval!Date(Date(1996, 1, 2))));

assert(!Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).isAdjacent(
            NegInfInterval!Date(Date(2000, 1, 2))));
const Interval merge(scope const Interval interval);

Returns the union of two intervals

Parameters:
Interval interval The interval to merge with this interval.
Throws:
std.datetime.date.DateTimeException if the two intervals do not intersect and are not adjacent or if either interval is empty.
Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).merge(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))) ==
       Interval!Date(Date(1990, 7 , 6), Date(2012, 3, 1)));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).merge(
            Interval!Date(Date(2012, 3, 1), Date(2013, 5, 7))) ==
       Interval!Date(Date(1996, 1 , 2), Date(2013, 5, 7)));
const PosInfInterval!TP merge(scope const PosInfInterval!TP interval);

Returns the union of two intervals

Parameters:
PosInfInterval!TP interval The interval to merge with this interval.
Throws:
std.datetime.date.DateTimeException if the two intervals do not intersect and are not adjacent or if this interval is empty.
Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).merge(
            PosInfInterval!Date(Date(1990, 7, 6))) ==
       PosInfInterval!Date(Date(1990, 7 , 6)));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).merge(
            PosInfInterval!Date(Date(2012, 3, 1))) ==
       PosInfInterval!Date(Date(1996, 1 , 2)));
const NegInfInterval!TP merge(scope const NegInfInterval!TP interval);

Returns the union of two intervals

Parameters:
NegInfInterval!TP interval The interval to merge with this interval.
Throws:
std.datetime.date.DateTimeException if the two intervals do not intersect and are not adjacent or if this interval is empty.
Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).merge(
            NegInfInterval!Date(Date(1996, 1, 2))) ==
       NegInfInterval!Date(Date(2012, 3 , 1)));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).merge(
            NegInfInterval!Date(Date(2013, 1, 12))) ==
       NegInfInterval!Date(Date(2013, 1 , 12)));
const pure Interval span(scope const Interval interval);

Returns an interval that covers from the earliest time point of two intervals up to (but not including) the latest time point of two intervals.

Parameters:
Interval interval The interval to create a span together with this interval.
Throws:
std.datetime.date.DateTimeException if either interval is empty.
Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).span(
            Interval!Date(Date(1990, 7, 6), Date(1991, 1, 8))) ==
       Interval!Date(Date(1990, 7 , 6), Date(2012, 3, 1)));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).span(
            Interval!Date(Date(2012, 3, 1), Date(2013, 5, 7))) ==
       Interval!Date(Date(1996, 1 , 2), Date(2013, 5, 7)));
const pure PosInfInterval!TP span(scope const PosInfInterval!TP interval);

Returns an interval that covers from the earliest time point of two intervals up to (but not including) the latest time point of two intervals.

Parameters:
PosInfInterval!TP interval The interval to create a span together with this interval.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).span(
            PosInfInterval!Date(Date(1990, 7, 6))) ==
       PosInfInterval!Date(Date(1990, 7 , 6)));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).span(
            PosInfInterval!Date(Date(2050, 1, 1))) ==
       PosInfInterval!Date(Date(1996, 1 , 2)));
const pure NegInfInterval!TP span(scope const NegInfInterval!TP interval);

Returns an interval that covers from the earliest time point of two intervals up to (but not including) the latest time point of two intervals.

Parameters:
NegInfInterval!TP interval The interval to create a span together with this interval.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Example
assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).span(
            NegInfInterval!Date(Date(1602, 5, 21))) ==
       NegInfInterval!Date(Date(2012, 3 , 1)));

assert(Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1)).span(
            NegInfInterval!Date(Date(2013, 1, 12))) ==
       NegInfInterval!Date(Date(2013, 1 , 12)));
pure void shift(D)(D duration)
Constraints: if (__traits(compiles, begin + duration));

Shifts the interval forward or backwards in time by the given duration (a positive duration shifts the interval forward; a negative duration shifts it backward). Effectively, it does begin += duration and end += duration.

Parameters:
D duration The duration to shift the interval by.
Throws:
std.datetime.date.DateTimeException this interval is empty or if the resulting interval would be invalid.
Example
auto interval1 = Interval!Date(Date(1996, 1, 2), Date(2012, 4, 5));
auto interval2 = Interval!Date(Date(1996, 1, 2), Date(2012, 4, 5));

interval1.shift(dur!"days"(50));
assert(interval1 == Interval!Date(Date(1996, 2, 21), Date(2012, 5, 25)));

interval2.shift(dur!"days"(-50));
assert(interval2 == Interval!Date(Date(1995, 11, 13), Date(2012, 2, 15)));
void shift(T)(T years, T months = 0, AllowDayOverflow allowOverflow = AllowDayOverflow.yes)
Constraints: if (isIntegral!T);

Shifts the interval forward or backwards in time by the given number of years and/or months (a positive number of years and months shifts the interval forward; a negative number shifts it backward). It adds the years the given years and months to both begin and end. It effectively calls add!"years"() and then add!"months"() on begin and end with the given number of years and months.

Parameters:
T years The number of years to shift the interval by.
T months The number of months to shift the interval by.
AllowDayOverflow allowOverflow Whether the days should be allowed to overflow on begin and end, causing their month to increment.
Throws:
std.datetime.date.DateTimeException if this interval is empty or if the resulting interval would be invalid.
Example
auto interval1 = Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1));
auto interval2 = Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1));

interval1.shift(2);
assert(interval1 == Interval!Date(Date(1998, 1, 2), Date(2014, 3, 1)));

interval2.shift(-2);
assert(interval2 == Interval!Date(Date(1994, 1, 2), Date(2010, 3, 1)));
pure void expand(D)(D duration, Direction dir = Direction.both)
Constraints: if (__traits(compiles, begin + duration));

Expands the interval forwards and/or backwards in time. Effectively, it does begin -= duration and/or end += duration. Whether it expands forwards and/or backwards in time is determined by dir.

Parameters:
D duration The duration to expand the interval by.
Direction dir The direction in time to expand the interval.
Throws:
std.datetime.date.DateTimeException this interval is empty or if the resulting interval would be invalid.
Example
auto interval1 = Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1));
auto interval2 = Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1));

interval1.expand(2);
assert(interval1 == Interval!Date(Date(1994, 1, 2), Date(2014, 3, 1)));

interval2.expand(-2);
assert(interval2 == Interval!Date(Date(1998, 1, 2), Date(2010, 3, 1)));
void expand(T)(T years, T months = 0, AllowDayOverflow allowOverflow = AllowDayOverflow.yes, Direction dir = Direction.both)
Constraints: if (isIntegral!T);

Expands the interval forwards and/or backwards in time. Effectively, it subtracts the given number of months/years from begin and adds them to end. Whether it expands forwards and/or backwards in time is determined by dir.

Parameters:
T years The number of years to expand the interval by.
T months The number of months to expand the interval by.
AllowDayOverflow allowOverflow Whether the days should be allowed to overflow on begin and end, causing their month to increment.
Direction dir The direction in time to expand the interval.
Throws:
std.datetime.date.DateTimeException if this interval is empty or if the resulting interval would be invalid.
Example
auto interval1 = Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1));
auto interval2 = Interval!Date(Date(1996, 1, 2), Date(2012, 3, 1));

interval1.expand(2);
assert(interval1 == Interval!Date(Date(1994, 1, 2), Date(2014, 3, 1)));

interval2.expand(-2);
assert(interval2 == Interval!Date(Date(1998, 1, 2), Date(2010, 3, 1)));
const IntervalRange!(TP, Direction.fwd) fwdRange(TP delegate(scope const TP) func, PopFirst popFirst = PopFirst.no);

Returns a range which iterates forward over the interval, starting at begin, using func to generate each successive time point.

The range's front is the interval's begin. func is used to generate the next front when popFront is called. If popFirst is PopFirst.yes, then popFront is called before the range is returned (so that front is a time point which func would generate).

If func ever generates a time point less than or equal to the current front of the range, then a std.datetime.date.DateTimeException will be thrown. The range will be empty and iteration complete when func generates a time point equal to or beyond the end of the interval.

There are helper functions in this module which generate common delegates to pass to fwdRange. Their documentation starts with "Range-generating function," making them easily searchable.

Parameters:
TP delegate(scope const TP) func The function used to generate the time points of the range over the interval.
PopFirst popFirst Whether popFront should be called on the range before returning it.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Warning
func must be logically pure. Ideally, func would be a function pointer to a pure function, but forcing func to be pure is far too restrictive to be useful, and in order to have the ease of use of having functions which generate functions to pass to fwdRange, func must be a delegate.
If func retains state which changes as it is called, then some algorithms will not work correctly, because the range's save will have failed to have really saved the range's state. To avoid such bugs, don't pass a delegate which is not logically pure to fwdRange. If func is given the same time point with two different calls, it must return the same result both times. Of course, none of the functions in this module have this problem, so it's only relevant if when creating a custom delegate.
Example
auto interval = Interval!Date(Date(2010, 9, 1), Date(2010, 9, 9));
auto func = delegate (scope const Date date) // For iterating over even-numbered days.
            {
                if ((date.day & 1) == 0)
                    return date + dur!"days"(2);

                return date + dur!"days"(1);
            };
auto range = interval.fwdRange(func);

// An odd day. Using PopFirst.yes would have made this Date(2010, 9, 2).
assert(range.front == Date(2010, 9, 1));

range.popFront();
assert(range.front == Date(2010, 9, 2));

range.popFront();
assert(range.front == Date(2010, 9, 4));

range.popFront();
assert(range.front == Date(2010, 9, 6));

range.popFront();
assert(range.front == Date(2010, 9, 8));

range.popFront();
assert(range.empty);
const IntervalRange!(TP, Direction.bwd) bwdRange(TP delegate(scope const TP) func, PopFirst popFirst = PopFirst.no);

Returns a range which iterates backwards over the interval, starting at end, using func to generate each successive time point.

The range's front is the interval's end. func is used to generate the next front when popFront is called. If popFirst is PopFirst.yes, then popFront is called before the range is returned (so that front is a time point which func would generate).

If func ever generates a time point greater than or equal to the current front of the range, then a std.datetime.date.DateTimeException will be thrown. The range will be empty and iteration complete when func generates a time point equal to or less than the begin of the interval.

There are helper functions in this module which generate common delegates to pass to bwdRange. Their documentation starts with "Range-generating function," making them easily searchable.

Parameters:
TP delegate(scope const TP) func The function used to generate the time points of the range over the interval.
PopFirst popFirst Whether popFront should be called on the range before returning it.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Warning
func must be logically pure. Ideally, func would be a function pointer to a pure function, but forcing func to be pure is far too restrictive to be useful, and in order to have the ease of use of having functions which generate functions to pass to fwdRange, func must be a delegate.
If func retains state which changes as it is called, then some algorithms will not work correctly, because the range's save will have failed to have really saved the range's state. To avoid such bugs, don't pass a delegate which is not logically pure to fwdRange. If func is given the same time point with two different calls, it must return the same result both times. Of course, none of the functions in this module have this problem, so it's only relevant for custom delegates.
Example
auto interval = Interval!Date(Date(2010, 9, 1), Date(2010, 9, 9));
auto func = delegate (scope const Date date) // For iterating over even-numbered days.
            {
                if ((date.day & 1) == 0)
                    return date - dur!"days"(2);

                return date - dur!"days"(1);
            };
auto range = interval.bwdRange(func);

// An odd day. Using PopFirst.yes would have made this Date(2010, 9, 8).
assert(range.front == Date(2010, 9, 9));

range.popFront();
assert(range.front == Date(2010, 9, 8));

range.popFront();
assert(range.front == Date(2010, 9, 6));

range.popFront();
assert(range.front == Date(2010, 9, 4));

range.popFront();
assert(range.front == Date(2010, 9, 2));

range.popFront();
assert(range.empty);
const nothrow @safe string toString();

const void toString(Writer)(ref Writer w)
Constraints: if (isOutputRange!(Writer, char));

Converts this interval to a string.

Parameters:
Writer w A char accepting output range
Returns:
A string when not using an output range; void otherwise.
struct PosInfInterval(TP);

Represents an interval of time which has positive infinity as its end point.

Any ranges which iterate over a PosInfInterval are infinite. So, the main purpose of using PosInfInterval is to create an infinite range which starts at a fixed point in time and goes to positive infinity.

pure nothrow this(scope const TP begin);
Parameters:
TP begin The time point which begins the interval.
Example
auto interval = PosInfInterval!Date(Date(1996, 1, 2));
pure nothrow ref PosInfInterval opAssign(ref const PosInfInterval rhs);
Parameters:
PosInfInterval rhs The PosInfInterval to assign to this one.
pure nothrow ref PosInfInterval opAssign(PosInfInterval rhs);
Parameters:
PosInfInterval rhs The PosInfInterval to assign to this one.
const pure nothrow @property TP begin();

The starting point of the interval. It is included in the interval.

Example
assert(PosInfInterval!Date(Date(1996, 1, 2)).begin == Date(1996, 1, 2));
pure nothrow @property void begin(TP timePoint);

The starting point of the interval. It is included in the interval.

Parameters:
TP timePoint The time point to set begin to.
enum bool empty;

Whether the interval's length is 0. Always returns false.

Example
assert(!PosInfInterval!Date(Date(1996, 1, 2)).empty);
const pure nothrow bool contains(TP timePoint);

Whether the given time point is within this interval.

Parameters:
TP timePoint The time point to check for inclusion in this interval.
Example
assert(!PosInfInterval!Date(Date(1996, 1, 2)).contains(Date(1994, 12, 24)));
assert(PosInfInterval!Date(Date(1996, 1, 2)).contains(Date(2000, 1, 5)));
const pure bool contains(scope const Interval!TP interval);

Whether the given interval is completely within this interval.

Parameters:
Interval!TP interval The interval to check for inclusion in this interval.
Throws:
std.datetime.date.DateTimeException if the given interval is empty.
Example
assert(!PosInfInterval!Date(Date(1996, 1, 2)).contains(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))));

assert(PosInfInterval!Date(Date(1996, 1, 2)).contains(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))));

assert(PosInfInterval!Date(Date(1996, 1, 2)).contains(
            Interval!Date(Date(1998, 2, 28), Date(2013, 5, 1))));
const pure nothrow bool contains(scope const PosInfInterval interval);

Whether the given interval is completely within this interval.

Parameters:
PosInfInterval interval The interval to check for inclusion in this interval.
Example
assert(PosInfInterval!Date(Date(1996, 1, 2)).contains(
            PosInfInterval!Date(Date(1999, 5, 4))));

assert(!PosInfInterval!Date(Date(1996, 1, 2)).contains(
            PosInfInterval!Date(Date(1995, 7, 2))));
const pure nothrow bool contains(scope const NegInfInterval!TP interval);

Whether the given interval is completely within this interval.

Always returns false because an interval going to positive infinity can never contain an interval beginning at negative infinity.

Parameters:
NegInfInterval!TP interval The interval to check for inclusion in this interval.
Example
assert(!PosInfInterval!Date(Date(1996, 1, 2)).contains(
            NegInfInterval!Date(Date(1996, 5, 4))));
const pure nothrow bool isBefore(scope const TP timePoint);

Whether this interval is before the given time point.

Always returns false because an interval going to positive infinity can never be before any time point.

Parameters:
TP timePoint The time point to check whether this interval is before it.
Example
assert(!PosInfInterval!Date(Date(1996, 1, 2)).isBefore(Date(1994, 12, 24)));
assert(!PosInfInterval!Date(Date(1996, 1, 2)).isBefore(Date(2000, 1, 5)));
const pure bool isBefore(scope const Interval!TP interval);

Whether this interval is before the given interval and does not intersect it.

Always returns false (unless the given interval is empty) because an interval going to positive infinity can never be before any other interval.

Parameters:
Interval!TP interval The interval to check for against this interval.
Throws:
std.datetime.date.DateTimeException if the given interval is empty.
Example
assert(!PosInfInterval!Date(Date(1996, 1, 2)).isBefore(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))));

assert(!PosInfInterval!Date(Date(1996, 1, 2)).isBefore(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))));
const pure nothrow bool isBefore(scope const PosInfInterval interval);

Whether this interval is before the given interval and does not intersect it.

Always returns false because an interval going to positive infinity can never be before any other interval.

Parameters:
PosInfInterval interval The interval to check for against this interval.
Example
assert(!PosInfInterval!Date(Date(1996, 1, 2)).isBefore(
            PosInfInterval!Date(Date(1992, 5, 4))));

assert(!PosInfInterval!Date(Date(1996, 1, 2)).isBefore(
            PosInfInterval!Date(Date(2013, 3, 7))));
const pure nothrow bool isBefore(scope const NegInfInterval!TP interval);

Whether this interval is before the given interval and does not intersect it.

Always returns false because an interval going to positive infinity can never be before any other interval.

Parameters:
NegInfInterval!TP interval The interval to check for against this interval.
Example
assert(!PosInfInterval!Date(Date(1996, 1, 2)).isBefore(
            NegInfInterval!Date(Date(1996, 5, 4))));
const pure nothrow bool isAfter(scope const TP timePoint);

Whether this interval is after the given time point.

Parameters:
TP timePoint The time point to check whether this interval is after it.
Example
assert(PosInfInterval!Date(Date(1996, 1, 2)).isAfter(Date(1994, 12, 24)));
assert(!PosInfInterval!Date(Date(1996, 1, 2)).isAfter(Date(2000, 1, 5)));
const pure bool isAfter(scope const Interval!TP interval);

Whether this interval is after the given interval and does not intersect it.

Parameters:
Interval!TP interval The interval to check against this interval.
Throws:
std.datetime.date.DateTimeException if the given interval is empty.
Example
assert(!PosInfInterval!Date(Date(1996, 1, 2)).isAfter(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))));

assert(!PosInfInterval!Date(Date(1996, 1, 2)).isAfter(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))));

assert(PosInfInterval!Date(Date(1996, 1, 2)).isAfter(
            Interval!Date(Date(1989, 3, 1), Date(1996, 1, 2))));
const pure nothrow bool isAfter(scope const PosInfInterval interval);

Whether this interval is after the given interval and does not intersect it.

Always returns false because an interval going to positive infinity can never be after another interval going to positive infinity.

Parameters:
PosInfInterval interval The interval to check against this interval.
Example
assert(!PosInfInterval!Date(Date(1996, 1, 2)).isAfter(
            PosInfInterval!Date(Date(1990, 1, 7))));

assert(!PosInfInterval!Date(Date(1996, 1, 2)).isAfter(
            PosInfInterval!Date(Date(1999, 5, 4))));
const pure nothrow bool isAfter(scope const NegInfInterval!TP interval);

Whether this interval is after the given interval and does not intersect it.

Parameters:
NegInfInterval!TP interval The interval to check against this interval.
Example
assert(PosInfInterval!Date(Date(1996, 1, 2)).isAfter(
            NegInfInterval!Date(Date(1996, 1, 2))));

assert(!PosInfInterval!Date(Date(1996, 1, 2)).isAfter(
            NegInfInterval!Date(Date(2000, 7, 1))));
const pure bool intersects(scope const Interval!TP interval);

Whether the given interval overlaps this interval.

Parameters:
Interval!TP interval The interval to check for intersection with this interval.
Throws:
std.datetime.date.DateTimeException if the given interval is empty.
Example
assert(PosInfInterval!Date(Date(1996, 1, 2)).intersects(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))));

assert(PosInfInterval!Date(Date(1996, 1, 2)).intersects(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))));

assert(!PosInfInterval!Date(Date(1996, 1, 2)).intersects(
            Interval!Date(Date(1989, 3, 1), Date(1996, 1, 2))));
const pure nothrow bool intersects(scope const PosInfInterval interval);

Whether the given interval overlaps this interval.

Always returns true because two intervals going to positive infinity always overlap.

Parameters:
PosInfInterval interval The interval to check for intersection with this interval.
Example
assert(PosInfInterval!Date(Date(1996, 1, 2)).intersects(
            PosInfInterval!Date(Date(1990, 1, 7))));

assert(PosInfInterval!Date(Date(1996, 1, 2)).intersects(
            PosInfInterval!Date(Date(1999, 5, 4))));
const pure nothrow bool intersects(scope const NegInfInterval!TP interval);

Whether the given interval overlaps this interval.

Parameters:
NegInfInterval!TP interval The interval to check for intersection with this interval.
Example
assert(!PosInfInterval!Date(Date(1996, 1, 2)).intersects(
            NegInfInterval!Date(Date(1996, 1, 2))));

assert(PosInfInterval!Date(Date(1996, 1, 2)).intersects(
            NegInfInterval!Date(Date(2000, 7, 1))));
const Interval!TP intersection(scope const Interval!TP interval);

Returns the intersection of two intervals

Parameters:
Interval!TP interval The interval to intersect with this interval.
Throws:
std.datetime.date.DateTimeException if the two intervals do not intersect or if the given interval is empty.
Example
assert(PosInfInterval!Date(Date(1996, 1, 2)).intersection(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))) ==
       Interval!Date(Date(1996, 1 , 2), Date(2000, 8, 2)));

assert(PosInfInterval!Date(Date(1996, 1, 2)).intersection(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))) ==
       Interval!Date(Date(1999, 1 , 12), Date(2011, 9, 17)));
const pure nothrow PosInfInterval intersection(scope const PosInfInterval interval);

Returns the intersection of two intervals

Parameters:
PosInfInterval interval The interval to intersect with this interval.
Example
assert(PosInfInterval!Date(Date(1996, 1, 2)).intersection(
            PosInfInterval!Date(Date(1990, 7, 6))) ==
       PosInfInterval!Date(Date(1996, 1 , 2)));

assert(PosInfInterval!Date(Date(1996, 1, 2)).intersection(
            PosInfInterval!Date(Date(1999, 1, 12))) ==
       PosInfInterval!Date(Date(1999, 1 , 12)));
const Interval!TP intersection(scope const NegInfInterval!TP interval);

Returns the intersection of two intervals

Parameters:
NegInfInterval!TP interval The interval to intersect with this interval.
Throws:
std.datetime.date.DateTimeException if the two intervals do not intersect.
Example
assert(PosInfInterval!Date(Date(1996, 1, 2)).intersection(
            NegInfInterval!Date(Date(1999, 7, 6))) ==
       Interval!Date(Date(1996, 1 , 2), Date(1999, 7, 6)));

assert(PosInfInterval!Date(Date(1996, 1, 2)).intersection(
            NegInfInterval!Date(Date(2013, 1, 12))) ==
       Interval!Date(Date(1996, 1 , 2), Date(2013, 1, 12)));
const pure bool isAdjacent(scope const Interval!TP interval);

Whether the given interval is adjacent to this interval.

Parameters:
Interval!TP interval The interval to check whether its adjecent to this interval.
Throws:
std.datetime.date.DateTimeException if the given interval is empty.
Example
assert(PosInfInterval!Date(Date(1996, 1, 2)).isAdjacent(
            Interval!Date(Date(1989, 3, 1), Date(1996, 1, 2))));

assert(!PosInfInterval!Date(Date(1999, 1, 12)).isAdjacent(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))));
const pure nothrow bool isAdjacent(scope const PosInfInterval interval);

Whether the given interval is adjacent to this interval.

Always returns false because two intervals going to positive infinity can never be adjacent to one another.

Parameters:
PosInfInterval interval The interval to check whether its adjecent to this interval.
Example
assert(!PosInfInterval!Date(Date(1996, 1, 2)).isAdjacent(
            PosInfInterval!Date(Date(1990, 1, 7))));

assert(!PosInfInterval!Date(Date(1996, 1, 2)).isAdjacent(
            PosInfInterval!Date(Date(1996, 1, 2))));
const pure nothrow bool isAdjacent(scope const NegInfInterval!TP interval);

Whether the given interval is adjacent to this interval.

Parameters:
NegInfInterval!TP interval The interval to check whether its adjecent to this interval.
Example
assert(PosInfInterval!Date(Date(1996, 1, 2)).isAdjacent(
            NegInfInterval!Date(Date(1996, 1, 2))));

assert(!PosInfInterval!Date(Date(1996, 1, 2)).isAdjacent(
            NegInfInterval!Date(Date(2000, 7, 1))));
const PosInfInterval merge(scope const Interval!TP interval);

Returns the union of two intervals

Parameters:
Interval!TP interval The interval to merge with this interval.
Throws:
std.datetime.date.DateTimeException if the two intervals do not intersect and are not adjacent or if the given interval is empty.
Note
There is no overload for merge which takes a NegInfInterval, because an interval going from negative infinity to positive infinity is not possible.
Example
assert(PosInfInterval!Date(Date(1996, 1, 2)).merge(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))) ==
       PosInfInterval!Date(Date(1990, 7 , 6)));

assert(PosInfInterval!Date(Date(1996, 1, 2)).merge(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))) ==
       PosInfInterval!Date(Date(1996, 1 , 2)));
const pure nothrow PosInfInterval merge(scope const PosInfInterval interval);

Returns the union of two intervals

Parameters:
PosInfInterval interval The interval to merge with this interval.
Note
There is no overload for merge which takes a NegInfInterval, because an interval going from negative infinity to positive infinity is not possible.
Example
assert(PosInfInterval!Date(Date(1996, 1, 2)).merge(
            PosInfInterval!Date(Date(1990, 7, 6))) ==
       PosInfInterval!Date(Date(1990, 7 , 6)));

assert(PosInfInterval!Date(Date(1996, 1, 2)).merge(
            PosInfInterval!Date(Date(1999, 1, 12))) ==
       PosInfInterval!Date(Date(1996, 1 , 2)));
const pure PosInfInterval span(scope const Interval!TP interval);

Returns an interval that covers from the earliest time point of two intervals up to (but not including) the latest time point of two intervals.

Parameters:
Interval!TP interval The interval to create a span together with this interval.
Throws:
std.datetime.date.DateTimeException if the given interval is empty.
Note
There is no overload for span which takes a NegInfInterval, because an interval going from negative infinity to positive infinity is not possible.
Example
assert(PosInfInterval!Date(Date(1996, 1, 2)).span(
            Interval!Date(Date(500, 8, 9), Date(1602, 1, 31))) ==
       PosInfInterval!Date(Date(500, 8, 9)));

assert(PosInfInterval!Date(Date(1996, 1, 2)).span(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))) ==
       PosInfInterval!Date(Date(1990, 7 , 6)));

assert(PosInfInterval!Date(Date(1996, 1, 2)).span(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))) ==
       PosInfInterval!Date(Date(1996, 1 , 2)));
const pure nothrow PosInfInterval span(scope const PosInfInterval interval);

Returns an interval that covers from the earliest time point of two intervals up to (but not including) the latest time point of two intervals.

Parameters:
PosInfInterval interval The interval to create a span together with this interval.
Note
There is no overload for span which takes a NegInfInterval, because an interval going from negative infinity to positive infinity is not possible.
Example
assert(PosInfInterval!Date(Date(1996, 1, 2)).span(
            PosInfInterval!Date(Date(1990, 7, 6))) ==
       PosInfInterval!Date(Date(1990, 7 , 6)));

assert(PosInfInterval!Date(Date(1996, 1, 2)).span(
            PosInfInterval!Date(Date(1999, 1, 12))) ==
       PosInfInterval!Date(Date(1996, 1 , 2)));
pure nothrow void shift(D)(D duration)
Constraints: if (__traits(compiles, begin + duration));

Shifts the begin of this interval forward or backwards in time by the given duration (a positive duration shifts the interval forward; a negative duration shifts it backward). Effectively, it does begin += duration.

Parameters:
D duration The duration to shift the interval by.
Example
auto interval1 = PosInfInterval!Date(Date(1996, 1, 2));
auto interval2 = PosInfInterval!Date(Date(1996, 1, 2));

interval1.shift(dur!"days"(50));
assert(interval1 == PosInfInterval!Date(Date(1996, 2, 21)));

interval2.shift(dur!"days"(-50));
assert(interval2 == PosInfInterval!Date(Date(1995, 11, 13)));
void shift(T)(T years, T months = 0, AllowDayOverflow allowOverflow = AllowDayOverflow.yes)
Constraints: if (isIntegral!T);

Shifts the begin of this interval forward or backwards in time by the given number of years and/or months (a positive number of years and months shifts the interval forward; a negative number shifts it backward). It adds the years the given years and months to begin. It effectively calls add!"years"() and then add!"months"() on begin with the given number of years and months.

Parameters:
T years The number of years to shift the interval by.
T months The number of months to shift the interval by.
AllowDayOverflow allowOverflow Whether the days should be allowed to overflow on begin, causing its month to increment.
Throws:
std.datetime.date.DateTimeException if this interval is empty or if the resulting interval would be invalid.
Example
auto interval1 = PosInfInterval!Date(Date(1996, 1, 2));
auto interval2 = PosInfInterval!Date(Date(1996, 1, 2));

interval1.shift(dur!"days"(50));
assert(interval1 == PosInfInterval!Date(Date(1996, 2, 21)));

interval2.shift(dur!"days"(-50));
assert(interval2 == PosInfInterval!Date(Date(1995, 11, 13)));
pure nothrow void expand(D)(D duration)
Constraints: if (__traits(compiles, begin + duration));

Expands the interval backwards in time. Effectively, it does begin -= duration.

Parameters:
D duration The duration to expand the interval by.
Example
auto interval1 = PosInfInterval!Date(Date(1996, 1, 2));
auto interval2 = PosInfInterval!Date(Date(1996, 1, 2));

interval1.expand(dur!"days"(2));
assert(interval1 == PosInfInterval!Date(Date(1995, 12, 31)));

interval2.expand(dur!"days"(-2));
assert(interval2 == PosInfInterval!Date(Date(1996, 1, 4)));
void expand(T)(T years, T months = 0, AllowDayOverflow allowOverflow = AllowDayOverflow.yes)
Constraints: if (isIntegral!T);

Expands the interval forwards and/or backwards in time. Effectively, it subtracts the given number of months/years from begin.

Parameters:
T years The number of years to expand the interval by.
T months The number of months to expand the interval by.
AllowDayOverflow allowOverflow Whether the days should be allowed to overflow on begin, causing its month to increment.
Throws:
std.datetime.date.DateTimeException if this interval is empty or if the resulting interval would be invalid.
Example
auto interval1 = PosInfInterval!Date(Date(1996, 1, 2));
auto interval2 = PosInfInterval!Date(Date(1996, 1, 2));

interval1.expand(2);
assert(interval1 == PosInfInterval!Date(Date(1994, 1, 2)));

interval2.expand(-2);
assert(interval2 == PosInfInterval!Date(Date(1998, 1, 2)));
const PosInfIntervalRange!TP fwdRange(TP delegate(scope const TP) func, PopFirst popFirst = PopFirst.no);

Returns a range which iterates forward over the interval, starting at begin, using func to generate each successive time point.

The range's front is the interval's begin. func is used to generate the next front when popFront is called. If popFirst is PopFirst.yes, then popFront is called before the range is returned (so that front is a time point which func would generate).

If func ever generates a time point less than or equal to the current front of the range, then a std.datetime.date.DateTimeException will be thrown.

There are helper functions in this module which generate common delegates to pass to fwdRange. Their documentation starts with "Range-generating function," to make them easily searchable.

Parameters:
TP delegate(scope const TP) func The function used to generate the time points of the range over the interval.
PopFirst popFirst Whether popFront should be called on the range before returning it.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Warning
func must be logically pure. Ideally, func would be a function pointer to a pure function, but forcing func to be pure is far too restrictive to be useful, and in order to have the ease of use of having functions which generate functions to pass to fwdRange, func must be a delegate.
If func retains state which changes as it is called, then some algorithms will not work correctly, because the range's save will have failed to have really saved the range's state. To avoid such bugs, don't pass a delegate which is not logically pure to fwdRange. If func is given the same time point with two different calls, it must return the same result both times. Of course, none of the functions in this module have this problem, so it's only relevant for custom delegates.
Example
auto interval = PosInfInterval!Date(Date(2010, 9, 1));
auto func = delegate (scope const Date date) //For iterating over even-numbered days.
            {
                if ((date.day & 1) == 0)
                    return date + dur!"days"(2);

                return date + dur!"days"(1);
            };
auto range = interval.fwdRange(func);

//An odd day. Using PopFirst.yes would have made this Date(2010, 9, 2).
assert(range.front == Date(2010, 9, 1));

range.popFront();
assert(range.front == Date(2010, 9, 2));

range.popFront();
assert(range.front == Date(2010, 9, 4));

range.popFront();
assert(range.front == Date(2010, 9, 6));

range.popFront();
assert(range.front == Date(2010, 9, 8));

range.popFront();
assert(!range.empty);
const nothrow string toString();

Converts this interval to a string.

struct NegInfInterval(TP);

Represents an interval of time which has negative infinity as its starting point.

Any ranges which iterate over a NegInfInterval are infinite. So, the main purpose of using NegInfInterval is to create an infinite range which starts at negative infinity and goes to a fixed end point. Iterate over it in reverse.

pure nothrow this(scope const TP end);
Parameters:
TP end The time point which ends the interval.
Example
auto interval = PosInfInterval!Date(Date(1996, 1, 2));
pure nothrow ref NegInfInterval opAssign(ref const NegInfInterval rhs);
Parameters:
NegInfInterval rhs The NegInfInterval to assign to this one.
pure nothrow ref NegInfInterval opAssign(NegInfInterval rhs);
Parameters:
NegInfInterval rhs The NegInfInterval to assign to this one.
const pure nothrow @property TP end();

The end point of the interval. It is excluded from the interval.

Example
assert(NegInfInterval!Date(Date(2012, 3, 1)).end == Date(2012, 3, 1));
pure nothrow @property void end(TP timePoint);

The end point of the interval. It is excluded from the interval.

Parameters:
TP timePoint The time point to set end to.
enum bool empty;

Whether the interval's length is 0. Always returns false.

Example
assert(!NegInfInterval!Date(Date(1996, 1, 2)).empty);
const pure nothrow bool contains(TP timePoint);

Whether the given time point is within this interval.

Parameters:
TP timePoint The time point to check for inclusion in this interval.
Example
assert(NegInfInterval!Date(Date(2012, 3, 1)).contains(Date(1994, 12, 24)));
assert(NegInfInterval!Date(Date(2012, 3, 1)).contains(Date(2000, 1, 5)));
assert(!NegInfInterval!Date(Date(2012, 3, 1)).contains(Date(2012, 3, 1)));
const pure bool contains(scope const Interval!TP interval);

Whether the given interval is completely within this interval.

Parameters:
Interval!TP interval The interval to check for inclusion in this interval.
Throws:
std.datetime.date.DateTimeException if the given interval is empty.
Example
assert(NegInfInterval!Date(Date(2012, 3, 1)).contains(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))));

assert(NegInfInterval!Date(Date(2012, 3, 1)).contains(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))));

assert(!NegInfInterval!Date(Date(2012, 3, 1)).contains(
            Interval!Date(Date(1998, 2, 28), Date(2013, 5, 1))));
const pure nothrow bool contains(scope const PosInfInterval!TP interval);

Whether the given interval is completely within this interval.

Always returns false because an interval beginning at negative infinity can never contain an interval going to positive infinity.

Parameters:
PosInfInterval!TP interval The interval to check for inclusion in this interval.
Example
assert(!NegInfInterval!Date(Date(2012, 3, 1)).contains(
            PosInfInterval!Date(Date(1999, 5, 4))));
const pure nothrow bool contains(scope const NegInfInterval interval);

Whether the given interval is completely within this interval.

Parameters:
NegInfInterval interval The interval to check for inclusion in this interval.
Example
assert(NegInfInterval!Date(Date(2012, 3, 1)).contains(
            NegInfInterval!Date(Date(1996, 5, 4))));

assert(!NegInfInterval!Date(Date(2012, 3, 1)).contains(
            NegInfInterval!Date(Date(2013, 7, 9))));
const pure nothrow bool isBefore(scope const TP timePoint);

Whether this interval is before the given time point.

Parameters:
TP timePoint The time point to check whether this interval is before it.
Example
assert(!NegInfInterval!Date(Date(2012, 3, 1)).isBefore(Date(1994, 12, 24)));
assert(!NegInfInterval!Date(Date(2012, 3, 1)).isBefore(Date(2000, 1, 5)));
assert(NegInfInterval!Date(Date(2012, 3, 1)).isBefore(Date(2012, 3, 1)));
const pure bool isBefore(scope const Interval!TP interval);

Whether this interval is before the given interval and does not intersect it.

Parameters:
Interval!TP interval The interval to check for against this interval.
Throws:
std.datetime.date.DateTimeException if the given interval is empty
Example
assert(!NegInfInterval!Date(Date(2012, 3, 1)).isBefore(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))));

assert(!NegInfInterval!Date(Date(2012, 3, 1)).isBefore(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))));

assert(NegInfInterval!Date(Date(2012, 3, 1)).isBefore(
            Interval!Date(Date(2022, 10, 19), Date(2027, 6, 3))));
const pure nothrow bool isBefore(scope const PosInfInterval!TP interval);

Whether this interval is before the given interval and does not intersect it.

Parameters:
PosInfInterval!TP interval The interval to check for against this interval.
Example
assert(!NegInfInterval!Date(Date(2012, 3, 1)).isBefore(
            PosInfInterval!Date(Date(1999, 5, 4))));

assert(NegInfInterval!Date(Date(2012, 3, 1)).isBefore(
            PosInfInterval!Date(Date(2012, 3, 1))));
const pure nothrow bool isBefore(scope const NegInfInterval interval);

Whether this interval is before the given interval and does not intersect it.

Always returns false because an interval beginning at negative infinity can never be before another interval beginning at negative infinity.

Parameters:
NegInfInterval interval The interval to check for against this interval.
Example
assert(!NegInfInterval!Date(Date(2012, 3, 1)).isBefore(
            NegInfInterval!Date(Date(1996, 5, 4))));

assert(!NegInfInterval!Date(Date(2012, 3, 1)).isBefore(
            NegInfInterval!Date(Date(2013, 7, 9))));
const pure nothrow bool isAfter(scope const TP timePoint);

Whether this interval is after the given time point.

Always returns false because an interval beginning at negative infinity can never be after any time point.

Parameters:
TP timePoint The time point to check whether this interval is after it.
Example
assert(!NegInfInterval!Date(Date(2012, 3, 1)).isAfter(Date(1994, 12, 24)));
assert(!NegInfInterval!Date(Date(2012, 3, 1)).isAfter(Date(2000, 1, 5)));
assert(!NegInfInterval!Date(Date(2012, 3, 1)).isAfter(Date(2012, 3, 1)));
const pure bool isAfter(scope const Interval!TP interval);

Whether this interval is after the given interval and does not intersect it.

Always returns false (unless the given interval is empty) because an interval beginning at negative infinity can never be after any other interval.

Parameters:
Interval!TP interval The interval to check against this interval.
Throws:
std.datetime.date.DateTimeException if the given interval is empty.
Example
assert(!NegInfInterval!Date(Date(2012, 3, 1)).isAfter(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))));

assert(!NegInfInterval!Date(Date(2012, 3, 1)).isAfter(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))));

assert(!NegInfInterval!Date(Date(2012, 3, 1)).isAfter(
            Interval!Date(Date(2022, 10, 19), Date(2027, 6, 3))));
const pure nothrow bool isAfter(scope const PosInfInterval!TP interval);

Whether this interval is after the given interval and does not intersect it.

Always returns false because an interval beginning at negative infinity can never be after any other interval.

Parameters:
PosInfInterval!TP interval The interval to check against this interval.
Example
assert(!NegInfInterval!Date(Date(2012, 3, 1)).isAfter(
            PosInfInterval!Date(Date(1999, 5, 4))));

assert(!NegInfInterval!Date(Date(2012, 3, 1)).isAfter(
            PosInfInterval!Date(Date(2012, 3, 1))));
const pure nothrow bool isAfter(scope const NegInfInterval interval);

Whether this interval is after the given interval and does not intersect it.

Always returns false because an interval beginning at negative infinity can never be after any other interval.

Parameters:
NegInfInterval interval The interval to check against this interval.
Example
assert(!NegInfInterval!Date(Date(2012, 3, 1)).isAfter(
            NegInfInterval!Date(Date(1996, 5, 4))));

assert(!NegInfInterval!Date(Date(2012, 3, 1)).isAfter(
            NegInfInterval!Date(Date(2013, 7, 9))));
const pure bool intersects(scope const Interval!TP interval);

Whether the given interval overlaps this interval.

Parameters:
Interval!TP interval The interval to check for intersection with this interval.
Throws:
std.datetime.date.DateTimeException if the given interval is empty.
Example
assert(NegInfInterval!Date(Date(2012, 3, 1)).intersects(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))));

assert(NegInfInterval!Date(Date(2012, 3, 1)).intersects(
            Interval!Date(Date(1999, 1, 12), Date(2011, 9, 17))));

assert(!NegInfInterval!Date(Date(2012, 3, 1)).intersects(
            Interval!Date(Date(2022, 10, 19), Date(2027, 6, 3))));
const pure nothrow bool intersects(scope const PosInfInterval!TP interval);

Whether the given interval overlaps this interval.

Parameters:
PosInfInterval!TP interval The interval to check for intersection with this interval.
Example
assert(NegInfInterval!Date(Date(2012, 3, 1)).intersects(
            PosInfInterval!Date(Date(1999, 5, 4))));

assert(!NegInfInterval!Date(Date(2012, 3, 1)).intersects(
            PosInfInterval!Date(Date(2012, 3, 1))));
const pure nothrow bool intersects(scope const NegInfInterval!TP interval);

Whether the given interval overlaps this interval.

Always returns true because two intervals beginning at negative infinity always overlap.

Parameters:
NegInfInterval!TP interval The interval to check for intersection with this interval.
Example
assert(NegInfInterval!Date(Date(2012, 3, 1)).intersects(
            NegInfInterval!Date(Date(1996, 5, 4))));

assert(NegInfInterval!Date(Date(2012, 3, 1)).intersects(
            NegInfInterval!Date(Date(2013, 7, 9))));
const Interval!TP intersection(scope const Interval!TP interval);

Returns the intersection of two intervals

Parameters:
Interval!TP interval The interval to intersect with this interval.
Throws:
std.datetime.date.DateTimeException if the two intervals do not intersect or if the given interval is empty.
Example
assert(NegInfInterval!Date(Date(2012, 3, 1)).intersection(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))) ==
       Interval!Date(Date(1990, 7 , 6), Date(2000, 8, 2)));

assert(NegInfInterval!Date(Date(2012, 3, 1)).intersection(
            Interval!Date(Date(1999, 1, 12), Date(2015, 9, 2))) ==
       Interval!Date(Date(1999, 1 , 12), Date(2012, 3, 1)));
const Interval!TP intersection(scope const PosInfInterval!TP interval);

Returns the intersection of two intervals

Parameters:
PosInfInterval!TP interval The interval to intersect with this interval.
Throws:
std.datetime.date.DateTimeException if the two intervals do not intersect.
Example
assert(NegInfInterval!Date(Date(2012, 3, 1)).intersection(
            PosInfInterval!Date(Date(1990, 7, 6))) ==
       Interval!Date(Date(1990, 7 , 6), Date(2012, 3, 1)));

assert(NegInfInterval!Date(Date(2012, 3, 1)).intersection(
            PosInfInterval!Date(Date(1999, 1, 12))) ==
       Interval!Date(Date(1999, 1 , 12), Date(2012, 3, 1)));
const nothrow NegInfInterval intersection(scope const NegInfInterval interval);

Returns the intersection of two intervals

Parameters:
NegInfInterval interval The interval to intersect with this interval.
Example
assert(NegInfInterval!Date(Date(2012, 3, 1)).intersection(
            NegInfInterval!Date(Date(1999, 7, 6))) ==
       NegInfInterval!Date(Date(1999, 7 , 6)));

assert(NegInfInterval!Date(Date(2012, 3, 1)).intersection(
            NegInfInterval!Date(Date(2013, 1, 12))) ==
       NegInfInterval!Date(Date(2012, 3 , 1)));
const pure bool isAdjacent(scope const Interval!TP interval);

Whether the given interval is adjacent to this interval.

Parameters:
Interval!TP interval The interval to check whether its adjecent to this interval.
Throws:
std.datetime.date.DateTimeException if the given interval is empty.
Example
assert(!NegInfInterval!Date(Date(2012, 3, 1)).isAdjacent(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))));

assert(!NegInfInterval!Date(Date(2012, 3, 1)).isAdjacent(
            Interval!Date(Date(1999, 1, 12), Date(2012, 3, 1))));

assert(NegInfInterval!Date(Date(2012, 3, 1)).isAdjacent(
            Interval!Date(Date(2012, 3, 1), Date(2019, 2, 2))));

assert(!NegInfInterval!Date(Date(2012, 3, 1)).isAdjacent(
            Interval!Date(Date(2022, 10, 19), Date(2027, 6, 3))));
const pure nothrow bool isAdjacent(scope const PosInfInterval!TP interval);

Whether the given interval is adjacent to this interval.

Parameters:
PosInfInterval!TP interval The interval to check whether its adjecent to this interval.
Example
assert(!NegInfInterval!Date(Date(2012, 3, 1)).isAdjacent(
            PosInfInterval!Date(Date(1999, 5, 4))));

assert(NegInfInterval!Date(Date(2012, 3, 1)).isAdjacent(
            PosInfInterval!Date(Date(2012, 3, 1))));
const pure nothrow bool isAdjacent(scope const NegInfInterval interval);

Whether the given interval is adjacent to this interval.

Always returns false because two intervals beginning at negative infinity can never be adjacent to one another.

Parameters:
NegInfInterval interval The interval to check whether its adjecent to this interval.
Example
assert(!NegInfInterval!Date(Date(2012, 3, 1)).isAdjacent(
            NegInfInterval!Date(Date(1996, 5, 4))));

assert(!NegInfInterval!Date(Date(2012, 3, 1)).isAdjacent(
            NegInfInterval!Date(Date(2012, 3, 1))));
const NegInfInterval merge(scope const Interval!TP interval);

Returns the union of two intervals

Parameters:
Interval!TP interval The interval to merge with this interval.
Throws:
std.datetime.date.DateTimeException if the two intervals do not intersect and are not adjacent or if the given interval is empty.
Note
There is no overload for merge which takes a PosInfInterval, because an interval going from negative infinity to positive infinity is not possible.
Example
assert(NegInfInterval!Date(Date(2012, 3, 1)).merge(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))) ==
       NegInfInterval!Date(Date(2012, 3 , 1)));

assert(NegInfInterval!Date(Date(2012, 3, 1)).merge(
            Interval!Date(Date(1999, 1, 12), Date(2015, 9, 2))) ==
       NegInfInterval!Date(Date(2015, 9 , 2)));
const pure nothrow NegInfInterval merge(scope const NegInfInterval interval);

Returns the union of two intervals

Parameters:
NegInfInterval interval The interval to merge with this interval.
Note
There is no overload for merge which takes a PosInfInterval, because an interval going from negative infinity to positive infinity is not possible.
Example
assert(NegInfInterval!Date(Date(2012, 3, 1)).merge(
            NegInfInterval!Date(Date(1999, 7, 6))) ==
       NegInfInterval!Date(Date(2012, 3 , 1)));

assert(NegInfInterval!Date(Date(2012, 3, 1)).merge(
            NegInfInterval!Date(Date(2013, 1, 12))) ==
       NegInfInterval!Date(Date(2013, 1 , 12)));
const pure NegInfInterval span(scope const Interval!TP interval);

Returns an interval that covers from the earliest time point of two intervals up to (but not including) the latest time point of two intervals.

Parameters:
Interval!TP interval The interval to create a span together with this interval.
Throws:
std.datetime.date.DateTimeException if the given interval is empty.
Note
There is no overload for span which takes a PosInfInterval, because an interval going from negative infinity to positive infinity is not possible.
Example
assert(NegInfInterval!Date(Date(2012, 3, 1)).span(
            Interval!Date(Date(1990, 7, 6), Date(2000, 8, 2))) ==
       NegInfInterval!Date(Date(2012, 3 , 1)));

assert(NegInfInterval!Date(Date(2012, 3, 1)).span(
            Interval!Date(Date(1999, 1, 12), Date(2015, 9, 2))) ==
       NegInfInterval!Date(Date(2015, 9 , 2)));

assert(NegInfInterval!Date(Date(1600, 1, 7)).span(
            Interval!Date(Date(2012, 3, 11), Date(2017, 7, 1))) ==
       NegInfInterval!Date(Date(2017, 7 , 1)));
const pure nothrow NegInfInterval span(scope const NegInfInterval interval);

Returns an interval that covers from the earliest time point of two intervals up to (but not including) the latest time point of two intervals.

Parameters:
NegInfInterval interval The interval to create a span together with this interval.
Note
There is no overload for span which takes a PosInfInterval, because an interval going from negative infinity to positive infinity is not possible.
Example
assert(NegInfInterval!Date(Date(2012, 3, 1)).span(
            NegInfInterval!Date(Date(1999, 7, 6))) ==
       NegInfInterval!Date(Date(2012, 3 , 1)));

assert(NegInfInterval!Date(Date(2012, 3, 1)).span(
            NegInfInterval!Date(Date(2013, 1, 12))) ==
       NegInfInterval!Date(Date(2013, 1 , 12)));
pure nothrow void shift(D)(D duration)
Constraints: if (__traits(compiles, end + duration));

Shifts the end of this interval forward or backwards in time by the given duration (a positive duration shifts the interval forward; a negative duration shifts it backward). Effectively, it does end += duration.

Parameters:
D duration The duration to shift the interval by.
Example
auto interval1 = NegInfInterval!Date(Date(2012, 4, 5));
auto interval2 = NegInfInterval!Date(Date(2012, 4, 5));

interval1.shift(dur!"days"(50));
assert(interval1 == NegInfInterval!Date(Date(2012, 5, 25)));

interval2.shift(dur!"days"(-50));
assert(interval2 == NegInfInterval!Date( Date(2012, 2, 15)));
void shift(T)(T years, T months = 0, AllowDayOverflow allowOverflow = AllowDayOverflow.yes)
Constraints: if (isIntegral!T);

Shifts the end of this interval forward or backwards in time by the given number of years and/or months (a positive number of years and months shifts the interval forward; a negative number shifts it backward). It adds the years the given years and months to end. It effectively calls add!"years"() and then add!"months"() on end with the given number of years and months.

Parameters:
T years The number of years to shift the interval by.
T months The number of months to shift the interval by.
AllowDayOverflow allowOverflow Whether the days should be allowed to overflow on end, causing its month to increment.
Throws:
std.datetime.date.DateTimeException if empty is true or if the resulting interval would be invalid.
Example
auto interval1 = NegInfInterval!Date(Date(2012, 3, 1));
auto interval2 = NegInfInterval!Date(Date(2012, 3, 1));

interval1.shift(2);
assert(interval1 == NegInfInterval!Date(Date(2014, 3, 1)));

interval2.shift(-2);
assert(interval2 == NegInfInterval!Date(Date(2010, 3, 1)));
pure nothrow void expand(D)(D duration)
Constraints: if (__traits(compiles, end + duration));

Expands the interval forwards in time. Effectively, it does end += duration.

Parameters:
D duration The duration to expand the interval by.
Example
auto interval1 = NegInfInterval!Date(Date(2012, 3, 1));
auto interval2 = NegInfInterval!Date(Date(2012, 3, 1));

interval1.expand(dur!"days"(2));
assert(interval1 == NegInfInterval!Date(Date(2012, 3, 3)));

interval2.expand(dur!"days"(-2));
assert(interval2 == NegInfInterval!Date(Date(2012, 2, 28)));
void expand(T)(T years, T months = 0, AllowDayOverflow allowOverflow = AllowDayOverflow.yes)
Constraints: if (isIntegral!T);

Expands the interval forwards and/or backwards in time. Effectively, it adds the given number of months/years to end.

Parameters:
T years The number of years to expand the interval by.
T months The number of months to expand the interval by.
AllowDayOverflow allowOverflow Whether the days should be allowed to overflow on end, causing their month to increment.
Throws:
std.datetime.date.DateTimeException if empty is true or if the resulting interval would be invalid.
Example
auto interval1 = NegInfInterval!Date(Date(2012, 3, 1));
auto interval2 = NegInfInterval!Date(Date(2012, 3, 1));

interval1.expand(2);
assert(interval1 == NegInfInterval!Date(Date(2014, 3, 1)));

interval2.expand(-2);
assert(interval2 == NegInfInterval!Date(Date(2010, 3, 1)));
const NegInfIntervalRange!TP bwdRange(TP delegate(scope const TP) func, PopFirst popFirst = PopFirst.no);

Returns a range which iterates backwards over the interval, starting at end, using func to generate each successive time point.

The range's front is the interval's end. func is used to generate the next front when popFront is called. If popFirst is PopFirst.yes, then popFront is called before the range is returned (so that front is a time point which func would generate).

If func ever generates a time point greater than or equal to the current front of the range, then a std.datetime.date.DateTimeException will be thrown.

There are helper functions in this module which generate common delegates to pass to bwdRange. Their documentation starts with "Range-generating function," to make them easily searchable.

Parameters:
TP delegate(scope const TP) func The function used to generate the time points of the range over the interval.
PopFirst popFirst Whether popFront should be called on the range before returning it.
Throws:
std.datetime.date.DateTimeException if this interval is empty.
Warning
func must be logically pure. Ideally, func would be a function pointer to a pure function, but forcing func to be pure is far too restrictive to be useful, and in order to have the ease of use of having functions which generate functions to pass to fwdRange, func must be a delegate.
If func retains state which changes as it is called, then some algorithms will not work correctly, because the range's save will have failed to have really saved the range's state. To avoid such bugs, don't pass a delegate which is not logically pure to fwdRange. If func is given the same time point with two different calls, it must return the same result both times. Of course, none of the functions in this module have this problem, so it's only relevant for custom delegates.
Example
auto interval = NegInfInterval!Date(Date(2010, 9, 9));
auto func = delegate (scope const Date date) //For iterating over even-numbered days.
            {
                if ((date.day & 1) == 0)
                    return date - dur!"days"(2);

                return date - dur!"days"(1);
            };
auto range = interval.bwdRange(func);

assert(range.front == Date(2010, 9, 9)); //An odd day. Using PopFirst.yes would have made this Date(2010, 9, 8).

range.popFront();
assert(range.front == Date(2010, 9, 8));

range.popFront();
assert(range.front == Date(2010, 9, 6));

range.popFront();
assert(range.front == Date(2010, 9, 4));

range.popFront();
assert(range.front == Date(2010, 9, 2));

range.popFront();
assert(!range.empty);
const nothrow string toString();

Converts this interval to a string.

nothrow TP delegate(scope const TP) everyDayOfWeek(TP, Direction dir = Direction.fwd)(DayOfWeek dayOfWeek)
Constraints: if (isTimePoint!TP && (dir == Direction.fwd || dir == Direction.bwd) && __traits(hasMember, TP, "dayOfWeek") && !__traits(isStaticFunction, TP.dayOfWeek) && is(typeof(TP.dayOfWeek) == DayOfWeek));

Range-generating function.

Returns a delegate which returns the next time point with the given DayOfWeek in a range.

Using this delegate allows iteration over successive time points which are all the same day of the week. e.g. passing DayOfWeek.mon to everyDayOfWeek would result in a delegate which could be used to iterate over all of the Mondays in a range.

Parameters:
dir The direction to iterate in. If passing the return value to fwdRange, use Direction.fwd. If passing it to bwdRange, use Direction.bwd.
DayOfWeek dayOfWeek The week that each time point in the range will be.
Examples:
import std.datetime.date : Date, DayOfWeek;

auto interval = Interval!Date(Date(2010, 9, 2), Date(2010, 9, 27));
auto func = everyDayOfWeek!Date(DayOfWeek.mon);
auto range = interval.fwdRange(func);

// A Thursday. Using PopFirst.yes would have made this Date(2010, 9, 6).
writeln(range.front); // Date(2010, 9, 2)

range.popFront();
writeln(range.front); // Date(2010, 9, 6)

range.popFront();
writeln(range.front); // Date(2010, 9, 13)

range.popFront();
writeln(range.front); // Date(2010, 9, 20)

range.popFront();
assert(range.empty);
TP delegate(scope const TP) everyMonth(TP, Direction dir = Direction.fwd)(int month)
Constraints: if (isTimePoint!TP && (dir == Direction.fwd || dir == Direction.bwd) && __traits(hasMember, TP, "month") && !__traits(isStaticFunction, TP.month) && is(typeof(TP.month) == Month));

Range-generating function.

Returns a delegate which returns the next time point with the given month which would be reached by adding months to the given time point.

So, using this delegate allows iteration over successive time points which are in the same month but different years. For example, iterate over each successive December 25th in an interval by starting with a date which had the 25th as its day and passed Month.dec to everyMonth to create the delegate.

Since it wouldn't really make sense to be iterating over a specific month and end up with some of the time points in the succeeding month or two years after the previous time point, AllowDayOverflow.no is always used when calculating the next time point.

Parameters:
dir The direction to iterate in. If passing the return value to fwdRange, use Direction.fwd. If passing it to bwdRange, use Direction.bwd.
int month The month that each time point in the range will be in (January is 1).
Examples:
import std.datetime.date : Date, Month;

auto interval = Interval!Date(Date(2000, 1, 30), Date(2004, 8, 5));
auto func = everyMonth!Date(Month.feb);
auto range = interval.fwdRange(func);

// Using PopFirst.yes would have made this Date(2010, 2, 29).
writeln(range.front); // Date(2000, 1, 30)

range.popFront();
writeln(range.front); // Date(2000, 2, 29)

range.popFront();
writeln(range.front); // Date(2001, 2, 28)

range.popFront();
writeln(range.front); // Date(2002, 2, 28)

range.popFront();
writeln(range.front); // Date(2003, 2, 28)

range.popFront();
writeln(range.front); // Date(2004, 2, 28)

range.popFront();
assert(range.empty);
nothrow TP delegate(scope const TP) everyDuration(TP, Direction dir = Direction.fwd, D)(D duration)
Constraints: if (isTimePoint!TP && __traits(compiles, TP.init + duration) && (dir == Direction.fwd || dir == Direction.bwd));

Range-generating function.

Returns a delegate which returns the next time point which is the given duration later.

Using this delegate allows iteration over successive time points which are apart by the given duration e.g. passing dur!"days"(3) to everyDuration would result in a delegate which could be used to iterate over a range of days which are each 3 days apart.

Parameters:
dir The direction to iterate in. If passing the return value to fwdRange, use Direction.fwd. If passing it to bwdRange, use Direction.bwd.
D duration The duration which separates each successive time point in the range.
Examples:
import core.time : dur;
import std.datetime.date : Date;

auto interval = Interval!Date(Date(2010, 9, 2), Date(2010, 9, 27));
auto func = everyDuration!Date(dur!"days"(8));
auto range = interval.fwdRange(func);

// Using PopFirst.yes would have made this Date(2010, 9, 10).
writeln(range.front); // Date(2010, 9, 2)

range.popFront();
writeln(range.front); // Date(2010, 9, 10)

range.popFront();
writeln(range.front); // Date(2010, 9, 18)

range.popFront();
writeln(range.front); // Date(2010, 9, 26)

range.popFront();
assert(range.empty);
nothrow TP delegate(scope const TP) everyDuration(TP, Direction dir = Direction.fwd, D)(int years, int months = 0, AllowDayOverflow allowOverflow = AllowDayOverflow.yes, D duration = dur!"days"(0))
Constraints: if (isTimePoint!TP && __traits(compiles, TP.init + duration) && __traits(compiles, TP.init.add!"years"(years)) && __traits(compiles, TP.init.add!"months"(months)) && (dir == Direction.fwd || dir == Direction.bwd));

Range-generating function.

Returns a delegate which returns the next time point which is the given number of years, month, and duration later.

The difference between this version of everyDuration and the version which just takes a core.time.Duration is that this one also takes the number of years and months (along with an AllowDayOverflow to indicate whether adding years and months should allow the days to overflow).

Note that if iterating forward, add!"years"() is called on the given time point, then add!"months"(), and finally the duration is added to it. However, if iterating backwards, the duration is added first, then add!"months"() is called, and finally add!"years"() is called. That way, going backwards generates close to the same time points that iterating forward does, but since adding years and months is not entirely reversible (due to possible day overflow, regardless of whether AllowDayOverflow.yes or AllowDayOverflow.no is used), it can't be guaranteed that iterating backwards will give the same time points as iterating forward would have (even assuming that the end of the range is a time point which would be returned by the delegate when iterating forward from begin).

Parameters:
dir The direction to iterate in. If passing the return value to fwdRange, use Direction.fwd. If passing it to bwdRange, use Direction.bwd.
int years The number of years to add to the time point passed to the delegate.
int months The number of months to add to the time point passed to the delegate.
AllowDayOverflow allowOverflow Whether the days should be allowed to overflow on begin and end, causing their month to increment.
D duration The duration to add to the time point passed to the delegate.
Examples:
import core.time : dur;
import std.datetime.date : AllowDayOverflow, Date;

auto interval = Interval!Date(Date(2010, 9, 2), Date(2025, 9, 27));
auto func = everyDuration!Date(4, 1, AllowDayOverflow.yes, dur!"days"(2));
auto range = interval.fwdRange(func);

// Using PopFirst.yes would have made this Date(2014, 10, 12).
writeln(range.front); // Date(2010, 9, 2)

range.popFront();
writeln(range.front); // Date(2014, 10, 4)

range.popFront();
writeln(range.front); // Date(2018, 11, 6)

range.popFront();
writeln(range.front); // Date(2022, 12, 8)

range.popFront();
assert(range.empty);
struct IntervalRange(TP, Direction dir) if (isTimePoint!TP && (dir != Direction.both));

A range over an Interval.

IntervalRange is only ever constructed by Interval. However, when it is constructed, it is given a function, func, which is used to generate the time points which are iterated over. func takes a time point and returns a time point of the same type. For instance, to iterate over all of the days in the interval Interval!Date, pass a function to Interval's fwdRange where that function took a std.datetime.date.Date and returned a std.datetime.date.Date which was one day later. That function would then be used by IntervalRange's popFront to iterate over the std.datetime.date.Dates in the interval.

If dir == Direction.fwd, then a range iterates forward in time, whereas if dir == Direction.bwd, then it iterates backwards in time. So, if dir == Direction.fwd then front == interval.begin, whereas if dir == Direction.bwd then front == interval.end. func must generate a time point going in the proper direction of iteration, or a std.datetime.date.DateTimeException will be thrown. So, to iterate forward in time, the time point that func generates must be later in time than the one passed to it. If it's either identical or earlier in time, then a std.datetime.date.DateTimeException will be thrown. To iterate backwards, then the generated time point must be before the time point which was passed in.

If the generated time point is ever passed the edge of the range in the proper direction, then the edge of that range will be used instead. So, if iterating forward, and the generated time point is past the interval's end, then front becomes end. If iterating backwards, and the generated time point is before begin, then front becomes begin. In either case, the range would then be empty.

Also note that while normally the begin of an interval is included in it and its end is excluded from it, if dir == Direction.bwd, then begin is treated as excluded and end is treated as included. This allows for the same behavior in both directions. This works because none of Interval's functions which care about whether begin or end is included or excluded are ever called by IntervalRange. interval returns a normal interval, regardless of whether dir == Direction.fwd or if dir == Direction.bwd, so any Interval functions which are called on it which care about whether begin or end are included or excluded will treat begin as included and end as excluded.

pure nothrow ref IntervalRange opAssign(ref IntervalRange rhs);

pure nothrow ref IntervalRange opAssign(IntervalRange rhs);
Parameters:
IntervalRange rhs The IntervalRange to assign to this one.
const pure nothrow @property bool empty();

Whether this IntervalRange is empty.

const pure @property TP front();

The first time point in the range.

Throws:
std.datetime.date.DateTimeException if the range is empty.
void popFront();

Pops front from the range, using func to generate the next time point in the range. If the generated time point is beyond the edge of the range, then front is set to that edge, and the range is then empty. So, if iterating forwards, and the generated time point is greater than the interval's end, then front is set to end. If iterating backwards, and the generated time point is less than the interval's begin, then front is set to begin.

Throws:
std.datetime.date.DateTimeException if the range is empty or if the generated time point is in the wrong direction (i.e. if iterating forward and the generated time point is before front, or if iterating backwards and the generated time point is after front).
pure nothrow @property IntervalRange save();

Returns a copy of this.

const pure nothrow @property Interval!TP interval();

The interval that this IntervalRange currently covers.

pure nothrow @property TP delegate(scope const TP) func();

The function used to generate the next time point in the range.

const pure nothrow @property Direction direction();

The Direction that this range iterates in.

struct PosInfIntervalRange(TP) if (isTimePoint!TP);

A range over a PosInfInterval. It is an infinite range.

PosInfIntervalRange is only ever constructed by PosInfInterval. However, when it is constructed, it is given a function, func, which is used to generate the time points which are iterated over. func takes a time point and returns a time point of the same type. For instance, to iterate over all of the days in the interval PosInfInterval!Date, pass a function to PosInfInterval's fwdRange where that function took a std.datetime.date.Date and returned a std.datetime.date.Date which was one day later. That function would then be used by PosInfIntervalRange's popFront to iterate over the std.datetime.date.Dates in the interval - though obviously, since the range is infinite, use a function such as std.range.take with it rather than iterating over all of the dates.

As the interval goes to positive infinity, the range is always iterated over forwards, never backwards. func must generate a time point going in the proper direction of iteration, or a std.datetime.date.DateTimeException will be thrown. So, the time points that func generates must be later in time than the one passed to it. If it's either identical or earlier in time, then a std.datetime.date.DateTimeException will be thrown.

pure nothrow ref PosInfIntervalRange opAssign(ref PosInfIntervalRange rhs);

pure nothrow ref PosInfIntervalRange opAssign(PosInfIntervalRange rhs);
Parameters:
PosInfIntervalRange rhs The PosInfIntervalRange to assign to this one.
enum bool empty;

This is an infinite range, so it is never empty.

const pure nothrow @property TP front();

The first time point in the range.

void popFront();

Pops front from the range, using func to generate the next time point in the range.

Throws:
std.datetime.date.DateTimeException if the generated time point is less than front.
pure nothrow @property PosInfIntervalRange save();

Returns a copy of this.

const pure nothrow @property PosInfInterval!TP interval();

The interval that this range currently covers.

pure nothrow @property TP delegate(scope const TP) func();

The function used to generate the next time point in the range.

struct NegInfIntervalRange(TP) if (isTimePoint!TP);

A range over a NegInfInterval. It is an infinite range.

NegInfIntervalRange is only ever constructed by NegInfInterval. However, when it is constructed, it is given a function, func, which is used to generate the time points which are iterated over. func takes a time point and returns a time point of the same type. For instance, to iterate over all of the days in the interval NegInfInterval!Date, pass a function to NegInfInterval's bwdRange where that function took a std.datetime.date.Date and returned a std.datetime.date.Date which was one day earlier. That function would then be used by NegInfIntervalRange's popFront to iterate over the std.datetime.date.Dates in the interval - though obviously, since the range is infinite, use a function such as std.range.take with it rather than iterating over all of the dates.

As the interval goes to negative infinity, the range is always iterated over backwards, never forwards. func must generate a time point going in the proper direction of iteration, or a std.datetime.date.DateTimeException will be thrown. So, the time points that func generates must be earlier in time than the one passed to it. If it's either identical or later in time, then a std.datetime.date.DateTimeException will be thrown.

Also note that while normally the end of an interval is excluded from it, NegInfIntervalRange treats it as if it were included. This allows for the same behavior as with PosInfIntervalRange. This works because none of NegInfInterval's functions which care about whether end is included or excluded are ever called by NegInfIntervalRange. interval returns a normal interval, so any NegInfInterval functions which are called on it which care about whether end is included or excluded will treat end as excluded.

pure nothrow ref NegInfIntervalRange opAssign(ref NegInfIntervalRange rhs);

pure nothrow ref NegInfIntervalRange opAssign(NegInfIntervalRange rhs);
Parameters:
NegInfIntervalRange rhs The NegInfIntervalRange to assign to this one.
enum bool empty;

This is an infinite range, so it is never empty.

const pure nothrow @property TP front();

The first time point in the range.

void popFront();

Pops front from the range, using func to generate the next time point in the range.

Throws:
std.datetime.date.DateTimeException if the generated time point is greater than front.
pure nothrow @property NegInfIntervalRange save();

Returns a copy of this.

const pure nothrow @property NegInfInterval!TP interval();

The interval that this range currently covers.

pure nothrow @property TP delegate(scope const TP) func();

The function used to generate the next time point in the range.

© 1999–2021 The D Language Foundation
Licensed under the Boost License 1.0.
https://dlang.org/phobos/std_datetime_interval.html