You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Refactor and streamline TemporalAdjusters documentation
Simplify the introduction and examples for `TemporalAdjusters` to improve clarity and focus on practical use cases. Removed redundant examples and reorganized sections to prioritize key adjusters like ordinal days and "teenth" date calculations. Enhanced consistency and readability across code snippets and explanations.
While the core`java.time`classes like `LocalDate` and `LocalDateTime` provide basic methods for adding or subtracting time units, more complex date adjustments often require more sophisticated logic (e.g., finding the "second Tuesday of the month" or the "last day of the year").
3
+
When working with`java.time`objects like `LocalDate`, you often need to perform complex date adjustments, such as finding the "second Tuesday of the month". Instead of calculating this manually, you can use **`TemporalAdjusters`**.
4
4
5
-
The `java.time.temporal` package provides the [`TemporalAdjuster`][temporaladjuster-docs] functional interface for this purpose. It represents a strategy for adjusting a temporal object (like a `LocalDate`). The [`TemporalAdjusters`][temporaladjusters-docs] (note the plural 's') utility class contains static factory methods providing many common, predefined adjuster implementations.
6
-
7
-
## Using TemporalAdjusters
8
-
9
-
Temporal objects like `LocalDate` and `LocalDateTime` have a `with()` method that accepts a `TemporalAdjuster`. This method returns a *new* temporal object with the adjustment applied.
5
+
The `java.time.temporal.TemporalAdjusters` (note the plural 's') utility class provides static methods for many common date adjustments. You apply these adjustments using the `.with()` method on a temporal object (like `LocalDate`).
10
6
11
7
```exercism/note
12
-
Using `with(TemporalAdjuster)` returns a _new_ instance and does not update the existing instance, as all `java.time` temporal classes are immutable.
8
+
Using `with(TemporalAdjuster)` returns a _new_ instance and does not update the existing instance, as `java.time` objects are immutable.
The`firstInMonth(DayOfWeek dayOfWeek)`and`lastInMonth(DayOfWeek dayOfWeek)` adjusters find the first or last occurrence of a day of the week within the month.
Adjusters like `next()`, `previous()`, `nextOrSame()`, and `previousOrSame()` find the next or previous occurrence of a given day of the week, relative to the current date.
46
+
### Finding Relative Occurrences ("Teenth" dates)
87
47
88
-
*`next()`/`previous()`: Excludes the current date if it matches.
89
-
*`nextOrSame()`/`previousOrSame()`: Includes the current date if it matches.
48
+
Use `nextOrSame(DayOfWeek dayOfWeek)`. This is useful for finding dates like the "teenth" days (13th-19th). Apply it to the 13th day of the month to find the target day of the week within that "teenth" range.
The `nextOrSame()` adjuster is particularly useful for finding dates in ranges like the "teenth" days (13th-19th) of a month, as seen in the Meetup exercise. Applying `nextOrSame(targetDayOfWeek)` to the 13th day of the month will find the correct "teenth" date.
111
-
112
-
## Custom Adjusters
113
-
114
-
Since `TemporalAdjuster` is a [`@FunctionalInterface`][functionalinterface-docs], you can create your own custom adjusters using lambda expressions for logic not covered by the predefined methods. The interface requires implementing a single method: `Temporal adjustInto(Temporal temporal)`.
115
-
116
-
```java
117
-
// Example: An adjuster that finds the next workday (Mon-Fri), skipping weekends.
118
-
TemporalAdjuster nextWorkday = temporal -> {
119
-
LocalDate result = (LocalDate) temporal; // Assuming input is LocalDate
120
-
do {
121
-
result = result.plusDays(1);
122
-
} while (result.getDayOfWeek() ==DayOfWeek.SATURDAY|| result.getDayOfWeek() ==DayOfWeek.SUNDAY);
0 commit comments