Add time_slots and TimeWindow for issue #481

[anurag-mds]

Implements the API proposed in #481.

time_slots(start, stop, interval; from, to) — generates a TimeArray of timestamps within a daily time window
time_slots(range; from, to) — same, accepts a StepRange{DateTime} directly
when(ta, time_slots(; from, to)) — filters an existing TimeArray by time-of-day via the new TimeWindow type

Closes #481

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.50%. Comparing base (3291223) to head (bac168f).
⚠️ Report is 22 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #553      +/-   ##
==========================================
+ Coverage   85.44%   86.50%   +1.06%     
==========================================
  Files          11       13       +2     
  Lines         625      919     +294     
==========================================
+ Hits          534      795     +261     
- Misses         91      124      +33     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[anurag-mds]

@iblislin

[anurag-mds]

I forgot to mention I added the following tests to make sure the negative inputs are handled
@test_throws ArgumentError time_slots(now(), now()+Day(1), Minute(-1))

Error thrown:

julia> time_slots(now(), now()+Day(1), Minute(-1))
ERROR: ArgumentError: interval must be positive, got -1 minute
Stacktrace:
 [1] #time_slots#25
   @ C:\Users\RadhaKunjBalram\Documents\open source julia\TimeSeries.jl\src\split.jl:80 [inlined]
 [2] time_slots(start::DateTime, stop::DateTime, interval::Minute)
   @ TimeSeries C:\Users\RadhaKunjBalram\Documents\open source julia\TimeSeries.jl\src\split.jl:71
 [3] top-level scope
   @ REPL[4]:1

julia> time_slots(
               DateTime(2023, 1, 1), DateTime(2023, 1, 2), Day(-1), from=Time(9), to=Time(17)
           )
ERROR: ArgumentError: interval must be positive, got -1 day
Stacktrace:
 [1] #time_slots#25
   @ C:\Users\RadhaKunjBalram\Documents\open source julia\TimeSeries.jl\src\split.jl:80 [inlined]
 [2] top-level scope
   @ REPL[2]:1

julia> 

julia> rng = DateTime(2023, 1, 2):Day(-1):DateTime(2023, 1, 1)
DateTime("2023-01-02T00:00:00"):Day(-1):DateTime("2023-01-01T00:00:00")

julia> time_slots(rng)
ERROR: ArgumentError: interval must be positive, got -1 day
Stacktrace:
 [1] #time_slots#26
   @ C:\Users\RadhaKunjBalram\Documents\open source julia\TimeSeries.jl\src\split.jl:98 [inlined]
 [2] time_slots(range::StepRange{DateTime, Day})
   @ TimeSeries C:\Users\RadhaKunjBalram\Documents\open source julia\TimeSeries.jl\src\split.jl:94
 [3] top-level scope
   @ REPL[6]:1

julia> 

[iblislin]

Suggested change

	function time_slots(
	start::T, stop::T, interval::Period; from::Time=Time(0, 0), to::Time=Time(23, 59)
	) where {T<:TimeType}
	function time_slots(
	start::T, stop::T, interval::P; from::Time=Time(0, 0), to::Time=Time(23, 59)
	) where {T<:TimeType,P<:Period}

then, also use those type variables in return?

[iblislin]

I'm not sure about the current behaviour of compiler, is this consider type stable or not, if we use eltype(..) and typeof(..) in return statement. 🤔

type stable is preferred, still fine if not.

[iblislin]

I'm still thinking about the possibility to support negative interval,
especially an edge case like: DateTime(2023, 1, 2, 0, 3):Minute(-4):DateTime(2023, 1, 1).

I forgot to mention I added the following tests to make sure the negative inputs are handled @test_throws ArgumentError time_slots(now(), now()+Day(1), Minute(-1))

Error thrown:

julia> time_slots(now(), now()+Day(1), Minute(-1))
ERROR: ArgumentError: interval must be positive, got -1 minute
Stacktrace:
 [1] #time_slots#25
   @ C:\Users\RadhaKunjBalram\Documents\open source julia\TimeSeries.jl\src\split.jl:80 [inlined]
 [2] time_slots(start::DateTime, stop::DateTime, interval::Minute)
   @ TimeSeries C:\Users\RadhaKunjBalram\Documents\open source julia\TimeSeries.jl\src\split.jl:71
 [3] top-level scope
   @ REPL[4]:1

julia> time_slots(
               DateTime(2023, 1, 1), DateTime(2023, 1, 2), Day(-1), from=Time(9), to=Time(17)
           )
ERROR: ArgumentError: interval must be positive, got -1 day
Stacktrace:
 [1] #time_slots#25
   @ C:\Users\RadhaKunjBalram\Documents\open source julia\TimeSeries.jl\src\split.jl:80 [inlined]
 [2] top-level scope
   @ REPL[2]:1

julia> 

julia> rng = DateTime(2023, 1, 2):Day(-1):DateTime(2023, 1, 1)
DateTime("2023-01-02T00:00:00"):Day(-1):DateTime("2023-01-01T00:00:00")

julia> time_slots(rng)
ERROR: ArgumentError: interval must be positive, got -1 day
Stacktrace:
 [1] #time_slots#26
   @ C:\Users\RadhaKunjBalram\Documents\open source julia\TimeSeries.jl\src\split.jl:98 [inlined]
 [2] time_slots(range::StepRange{DateTime, Day})
   @ TimeSeries C:\Users\RadhaKunjBalram\Documents\open source julia\TimeSeries.jl\src\split.jl:94
 [3] top-level scope
   @ REPL[6]:1

julia> 

[iblislin]

ah, I think we could keep current implementation for the negative interval.
Could you add some notes in the code (maybe a TODO or FIXME section as comment) about that negative interval? (also note a edge case: DateTime(2023, 1, 2, 0, 3):Minute(-4):DateTime(2023, 1, 1))
maybe we could relax this non-negative constrain later.

[anurag-mds]

ah, I think we could keep current implementation for the negative interval. Could you add some notes in the code (maybe a TODO or FIXME section as comment) about that negative interval? (also note a edge case: DateTime(2023, 1, 2, 0, 3):Minute(-4):DateTime(2023, 1, 1)) maybe we could relax this non-negative constrain later.

Sure!, Let me do this real quick.

[iblislin]

Thanks for your contributions!