# Date and Time

Course: [Dart](https://www.devtutorials.ai/learn/dart) · Section: Strings
Source: https://www.devtutorials.ai/learn/dart/strings-and-dates/date-and-time

> How to create DateTime values, read their parts, compare and subtract dates, add time with Duration, and convert dates to text and timestamps.

## What Is DateTime?

**DateTime** = a Dart value that holds one exact moment: a date **and** a time.

For example:

- the start of the Maths exam: 14 November 2026, 9:30 in the morning
- the homework deadline: 20 November 2026, 11:59 at night
- right now

**Duration** = a length of time, like 3 days or 45 minutes. It is not a moment, just an amount.

**Simple lesson:** a DateTime is a point on the calendar, and a Duration is a gap between two points.

### A Real-World Example

The school app shows: "Exam in 10 days, on Tuesday."

- It knows **today** (a DateTime).
- It knows the **exam date** (another DateTime).
- It works out the **gap** between them (a Duration), and the **weekday** of the exam.

Move the sliders to add time to a date:

Every **Run** box on this page runs on the course's Dart runner in your browser.

Boxes that use `DateTime.now()` or your time zone print something different for every person. That is expected.

## What You Will Learn

In this lesson, you will learn:

1. How to create DateTime values in five ways.
2. How to read a date's parts, like `year`, `month` and `weekday`.
3. How to compare dates and find the time between them.
4. How to add and subtract time, and turn dates into text and timestamps.
5. How to create and use Duration values.

## Creating DateTime Objects

```dart runnable title="Creating dates"
void main() {
  var exam = DateTime(2026, 11, 14, 9, 30);
  var republicDay = DateTime.utc(2026, 1, 26, 10);
  var independenceDay = DateTime.parse('2026-08-15 08:00:00');
  var start = DateTime.fromMillisecondsSinceEpoch(0, isUtc: true);
  print(exam);
  print(republicDay);
  print(independenceDay);
  print(start);
}
```

**Local time** = the time on your own clock, in your time zone.

**UTC (Coordinated Universal Time)** = one standard clock for the whole world. India is 5 hours 30 minutes ahead of it.

### DateTime.now()

```dart runnable varies title="Right now"
void main() {
  var now = DateTime.now();
  print(now);
  print('This year is ${now.year}.');
}
```

Your output is different from everyone else's, because it reads your clock.

**Simple lesson:** use `DateTime(...)` for a fixed date, `DateTime.now()` for the current moment, and `DateTime.parse()` for text.

## Date Components

Every DateTime has these parts:

| Property | Gives | For `DateTime(2026, 11, 14, 9, 30)` |
|---|---|---|
| `year` | the year | `2026` |
| `month` | 1 to 12 | `11` |
| `day` | 1 to 31 | `14` |
| `hour` | 0 to 23 | `9` |
| `minute`, `second` | 0 to 59 | `30`, `0` |
| `millisecond`, `microsecond` | 0 to 999 | `0`, `0` |
| `weekday` | 1 (Monday) to 7 (Sunday) | `6` (Saturday) |

```dart runnable title="Reading the parts of a date"
void main() {
  var exam = DateTime(2026, 11, 14, 9, 30);
  var days = ['', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'];
  print('${exam.day}/${exam.month}/${exam.year}');
  print('Starts at ${exam.hour}:${exam.minute}');
  print('Weekday number: ${exam.weekday}');
  print('That is a ${days[exam.weekday]}.');
  print(exam.weekday == DateTime.saturday);
}
```

- `weekday` starts at **1 for Monday**, not 0.
- Dart has names for them: `DateTime.monday` is 1, up to `DateTime.sunday`, which is 7.

**Simple lesson:** read a date's parts with `year`, `month`, `day`, `hour` and `weekday`.

## Time Zone Properties

- **`isUtc`** = `true` if the date is in UTC.
- **`timeZoneName`** = a short name, like `IST`. It depends on the computer.
- **`timeZoneOffset`** = how far this time zone is from UTC, as a Duration.

```dart runnable varies title="Your time zone"
void main() {
  var exam = DateTime(2026, 11, 14, 9, 30);
  print(exam.isUtc);
  print(exam.timeZoneName);
  print(exam.timeZoneOffset);
  var utc = exam.toUtc();
  print(utc);
  print(utc.isUtc);
}
```

In India, the offset is `5:30:00.000000`. On a computer set to another country, the numbers differ.

- **`toUtc()`** = the same moment, shown on the UTC clock.
- **`toLocal()`** = the same moment, shown on your local clock.

**Simple lesson:** a moment is the same everywhere, but its clock time depends on the time zone.

## Date Operations

| Method | Question |
|---|---|
| `isBefore(other)` | Is this earlier? |
| `isAfter(other)` | Is this later? |
| `isAtSameMomentAs(other)` | Is it the exact same moment? |
| `compareTo(other)` | `-1` if earlier, `0` if the same, `1` if later |
| `difference(other)` | the time between them, as a Duration |

```dart runnable title="Comparing two dates"
void main() {
  var today = DateTime(2026, 11, 4);
  var exam = DateTime(2026, 11, 14);
  print(today.isBefore(exam));
  print(today.isAfter(exam));
  print(today.compareTo(exam));
  var gap = exam.difference(today);
  print(gap);
  print('Exam in ${gap.inDays} days');
}
```

`exam.difference(today)` = exam minus today. Swap them and the Duration is negative.

**Simple lesson:** compare dates with `isBefore` and `isAfter`, and measure the gap with `difference`.

## Date Modification

- **`add(duration)`** = a **new** date, later by that much.
- **`subtract(duration)`** = a **new** date, earlier by that much.

The original date never changes.

**Simple lesson:** `add` and `subtract` give new dates, and leave the old one unchanged.

## Formatting and Timestamps

### toString() and toIso8601String()

- **`toString()`** = `2026-11-14 09:30:00.000`. This is what `print` shows.
- **`toIso8601String()`** = `2026-11-14T09:30:00.000`. The world standard, used by servers and JSON.

### Timestamps

**Epoch** = 1 January 1970, 00:00 UTC. Computers count time from this moment.

**Timestamp** = the number of milliseconds (or microseconds) since the epoch.

```dart runnable title="Text and timestamps"
void main() {
  var launch = DateTime.utc(2026, 11, 14, 9, 30);
  print(launch.toString());
  print(launch.toIso8601String());
  print(launch.millisecondsSinceEpoch);
  print(launch.microsecondsSinceEpoch);
  var back = DateTime.fromMillisecondsSinceEpoch(launch.millisecondsSinceEpoch, isUtc: true);
  print(back);
}
```

A timestamp is just a number, so it is easy to store and send.

For pretty dates like "Saturday, 14 Nov 2026", use the **intl** package (see **Libraries**).

Dart's own `toString()` always uses the year-month-day form.

**Simple lesson:** `toIso8601String()` is the standard text form, and a timestamp is the date as one big number.

## Duration Fundamentals

**Duration** = an amount of time.

### Duration Constructors

Make one with named parameters, all optional:

`Duration(days: 1, hours: 2, minutes: 30, seconds: 15, milliseconds: 0, microseconds: 0)`

```dart runnable title="Making durations"
void main() {
  var period = Duration(minutes: 40);
  var lunch = Duration(minutes: 45);
  var schoolDay = Duration(hours: 6, minutes: 30);
  var holiday = Duration(days: 10);
  print(period);
  print(lunch);
  print(schoolDay);
  print(holiday);
}
```

A Duration prints as `hours:minutes:seconds.microseconds`. Ten days is `240:00:00.000000`.

### Duration Properties

| Property | Gives |
|---|---|
| `inDays` | whole days |
| `inHours` | whole hours |
| `inMinutes` | whole minutes |
| `inSeconds` | whole seconds |
| `inMilliseconds`, `inMicroseconds` | smaller units |

```dart runnable title="One duration, many units"
void main() {
  var schoolDay = Duration(hours: 6, minutes: 30);
  print(schoolDay.inHours);
  print(schoolDay.inMinutes);
  print(schoolDay.inSeconds);
  print(schoolDay.inDays);
}
```

Each `in...` gives **whole** units. 6 hours 30 minutes is `6` in `inHours`, not 6.5.

**Simple lesson:** make a Duration with named parts, and read it back in any unit with `in...`.

## Working with Duration

### Adding and Subtracting Durations

```dart runnable title="Adding up the school timetable"
void main() {
  var period = Duration(minutes: 40);
  var breakTime = Duration(minutes: 15);
  var morning = period + period + period + breakTime;
  print(morning);
  print(morning.inMinutes);
  var left = Duration(hours: 3) - morning;
  print(left);
  print(period < breakTime);
  print(period * 2);
}
```

- **`+`** and **`-`** add and subtract durations.
- **`<`**, **`>`** and **`==`** compare them.
- **`*`** with a number multiplies a duration.

**Easy way to remember**

- **DateTime** = a moment: "14 November, 9:30".
- **Duration** = an amount: "40 minutes".
- moment + amount = new moment. moment − moment = amount.

**Simple lesson:** durations add and subtract like numbers, and a date plus a duration is a new date.

## TL;DR

1. **DateTime** = one moment. Create with `DateTime(...)`, `now()`, `utc(...)`, `parse(...)` or `fromMillisecondsSinceEpoch(...)`.
2. **Parts:** `year`, `month`, `day`, `hour`, `minute`, `second`, `weekday` (1 = Monday).
   - **Time zones:** `isUtc`, `timeZoneName`, `timeZoneOffset`, `toUtc()`, `toLocal()`.
3. **Compare:** `isBefore`, `isAfter`, `isAtSameMomentAs`, `compareTo`. **Gap:** `difference`.
4. **Change:** `add` and `subtract` give new dates.
   - **Text:** `toString()`, `toIso8601String()`. **Timestamps:** `millisecondsSinceEpoch`.
5. **Duration** = an amount. `Duration(days:, hours:, minutes:, ...)`, read with `inDays`, `inHours`...
   - Add and subtract with `+` and `-`.

## Common mistakes

| Mistake | Wrong idea | Correct idea | What goes wrong |
|---|---|---|---|
| `DateTime(2026, 0, 14)` for January | Months start at 0 | Months are 1 to 12 | December of the year before. |
| `weekday == 0` for Sunday | Weekdays start at 0 | Monday is 1, Sunday is 7 | Sunday is never found. |
| `date.add(...)` alone | It changes `date` | It gives a new date | Nothing changes. Store the result. |
| `inHours` for 6 h 30 min gives 6.5 | `in...` gives decimals | It gives whole units | You lose the 30 minutes. Use `inMinutes`. |
| Printing `DateTime.now()` in a test | It is always the same | It changes every run | Tests that fail tomorrow. |
| Comparing dates with `==` | Same day means equal | `==` needs the same moment and the same UTC setting | Use `isAtSameMomentAs`. |
| Mixing local and UTC dates | They are the same | They can be hours apart | Off-by-hours mistakes. |

## Check Yourself

## Exercises

## What to Remember

- A DateTime is a moment. Create it with `DateTime(...)`, `now()`, `utc()` or `parse()`.
- `weekday` runs from 1 (Monday) to 7 (Sunday), and months run from 1 to 12.
- `isBefore`, `isAfter` and `difference` compare dates.
- `add` and `subtract` make new dates. The original never changes.
- A Duration is an amount of time. Read it with `inDays`, `inHours` and `inMinutes`.

Next: **Libraries**. You will learn how Dart code is split into libraries, and how to import the ones you need.