std.datetime.interval

Indicates a direction in time. One example of its use is Interval's

should be expanded backwards (into the past), forwards (into the future), or both.

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.

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.

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.

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.

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.

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 Date and returned a Date which was one day later. That function would then be used by IntervalRange's popFront to iterate over the 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

generate a time point going in the proper direction of iteration, or a

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 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

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.

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

which was one day later. That function would then be used by PosInfIntervalRange's popFront to iterate over 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

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

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 Date and returned a Date which was one day earlier. That function would then be used by NegInfIntervalRange's popFront to iterate over the 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

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

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.