# man > DateTime::Format::ISO8601(3pm)

---
type: CommandReference
command: DateTime::Format::ISO8601
mode: perldoc
section: ""
source: perldoc
---

## Quick Reference

- `DateTime::Format::ISO8601->parse_datetime($str)` — parse ISO8601 date string (e.g., '2020-07-25T11:32:31')
- `DateTime::Format::ISO8601->parse_time($str)` — parse ISO8601 time string (e.g., '113231')
- `DateTime::Format::ISO8601->format_datetime($dt)` — format DateTime object to ISO8601 string
- `DateTime::Format::ISO8601->new(%opts)` — create formatter object with `base_datetime`, `cut_off_year`, `legacy_year`
- `DateTime::Format::ISO8601->DefaultCutOffYear($int)` — set/get global default cut-off year for 2-digit years
- `DateTime::Format::ISO8601->DefaultLegacyYear($bool)` — set/get global default legacy year flag

## Name

Parses ISO8601 formats

## Synopsis

perl
use DateTime::Format::ISO8601;

my $datetime_str = '2020-07-25T11:32:31';
my $dt = DateTime::Format::ISO8601->parse_datetime($datetime_str);
say $dt;

my $time_str = '113231';
$dt = DateTime::Format::ISO8601->parse_time($time_str);
say $dt;

my $iso8601 = DateTime::Format::ISO8601->new;
$dt = $iso8601->parse_datetime($datetime_str);
say $dt;

say DateTime::Format::ISO8601->format_datetime($dt);
## Options

### Constructors

- `DateTime::Format::ISO8601->new(%opts)` — create a new formatter. Optional keys: `base_datetime` (DateTime object to fill missing info), `cut_off_year` (integer, default from `DefaultCutOffYear`), `legacy_year` (boolean, default from `DefaultLegacyYear`).
- `$iso8601->clone` — return a replica of the object.

### Object Methods

- `$iso8601->base_datetime` — return the base DateTime object if set.
- `$iso8601->set_base_datetime($object)` — set a DateTime object to fill missing info.
- `$iso8601->cut_off_year` — return the cut-off year integer.
- `$iso8601->set_cut_off_year($int)` — set cut-off year: 2-digit years < $int → 20xx, ≥ $int → 19xx.
- `$iso8601->legacy_year` — return boolean indicating legacy year handling.
- `$iso8601->set_legacy_year($bool)` — set legacy year behavior: true uses `cut_off_year`, false interprets as current century.

### Class Methods

- `DateTime::Format::ISO8601->DefaultCutOffYear($int)` — get/set global default cut-off year for class-method calls and object creation.
- `DateTime::Format::ISO8601->DefaultLegacyYear($bool)` — get/set global default legacy year flag.

### Parsers

- `parse_datetime($str)` — parse a date/time string. Ambiguous strings (date-only formats) are matched as date. Supports ISO 8601 sections 5.2, 5.3, 5.4.
- `parse_time($str)` — parse a time-only string. Supports ISO 8601 section 5.3.1.1-5.3.1.4.

### Formatter

- `format_datetime($dt)` — format a DateTime object to ISO8601. Includes nanoseconds/milliseconds and correct timezone offset.

## Examples

perl
use DateTime::Format::ISO8601;

# Parse a full datetime
my $dt = DateTime::Format::ISO8601->parse_datetime('2020-07-25T11:32:31');
say $dt;   # 2020-07-25T11:32:31

# Parse a time-only string
my $time = DateTime::Format::ISO8601->parse_time('113231');
say $time; # 11:32:31

# Use object with base_datetime
my $base = DateTime->new(year => 2020, month => 1, day => 1);
my $fmt = DateTime::Format::ISO8601->new(base_datetime => $base);
$dt = $fmt->parse_datetime('--03-15');  # fills year from base
say $dt;   # 2020-03-15T00:00:00

# Format
say DateTime::Format::ISO8601->format_datetime($dt); # 2020-03-15T00:00:00
## Formats

### Supported via `parse_datetime`

**Dates (ISO 8601:2000 5.2):**
- `YYYYMMDD`, `YYYY-MM-DD`, `YYYY-MM`, `YYYY`, `YY`
- Reduced precision: `-YYMM`, `-YY-MM`, `-YY`, `--MMDD`, `--MM-DD`, `--MM`, `---DD`
- Expanded: `+[YY]YYYYMMDD`, `+[YY]YYYY-MM-DD`
- Ordinal: `YYYYDDD`, `YYYY-DDD`, `YYDDD`, `YY-DDD`, `-DDD`
- Week: `YYYYWwwD`, `YYYY-Www-D`, `YYYYWww`, `YYYY-Www`, `YYWwwD`, `YY-Www-D`, `YYWww`, `YY-Www`, `-YWwwD`, `-Y-Www-D`, `-YWww`, `-Y-Www`, `-WwwD`, `-Www-D`, `-Www`, `-W-D`

**Time of day (5.3):**
- `hh:mm:ss`, `hh:mm`, `hhmmss,ss`, `hh:mm:ss,ss`, `hhmm,mm`, `hh:mm,mm`, `hh,hh`
- Reduced: `-mm:ss`, `-mmss,s`, `-mm:ss,s`, `-mm,m`, `--ss,s`
- Timezone: `hhmmssZ`, `hh:mm:ssZ`, `hhmmZ`, `hh:mmZ`, `hhZ`, `hhmmss.ssZ`, `hh:mm:ss.ssZ`
- Timezone offset: `hhmmss[+-]hhmm`, `hh:mm:ss[+-]hh:mm`, `hhmmss[+-]hh`, `hh:mm:ss[+-]hh`, `hhmmss.ss[+-]hhmm`, `hh:mm:ss.ss[+-]hh:mm`

**Combinations (5.4):**
- `YYYYMMDDThhmmss`, `YYYY-MM-DDThh:mm:ss`, with Z or offset
- `YYYYMMDDThhmmss.ss`, `YYYY-MM-DDThh:mm:ss.ss`, with offset
- `YYYYMMDDThhmm`, `YYYY-MM-DDThh:mm`, with Z or offset; also `YYYYDDDThhmm`, `YYYY-DDDThh:mm`, `YYYYWwwDThhmm[+-]hhmm`, `YYYY-Www-DThh:mm[+-]hh`

### Supported via `parse_time`

- `hhmmss`, `hhmm`, `hh`
- Reduced: `-mmss`, `-mm`, `--ss`

## See Also

- [DateTime](https://metacpan.org/pod/DateTime)
- [DateTime::Format::Builder](https://metacpan.org/pod/DateTime::Format::Builder)