Add a concept for Duration and Period

rabestro · November 10, 2026, 1:16pm

Problem

The datetime concept covers LocalDate, LocalDateTime and formatting, but it does not cover amounts of time. Duration, Period and ChronoUnit.between() do not appear anywhere in the concept docs. The recently added beauty-salon-regulars exercise (#2944) also lists Duration and Period as out of scope.

As a result, students who meet date arithmetic in practice exercises (gigasecond, swift-scheduling, ledger) either do the arithmetic by hand or run into the classic pitfalls of the API:

LocalDate start = LocalDate.of(2024, 1, 15);
LocalDate end = LocalDate.of(2024, 3, 20);

Period.between(start, end);            // P2M5D
Period.between(start, end).getDays();  // 5, not 65
ChronoUnit.DAYS.between(start, end);   // 65

Duration.between(start, end);          // throws UnsupportedTemporalTypeException

LocalDate.of(2025, 1, 31).plus(Period.ofMonths(1)); // 2025-02-28

The Period.getDays() mistake in particular comes up again and again when people compute “how many days between two dates”.

Proposal

Add one concept, durations-and-periods (the name is open to discussion), together with a concept exercise.

I’d suggest one concept rather than two: what students most need to learn is the contrast between the two types.

	`Period`	`Duration`
Measures	years, months, days (calendar based)	seconds and nanoseconds (exact time)
Works with	`LocalDate`	`LocalTime`, `LocalDateTime`, `Instant`
Typical use	“membership expires in 1 month”	“the session lasted 90 minutes”

Learning objectives

Know the difference between Period (date-based) and Duration (time-based).
Create amounts with Period.ofX() / Duration.ofX() and add or subtract them with plus() / minus().
Compute the amount between two temporals with Period.between(), Duration.between() and ChronoUnit.X.between().
Understand that Period keeps its units separately (P2M5D) and that getDays() is not a total; use ChronoUnit.DAYS.between() or toTotalMonths() when a total is needed.
Understand month-end clamping (Jan 31 + 1 month = Feb 28/29).
Use Duration accessors such as toMinutes(), toHours() and toMinutesPart().

Out of scope

Time zones and ZonedDateTime. The DST difference between Period.ofDays(1) and Duration.ofDays(1) can be shown as a short aside in about.md, but the exercise itself would stay on Local* types, since zones are not taught anywhere in the track yet.
Parsing and formatting ISO-8601 amounts (P1M, PT90M), except for a short mention.
Custom TemporalUnit / TemporalAmount implementations.

Prerequisites

datetime
numbers

Concept exercise

The story should need both types, so students cannot get by with only one of them. One option is a gym or rental service:

The membership end date is the start date plus a Period of N months. This tests month-end clamping.
The number of remaining days is computed with ChronoUnit.DAYS.between(). This tests the getDays() trap.
The length of a visit is a Duration between check-in and check-out LocalDateTimes, billed per started 15 minutes.
An optional extra task checks whether a visit exceeded a time limit with Duration.compareTo().

I’m happy to work on the story if the general direction is accepted.

Practice exercises that could reference the concept

gigasecond: plus(Duration.ofSeconds(1_000_000_000))
swift-scheduling
ledger

Add the concept to their practices / prerequisites where it fits.

Deliverables

concepts/durations-and-periods/{about.md, introduction.md, links.json, .meta/config.json}
A concept exercise with .docs, .meta/design.md, a reference solution and tests
config.json updates (concept, exercise, and links from the practice exercises above)
Optional: analyzer rules, e.g. flag Period.between(...).getDays() used as a total day count

I’d be glad to open a PR for this, following the same structure as the temporal-adjusters concept.

kahgoh · November 11, 2026, 12:51pm

I think this sounds good. Happy for you to raise a PR for this.

rabestro · November 11, 2026, 8:11pm

github.com/exercism/java

Add durations-and-periods concept with gym-front-desk exercise

exercism:main ← rabestro:durations-and-periods

opened 08:05PM - 11 Nov 26 UTC

rabestro

+1496 -2

# pull request ## Description This PR adds a new concept, `durations-and-per…iods`, and a concept exercise that teaches it, `gym-front-desk`. The idea was discussed and approved on the forum: [Add a concept for Duration and Period](https://forum.exercism.org/t/add-a-concept-for-duration-and-period/98275). **Motivation** The `datetime` concept covers points in time (`LocalDate`, `LocalDateTime`) but not amounts of time, and `beauty-salon-regulars` explicitly leaves `Duration` and `Period` out of scope. Students who do date arithmetic in practice exercises either do it by hand or run into the usual pitfalls, the most common being `Period.between(a, b).getDays()` used as a total number of days. **Concept: `durations-and-periods`** - `introduction.md`: `Period` (factory methods, `plus()`, month-end clamping, `Period.between()` and its parts), counting units with `ChronoUnit.X.between()`, and `Duration` (factory methods, `Duration.between()`, `toXxx()` vs `toXxxPart()`). - `about.md`: adds ISO-8601 parsing, `until()`, `toTotalMonths()`, `normalized()` and unit-by-unit `equals()`, `UnsupportedTemporalTypeException` when mixing dates and durations, comparing and arithmetic with durations, and a short aside on why `Period.ofDays(1)` and `Duration.ofDays(1)` differ across a DST change. - Javadoc links point to Java 25, each sentence is on its own line, and the docs do not refer to any practice exercise. - All code examples were checked in `jshell`. **Exercise: `gym-front-desk`** A climbing gym front desk, with five tasks: 1. `membershipEnd()`: add a `Period` of months to a start date (tests include month-end clamping and leap years). 2. `membershipLength()`: `Period.between()`. 3. `daysLeft()`: total days with `ChronoUnit.DAYS.between()` (a test spans several months, so `Period.getDays()` fails it). 4. `visitDuration()`: `Duration.between()` for a visit, including one past midnight. 5. `formatVisit()`: `"1h 35m"` on a receipt, using `toHours()` and `toMinutesPart()` (a test with a visit over 24 hours catches `toHoursPart()`). Prerequisites: `datetime`, `strings`. `design.md` lists suggested analyzer rules. **Config changes** - Added the concept and the exercise to `config.json` (UUIDs `16500ebe-104e-44c3-84b3-3126a49bdb89` and `6553f255-154f-441d-a6e1-a428434f9653`) and the exercise to `exercises/settings.gradle`. - Added `durations-and-periods` to the `practices` and `prerequisites` of `gigasecond`, which adds a gigasecond to a date-time. Happy to drop it from `prerequisites` if you'd rather not lock the exercise behind the new concept. **Checks run locally** - `./gradlew test`, `check` and `compileStarterTestJava` for the exercise (JDK 25): 23 tests pass, no Checkstyle issues. - `configlet lint` and `configlet generate` (the exercise's `introduction.md` is generated from the concept). - `markdownlint-cli2` on the new Markdown files. The `i18n / completeness` check will need the `ready-to-translate` label to queue the new English for translation. --- Reviewer Resources: [Track Policies](https://github.com/exercism/java/blob/main/POLICIES.md#event-checklist) 🤖 Generated with [Claude Code](https://claude.com/claude-code)