Skip to content

Commit

Permalink
Add docstring for Dates.adjust (#52914)
Browse files Browse the repository at this point in the history
Co-authored-by: Steven G. Johnson <stevenj@mit.edu>
Co-authored-by: Lilith Orion Hafner <lilithhafner@gmail.com>
  • Loading branch information
3 people authored Jan 27, 2024
1 parent 26e54d3 commit 20085f4
Showing 2 changed files with 36 additions and 3 deletions.
35 changes: 35 additions & 0 deletions stdlib/Dates/src/adjusters.jl
Original file line number Diff line number Diff line change
@@ -204,6 +204,41 @@ function adjust(df::DateFunction, start, step, limit)
throw(ArgumentError("Adjustment limit reached: $limit iterations"))
end

"""
adjust(df, start[, step, limit]) -> TimeType
adjust(df, start) -> TimeType
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
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:
[...]
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
4 changes: 1 addition & 3 deletions stdlib/Dates/test/runtests.jl
Original file line number Diff line number Diff line change
@@ -9,9 +9,7 @@ for file in readlines(joinpath(@__DIR__, "testgroups"))
end

@testset "Docstrings" begin
undoc = Docs.undocumented_names(Dates)
@test_broken isempty(undoc)
@test undoc == [:adjust]
@test isempty(Docs.undocumented_names(Dates))
end

end

0 comments on commit 20085f4

Please sign in to comment.