<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from Time/Piece.rs. Do not edit. -->

```{index} single: Time::Piece
```

# Time::Piece

```{pperl-module-badges} Time::Piece
```

Date and time objects: `use Time::Piece` makes `localtime` and
`gmtime` return an object with accessors for every field, formatting
and parsing, comparison, and arithmetic with the durations of
`Time::Seconds`. In string context the object is still the familiar
`scalar localtime` text (`Tue Nov 14 22:13:20 2023`).

This is Time::Piece 1.41; `Time/Piece.pm` and `Time/Seconds.pm` are
upstream's. Formatting, parsing and the breaking down of an epoch run
natively; parsing (`strptime`) does not depend on the system's
library, so a format parses the same way everywhere.

## Synopsis

```perl
use Time::Piece;
use Time::Seconds;

my $t = gmtime(1_700_000_000);
print $t->ymd, ' ', $t->hms, "\n";              # 2023-11-14 22:13:20
print $t->year, ' ', $t->mon, ' ', $t->monname, "\n";   # 2023 11 Nov
print $t->strftime('%A, %d %B %Y'), "\n";       # Tuesday, 14 November 2023
print $t->epoch, "\n";                          # 1700000000

my $later = $t + ONE_DAY * 3;
print $later->ymd, "\n";                        # 2023-11-17
print +($later - $t)->days, " days\n";          # 3 days
print $t->add_months(3)->ymd, "\n";             # 2024-02-14

my $p = Time::Piece->strptime('2024-02-29 12:00', '%Y-%m-%d %H:%M');
print $p->is_leap_year ? "leap\n" : "common\n"; # leap
print $p > $t ? "later\n" : "earlier\n";        # later
```

## The interface

- **Making one** - `localtime($epoch)`, `gmtime($epoch)` (now without
  an argument), `Time::Piece->strptime($string, $format)`, and
  `Time::Piece->new($epoch)`.
- **Fields** - `sec`, `min`, `hour`, `mday` (`day_of_month`), `mon`
  (1-12), `_mon` (0-11), `monname`/`month`, `fullmonth`, `year`, `yy`,
  `wday` (1 = Sunday), `_wday` (0 = Sunday), `day_of_week`, `wdayname`,
  `fullday`, `yday` (`day_of_year`), `isdst`, `tzoffset`, `epoch`,
  `week` (ISO 8601), `julian_day`, `mjd`, `is_leap_year`,
  `month_last_day`.
- **Text** - `ymd`, `mdy`, `dmy`, `hms` (each with an optional
  separator), `datetime` (ISO 8601), `cdate`, `strftime($format)`.
- **Arithmetic** - `+` and `-` with seconds or a `Time::Seconds`
  (`ONE_DAY`, `ONE_WEEK`, `ONE_HOUR`, ...); two objects subtract to a
  `Time::Seconds` (`->days`, `->hours`, `->minutes`); `add_months`,
  `add_years`; `<`, `==`, `<=>` and `cmp` compare.
- **Locale** - `day_list`, `mon_list` and their `full` forms set or
  read the names `strftime` and `strptime` use;
  `Time::Piece::use_locale()` takes them from the current locale.

## Differences from upstream

None: upstream's tests pass unchanged
(t/81-xs-native/Time-Piece, the `upstream` files), and 010-050 there
check formatting, parsing and the field breakdown against perl 5.44.