التواريخ والأوقات المحلية

Written Explanation

The three local types

All three live in java.time, so start the file with import java.time.*;. They are immutable. The Javadoc for LocalDate states that it does not store a time or a time zone, and describes it as the date "as used for birthdays".

Creating values

There are three common ways.

LocalDate d = LocalDate.of(2026, 3, 15);        // year, month, day
LocalTime t = LocalTime.of(9, 30);              // hour, minute
LocalDateTime dt = LocalDateTime.of(d, t);      // combine a date and a time
LocalDate today = LocalDate.now();              // from the system clock and default zone
LocalDate parsed = LocalDate.parse("2026-03-15");

• of(...) builds a value from numbers. The month is a normal number from 1 to 12, not zero-based like the legacy Date.
• now() reads the system clock. The answer depends on the machine's default zone, which is why tests that call now() are hard to repeat.
• parse(text) reads text in the standard ISO form yyyy-MM-dd for dates, HH:mm for times, and yyyy-MM-ddTHH:mm for date-times. Lesson 4 covers other formats.

Printing a value with println shows the same ISO form:

2026-03-15 | 09:30 | 2026-03-15T09:30

Reading parts

d.getYear();          // 2026
d.getMonthValue();    // 3
d.getDayOfMonth();    // 15
d.getDayOfWeek();     // SUNDAY
d.getDayOfYear();     // 74

getDayOfWeek() and getMonth() return named constants (for example SUNDAY and MARCH) which print as words. You can convert between a date-time and its parts: dt.toLocalDate() and dt.toLocalTime() split it, and LocalDateTime.of(date, time) joins it.

Changing values: new objects

Every change method returns a new value. The original stays as it was.

LocalDate d = LocalDate.of(2026, 3, 15);
d.plusDays(30);                                 // result discarded
System.out.println(d);                          // 2026-03-15 (unchanged)
LocalDate later = d.plusDays(30).minusMonths(1);

The names follow a pattern: plusDays, plusWeeks, plusMonths, plusYears, and the minus... versions; plusHours, plusMinutes on times; and withYear, withHour to replace one field. You can chain them because each call returns a value you can call the next method on.

Comparing

a.isBefore(b);     // true if a is earlier than b
a.isAfter(b);      // true if a is later
a.equals(b);       // true if the same date (value comparison)

Use these instead of ==, which compares object references (BEG-026). LocalDate objects with the same date are equal even when they are different objects. Because LocalDate also implements Comparable, you can sort a list of dates with the tools from BEG-032.

Invalid dates and clamping

The library refuses dates that do not exist.

LocalDate.of(2026, 2, 30);
// DateTimeException: Invalid date 'FEBRUARY 30'

DateTimeException is an unchecked exception (BEG-029), so the compiler does not force you to catch it. Catch it where the date comes from user input.

Arithmetic is different: it does not throw. When adding months would land on a day that does not exist, the library moves to the last valid day of the month. Its Javadoc gives this rule with an example for 31 March plus one month.

LocalDate.of(2026, 1, 31).plusMonths(1);   // 2026-02-28
LocalDate.of(2024, 2, 29).plusYears(1);    // 2025-02-28

A subtle consequence: adding then subtracting is not always a round trip. 31 January plus one month is 28 February; minus one month is 28 January, not 31 January. If a requirement says "the same day each month" you must work from the original date each time (start.plusMonths(n)), not chain one-month steps.

LocalDate due = LocalDate.of(2026, 1, 31);
due.plusMonths(1);   // 2026-02-28
due.plusMonths(2);   // 2026-03-31

What a LocalDateTime is not

2026-03-15T09:30 is not a moment. In Riyadh it is one moment; in New York, another one, several hours later. Until you attach a zone, nothing tells you which. That is perfectly fine for facts like "the shop opens at 09:30", and wrong for facts like "the order was placed at 09:30". Lesson 3 adds the zone. The rule of thumb for now:

• If the value describes a calendar or wall clock fact: local type.
• If it describes when something happened or will happen: you need a zone or an Instant.