# man > Date::Manip::Date

---
type: CommandReference
command: Date::Manip::Date
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference

- `$date = new Date::Manip::Date;` — create a new date object
- `$date->parse($string)` — parse a date/time string, stores result in object
- `$date->calc($delta)` — add a delta to the date, returns new date
- `$date->cmp($date2)` — compare two dates, returns -1, 0, or 1
- `$date->printf($format)` — format date using printf directives
- `$date->convert($zone)` — convert date to a different time zone
- `$date->set('date', [Y,M,D,H,MN,S])` — explicitly set date fields
- `$date->value()` — return date as string (YYYYMMDDHH:MN:SS) or list

## Name

Date::Manip::Date — Methods for working with dates

## Synopsis

perl
use Date::Manip::Date;
$date = new Date::Manip::Date;
## Methods

### `new`
- `$date = new Date::Manip::Date;` — create a new date object (inherits from `Date::Manip::Obj`)

### `parse`
- `$err = $date->parse($string [, @opts]);` — parse a date/time string. Returns error (0 on success). Options: `noiso8601`, `nodow`, `nocommon`, `noother`, `nospecial`, `nodelta`, `noholidays`.

### `parse_date`
- `$err = $date->parse_date($string [, @opts]);` — parse only the date part, leaving time unchanged (defaults to 00:00:00 if no date existed).

### `parse_time`
- `$err = $date->parse_time($string [, @opts]);` — parse only the time part, leaving date unchanged. Options: `noiso8601`, `noother`.

### `parse_format`
- `$err = $date->parse_format($format, $string);` — parse date using a custom format string with printf-like directives. In list context, returns `($err, %match)` where `%match` includes named capture groups.

### `calc`
- `$date2 = $date->calc($delta [, $subtract]);` — add a delta to date, returns new date.
- `$delta = $date->calc($date2 [, $subtract, $mode]);` — compute delta between two dates. See [Date::Manip::Calc](https://metacpan.org/pod/Date::Manip::Calc).

### `cmp`
- `$val = $date1->cmp($date2);` — compare two dates. Returns -1, 0, 1 (handles time zones).

### `complete`
- `$flag = $date->complete([$field]);` — test if date is complete (all fields specified). `$field` can be `m`, `d`, `h`, `mn`, `s` to check individual fields.

### `convert`
- `$err = $date->convert([$zone]);` — convert date to another time zone (defaults to local time zone).

### `holiday`
- `$name = $date->holiday();` — return holiday name if date is a holiday, else undef. In list context returns all holidays for that date.

### `event`
- `$name = $date->event();` — same as `holiday`.

### `is_business_day`
- `$flag = $date->is_business_day([$checktime]);` — return 1 if date is a business day. If `$checktime` is non-zero, also checks if time falls within work hours.

### `list_holidays`
- `@date = $date->list_holidays([$y]);` — return list of Date objects for all holidays in year `$y` (defaults to year of current date or current year).

### `list_events`
- `@list = $date->list_events([$format]);` — return list of events defined in config. Formats: default returns array of `[START, END, NAME]`; `"dates"` format returns `[DATE, NAME1, NAME2, ...]`.

### `nearest_business_day`
- `$date->nearest_business_day([$tomorrowfirst]);` — adjust date to nearest business day. If `$tomorrowfirst` is non-zero, look forward first.

### `next_business_day`
- `$date->next_business_day($off [, $checktime]);` — set date to `$off` business days in the future. If current date is not a business day, moves to next business day first.

### `prev_business_day`
- `$date->prev_business_day($off [, $checktime]);` — set date to `$off` business days in the past. Note: if current date is not a business day, it moves forward (same as `next_business_day`).

### `prev` / `next`
- `$err = $date->prev($dow, $curr [, $time]);` — set date to previous occurrence of day-of-week `$dow` (1=Mon, 7=Sun). `$curr` controls whether current day counts. `$time` is `[H, MN, S]`.
- `$err = $date->next($dow, $curr [, $time]);` — same as `prev` but next occurrence.
- `$err = $date->prev(undef, $curr, $time);` — set to previous occurrence of a specific time (with optional undefined fields).

### `printf`
- `$out = $date->printf($in);` — format string with printf directives (see below). Also accepts a list of strings.

### `secs_since_1970_GMT`
- `$secs = $date->secs_since_1970_GMT();` — return seconds since epoch in GMT.
- `$err = $date->secs_since_1970_GMT($secs);` — set date from epoch seconds.

### `set`
- `$err = $date->set($field, @vals [, $isdst]);` — set one or more fields. `$field` can be: `zone`, `zdate`, `date`, `time`, `y`, `m`, `d`, `h`, `mn`, `s`. `@vals` depend on field. `$isdst` optional (0/1).

### `value`
- `$val = $date->value([$type]);` — return date as string (YYYYMMDDHH:MN:SS) in scalar context, or list `(Y,M,D,H,MN,S)` in list context. `$type` can be `"local"` or `"gmt"`.

### `week_of_year`
- `$wkno = $date->week_of_year([$first]);` — return week number (0-53). `$first` is first day of week (1-7). Prefer using `printf` with `%W`, `%U`, `%J`, `%L`.

### `input`
- `$str = $date->input();` — return the original parsed string.

### `err`
- See `Date::Manip::Obj` for `err` method to get error messages.

### `base`, `config`, `tz`
- Inherited from `Date::Manip::Obj`. See [Date::Manip::Obj](https://metacpan.org/pod/Date::Manip::Obj).

## Printf Directives

| Directive | Description | Example |
|-----------|-------------|---------|
| `%y` | year (00-99) | 21 |
| `%Y` | year (0001-9999) | 2021 |
| `%m` | month (01-12) | 11 |
| `%f` | month ( 1-12) | 11 |
| `%b`, `%h` | month abbreviation | Nov |
| `%B` | month name | November |
| `%j` | day of year (001-366) | 324 |
| `%d` | day of month (01-31) | 20 |
| `%e` | day of month ( 1-31) | 20 |
| `%a` | weekday abbreviation | Sat |
| `%A` | weekday name | Saturday |
| `%w` | day of week (1=Mon) | 6 |
| `%E` | day with suffix | 20th |
| `%H` | hour (00-23) | 14 |
| `%k` | hour ( 0-23) | 14 |
| `%I` | hour (01-12) | 02 |
| `%i` | hour ( 1-12) | 2 |
| `%p` | AM or PM | PM |
| `%M` | minute (00-59) | 30 |
| `%S` | second (00-59) | 05 |
| `%Z` | time zone abbreviation | EST |
| `%z` | GMT offset (+0500) | +0500 |
| `%N` | GMT offset (+01:00:00) | +01:00:00 |
| `%s` | seconds since epoch (GMT) | 1637400000 |
| `%o` | seconds since epoch (local) | 1637400000 |
| `%c` | `%a %b %e %H:%M:%S %Y` | Sat Nov 20 14:30:05 2021 |
| `%C`, `%u` | `%a %b %e %H:%M:%S %Z %Y` | Sat Nov 20 14:30:05 EST 2021 |
| `%g` | `%a, %d %b %Y %H:%M:%S %Z` | Sat, 20 Nov 2021 14:30:05 EST |
| `%D` | `%m/%d/%y` | 11/20/21 |
| `%x` | `%m/%d/%y` or `%d/%m/%y` (depends on `DateFormat`) | 11/20/21 |
| `%l` | ls format (`%b %e %H:%M` or `%b %e  %Y`) | Nov 20 14:30 |
| `%r` | `%I:%M:%S %p` | 02:30:05 PM |
| `%R` | `%H:%M` | 14:30 |
| `%T`, `%X` | `%H:%M:%S` | 14:30:05 |
| `%V` | `%m%d%H%M%y` | 1120143021 |
| `%Q` | `%Y%m%d` | 20211120 |
| `%q` | `%Y%m%d%H%M%S` | 20211120143005 |
| `%P` | `%Y%m%d%H:%M:%S` | 2021112014:30:05 |
| `%O` | `%Y-%m-%dT%H:%M:%S` | 2021-11-20T14:30:05 |
| `%F` | `%A, %B %e, %Y` | Saturday, November 20, 2021 |
| `%K` | `%Y-%j` | 2021-324 |
| `%G` | year (Monday week) | 2021 |
| `%W` | week of year (Monday start, 01-53) | 46 |
| `%L` | year (Sunday week) | 2021 |
| `%U` | week of year (Sunday start, 01-53) | 46 |
| `%J` | `%G-W%W-%w` | 2021-W46-6 |
| `%n` | newline | |
| `%t` | tab | |
| `%%` | percent | % |
| `%+` | plus | + |
| `%<A=N>` | Nth weekday name | Saturday (N=6) |
| `%<a=N>` | Nth weekday abbreviation | Sat (N=6) |
| `%<v=N>` | Nth weekday single char | S (N=6) |
| `%<B=N>` | Nth month name | November (N=11) |
| `%<b=N>` | Nth month abbreviation | Nov (N=11) |
| `%<p=N>` | Nth AM/PM | PM (N=2) |
| `%<E=N>` | Nth day with suffix | 20th (N=20) |

## Valid Date Formats

[Date::Manip](https://metacpan.org/pod/Date::Manip) supports ISO 8601, common formats (e.g., M/D/Y, mmm D YYYY), less common formats (e.g., "next Friday", "last day in October"), and special strings (today, tomorrow, yesterday). See the full documentation for details.

## Valid Time Formats

ISO 8601 times (HH:MN:SS, HH:MN, etc.), other formats (H12:MN:SS AM, fractional hours), and special strings (noon, midnight). Time zone can be specified by name, abbreviation, or offset.

## See Also

- [Date::Manip](https://metacpan.org/pod/Date::Manip) — main module documentation
- [Date::Manip::Obj](https://metacpan.org/pod/Date::Manip::Obj) — base class methods
- [Date::Manip::Calc](https://metacpan.org/pod/Date::Manip::Calc) — date calculations
- [Date::Manip::Delta](https://metacpan.org/pod/Date::Manip::Delta) — delta objects
- [Date::Manip::Zones](https://metacpan.org/pod/Date::Manip::Zones) — time zone definitions
- [Date::Manip::Holidays](https://metacpan.org/pod/Date::Manip::Holidays) — holiday configuration
- [Date::Manip::Config](https://metacpan.org/pod/Date::Manip::Config) — configuration variables
- [Date::Manip::TZ](https://metacpan.org/pod/Date::Manip::TZ) — time zone methods

## Notes

- Fractional seconds are ignored.
- The date is always stored in the time zone it was parsed in. Use `convert` to change.
- Truncated dates default missing fields: day=1, month=1, time=00:00:00.
- Two-digit years are converted using the `YYtoYYYY` config variable.
- Holidays can be parsed as date strings.