Skip to content

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

Open
rabestro wants to merge 1 commit into
exercism:mainfrom
rabestro:durations-and-periods
Open

rabestro wants to merge 1 commit into
exercism:mainfrom
rabestro:durations-and-periods

Conversation

@rabestro

Copy link
Copy Markdown
Member

pull request

Description

This PR adds a new concept, durations-and-periods, 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.

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

🤖 Generated with Claude Code

Introduces the `durations-and-periods` concept, which covers the
date-based `Period`, the time-based `Duration` and counting units with
`ChronoUnit.between()`, including common pitfalls such as
`Period.getDays()` not being a total and month-end clamping.

The new `gym-front-desk` concept exercise teaches it through a climbing
gym front desk: membership end dates and lengths (`Period`), days left
on a membership (`ChronoUnit.DAYS`) and the length of a visit printed on
a receipt (`Duration`, `toHours()` vs `toMinutesPart()`).

Also adds the concept to the `practices` and `prerequisites` of the
`gigasecond` practice exercise.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kahgoh kahgoh self-assigned this Nov 16, 2026
Comment on lines +13 to +18
| | `Period` | `Duration` |
| --- | --- | --- |
| Stores | years, months and days | seconds and nanoseconds |
| Used with | `LocalDate` | `LocalTime`, `LocalDateTime`, `Instant` |
| Example | "the membership lasts 1 month" | "the visit lasted 95 minutes" |
| `toString()` | `P1Y2M15D` | `PT1H35M` |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A couple of comments on this table:

  • I think Period can also be used with both LocalDateTime and Instant, not just LocalDate.
  • I think the "Example" and "toString()" rows are a bit confusing because the "Example" doesn't show how the period is created for the "toString()". Is the first "toString" supposed to be "P1M"? In any case, you already show some examples later, so it might not be needed in this table.

The `java.time` package also has two classes that describe an _amount_ of time:

- `java.time.Period` is an amount of time in years, months and days, such as "2 months and 5 days".
- `java.time.Duration` is an amount of time in seconds and nanoseconds, such as "1 hour and 30 minutes".

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to mention the other time units?

Suggested change
- `java.time.Duration` is an amount of time in seconds and nanoseconds, such as "1 hour and 30 minutes".
- `java.time.Duration` is an amount of time in hours, minutes, seconds, milliseconds and nanoseconds, such as "1 hour and 30 minutes".

@kahgoh kahgoh removed their assignment Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants