From b25aac741ae81e0dee27c7db9402cd865c4a9af7 Mon Sep 17 00:00:00 2001 From: jam-khan Date: Mon, 15 Jan 2024 16:22:58 -0500 Subject: [PATCH 1/6] Docstrings added for adjust in Dates in stdlib --- stdlib/Dates/src/adjusters.jl | 43 +++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/stdlib/Dates/src/adjusters.jl b/stdlib/Dates/src/adjusters.jl index 245e2678a9d77..88b33e3f3a39c 100644 --- a/stdlib/Dates/src/adjusters.jl +++ b/stdlib/Dates/src/adjusters.jl @@ -196,6 +196,28 @@ end Base.show(io::IO, df::DateFunction) = println(io, df.f) # Core adjuster + +""" + adjust(df::DateFunction, start, step, limit) -> TimeType + +Adjusts the date in `start` until `f::Function` in `df::DateFunction` returns `true`. +The step size dictates change in `start` on every iteration. If `limit` iterations occur, +then ArgumentError is thrown. + +# Examples +```jldoctest +julia> adjust(date -> month(date) == 10, Date(2022, 1, 1), step=Month(3), limit=10) +2022-10-01 + +julia> adjust(date -> year(date) == 2025, Date(2022, 1, 1), step=Year(1), limit=4) +2025-01-01 + +julia> adjust(date -> day(date) == 15, Date(2022, 1, 1); step=Year(1), limit=3) +ERROR: ArgumentError: Adjustment limit reached: 3 iterations +Stacktrace: +[...] +``` +""" function adjust(df::DateFunction, start, step, limit) for i = 1:limit df.f(start) && return start @@ -204,6 +226,27 @@ function adjust(df::DateFunction, start, step, limit) throw(ArgumentError("Adjustment limit reached: $limit iterations")) end +""" + adjust(df::DateFunction, start) -> TimeType + +Adjusts the date in `start` until `f::Function` in `df::DateFunction` returns `true`. +On every iteration, start is incremented by 1 Day. If 10000 iterations occur, +then ArgumentError is thrown. + +# Examples +```jldoctest +julia> adjust(date -> month(date) == 10, Date(2022, 1, 1)) +2022-10-01 + +julia> adjust(date -> year(date) == 2025, Date(2022, 1, 1)) +2025-01-01 + +julia> adjust(date -> year(date) == 2224, Date(2022, 1, 1)) +ERROR: ArgumentError: Adjustment limit reached: 10000 iterations +Stacktrace: +[...] +``` +""" function adjust(func::Function, start; step::Period=Day(1), limit::Int=10000) return adjust(DateFunction(func, start), start, step, limit) end From f892ee6a84cbc166c2ddc9ed0b978171d3f29258 Mon Sep 17 00:00:00 2001 From: jam-khan Date: Mon, 15 Jan 2024 20:31:49 -0500 Subject: [PATCH 2/6] Update stdlib/Dates/src/adjusters.jl Co-authored-by: Steven G. Johnson --- stdlib/Dates/src/adjusters.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stdlib/Dates/src/adjusters.jl b/stdlib/Dates/src/adjusters.jl index 88b33e3f3a39c..6906b8fab6946 100644 --- a/stdlib/Dates/src/adjusters.jl +++ b/stdlib/Dates/src/adjusters.jl @@ -202,7 +202,7 @@ Base.show(io::IO, df::DateFunction) = println(io, df.f) Adjusts the date in `start` until `f::Function` in `df::DateFunction` returns `true`. The step size dictates change in `start` on every iteration. If `limit` iterations occur, -then ArgumentError is thrown. +then an [`ArgumentError`](@ref) is thrown. # Examples ```jldoctest From b0a7b9cfb8a8c6e1ff2bf774ea3733704b22d5fa Mon Sep 17 00:00:00 2001 From: jam-khan Date: Fri, 26 Jan 2024 13:53:14 -0500 Subject: [PATCH 3/6] Merged docstrings for adjust and changed runtests.jl for Dates --- stdlib/Dates/src/adjusters.jl | 39 ++++++++++++++--------------------- stdlib/Dates/test/runtests.jl | 8 ++----- 2 files changed, 18 insertions(+), 29 deletions(-) diff --git a/stdlib/Dates/src/adjusters.jl b/stdlib/Dates/src/adjusters.jl index 6906b8fab6946..585ee2ed29b27 100644 --- a/stdlib/Dates/src/adjusters.jl +++ b/stdlib/Dates/src/adjusters.jl @@ -198,11 +198,14 @@ Base.show(io::IO, df::DateFunction) = println(io, df.f) # Core adjuster """ - adjust(df::DateFunction, start, step, limit) -> TimeType + adjust(df, start[, step, limit]) -> TimeType + adjust(df, start) -> TimeType -Adjusts the date in `start` until `f::Function` in `df::DateFunction` returns `true`. -The step size dictates change in `start` on every iteration. If `limit` iterations occur, -then an [`ArgumentError`](@ref) is thrown. +Adjusts the date in `start` until the `f::Function` passed using `df` returns `true`. +The optional `step` parameter dictates the change in `start` on every iteration. +If `limit` iterations occur, then an [`ArgumentError`](@ref) is thrown. + +The default values for parameters `start` and `limit` are 1 Day and 10,000 respectively. # Examples ```jldoctest @@ -212,29 +215,11 @@ julia> adjust(date -> month(date) == 10, Date(2022, 1, 1), step=Month(3), limit= julia> adjust(date -> year(date) == 2025, Date(2022, 1, 1), step=Year(1), limit=4) 2025-01-01 -julia> adjust(date -> day(date) == 15, Date(2022, 1, 1); step=Year(1), limit=3) +julia> adjust(date -> day(date) == 15, Date(2022, 1, 1), step=Year(1), limit=3) ERROR: ArgumentError: Adjustment limit reached: 3 iterations Stacktrace: [...] -``` -""" -function adjust(df::DateFunction, start, step, limit) - for i = 1:limit - df.f(start) && return start - start += step - end - throw(ArgumentError("Adjustment limit reached: $limit iterations")) -end - -""" - adjust(df::DateFunction, start) -> TimeType -Adjusts the date in `start` until `f::Function` in `df::DateFunction` returns `true`. -On every iteration, start is incremented by 1 Day. If 10000 iterations occur, -then ArgumentError is thrown. - -# Examples -```jldoctest julia> adjust(date -> month(date) == 10, Date(2022, 1, 1)) 2022-10-01 @@ -247,6 +232,14 @@ Stacktrace: [...] ``` """ +function adjust(df, start, step, limit) + for i = 1:limit + df.f(start) && return start + start += step + end + throw(ArgumentError("Adjustment limit reached: $limit iterations")) +end + function adjust(func::Function, start; step::Period=Day(1), limit::Int=10000) return adjust(DateFunction(func, start), start, step, limit) end diff --git a/stdlib/Dates/test/runtests.jl b/stdlib/Dates/test/runtests.jl index 7ac46bd69139c..c0e9f4657fc54 100644 --- a/stdlib/Dates/test/runtests.jl +++ b/stdlib/Dates/test/runtests.jl @@ -9,9 +9,5 @@ for file in readlines(joinpath(@__DIR__, "testgroups")) end @testset "Docstrings" begin - undoc = Docs.undocumented_names(Dates) - @test_broken isempty(undoc) - @test undoc == [:adjust] -end - -end + @test isempty(Docs.undocumented_names(Dates)) +end \ No newline at end of file From 1becc76d407afa4a77d52b714484d0d28a868fb7 Mon Sep 17 00:00:00 2001 From: jam-khan Date: Fri, 26 Jan 2024 13:54:13 -0500 Subject: [PATCH 4/6] Corrected runtests.jl --- stdlib/Dates/test/runtests.jl | 2 ++ 1 file changed, 2 insertions(+) diff --git a/stdlib/Dates/test/runtests.jl b/stdlib/Dates/test/runtests.jl index c0e9f4657fc54..4787ae5e5bbc8 100644 --- a/stdlib/Dates/test/runtests.jl +++ b/stdlib/Dates/test/runtests.jl @@ -10,4 +10,6 @@ end @testset "Docstrings" begin @test isempty(Docs.undocumented_names(Dates)) +end + end \ No newline at end of file From 55e9669e50283ef8584d1eceb967da10e81d5694 Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Sat, 27 Jan 2024 01:12:02 +0000 Subject: [PATCH 5/6] Fix whitespace --- stdlib/Dates/test/runtests.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stdlib/Dates/test/runtests.jl b/stdlib/Dates/test/runtests.jl index 4787ae5e5bbc8..ad2ee43cedfb1 100644 --- a/stdlib/Dates/test/runtests.jl +++ b/stdlib/Dates/test/runtests.jl @@ -12,4 +12,4 @@ end @test isempty(Docs.undocumented_names(Dates)) end -end \ No newline at end of file +end From 5805e4446ebeb926452bd795a1683972f23047fe Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Sat, 27 Jan 2024 01:16:04 +0000 Subject: [PATCH 6/6] Move docstring to ::Function method and put back ::DateFunction type annotation --- stdlib/Dates/src/adjusters.jl | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/stdlib/Dates/src/adjusters.jl b/stdlib/Dates/src/adjusters.jl index 585ee2ed29b27..dee2894ff5d4e 100644 --- a/stdlib/Dates/src/adjusters.jl +++ b/stdlib/Dates/src/adjusters.jl @@ -196,6 +196,13 @@ end Base.show(io::IO, df::DateFunction) = println(io, df.f) # Core adjuster +function adjust(df::DateFunction, start, step, limit) + for i = 1:limit + df.f(start) && return start + start += step + end + throw(ArgumentError("Adjustment limit reached: $limit iterations")) +end """ adjust(df, start[, step, limit]) -> TimeType @@ -232,14 +239,6 @@ Stacktrace: [...] ``` """ -function adjust(df, start, step, limit) - for i = 1:limit - df.f(start) && return start - start += step - end - throw(ArgumentError("Adjustment limit reached: $limit iterations")) -end - function adjust(func::Function, start; step::Period=Day(1), limit::Int=10000) return adjust(DateFunction(func, start), start, step, limit) end