# man > Date::Manip::Recur

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

## Quick Reference

- `$recur = new Date::Manip::Recur;` — create a new recurrence object
- `$recur->parse($string, $modifiers, $base, $start, $end, $unmod);` — parse a frequency string with optional modifiers and dates
- `$recur->frequency($freq);` — set the frequency part (e.g. `"0:0:2*4:12:0:0"`)
- `$recur->start($start);` — set the start date of the range
- `$recur->end($end);` — set the end date of the range
- `@dates = $recur->dates($start, $end, $unmod);` — get all recurring dates in range
- `($date, $err) = $recur->nth($n);` — get the Nth recurring event (integer)
- `($date, $err) = $recur->next();` — get the next recurring event
- `($date, $err) = $recur->prev();` — get the previous recurring event

## Name

methods for working with recurring events

## Synopsis

perl
use Date::Manip::Recur;
$date = new Date::Manip::Recur;
## Options

### Methods

- `new` — create a new `Date::Manip::Recur` object. Optional arguments: `$config`, `$date`, `$delta`, `$recur`.
- `parse($string, $modifiers, $base, $start, $end, $unmod)` — parse a recurrence from a string. `$string` is a frequency; `$modifiers` is a comma-separated list; `$base`, `$start`, `$end` are dates; `$unmod` (boolean) applies range to unmodified dates.
- `frequency($freq)` — set the frequency. Erases all other recurrence data.
- `start($start, $unmod)` — set the start date. `$unmod` applies range to unmodified dates.
- `end($end)` — set the end date.
- `basedate($base)` — set the base date.
- `modifiers($modifiers)` or `modifiers(@modifiers)` — set modifiers. If first modifier is `"+"`, append to existing list.
- `dates($start, $end, $unmod)` — return list of all recurring dates in the range.
- `nth($n)` — return the Nth recurring event (integer). Errors: `Invalid recurrence`, `Incomplete recurrence`, `Range invalid`, `Start invalid`, `End invalid`, `Base invalid`, `Not found`.
- `next()` — return the next recurring event.
- `prev()` — return the previous recurring event.

### Modifiers

**Day-of-week modifiers:**

- `PDn` — previous day n (not counting today)
- `PTn` — previous day n (counting today)
- `NDn` — next day n (not counting today)
- `NTn` — next day n (counting today)
- `WDn` — day n (1-7, Sunday=1) of current week

**Forward/backward days:**

- `FDn` — step forward n days
- `BDn` — step backward n days

**Business day modifiers:**

- `FWn` — step forward n workdays
- `BWn` — step backward n workdays
- `CWD` — closest work day (using `TomorrowFirst` config)
- `CWN` — closest work day (looking forward first)
- `CWP` — closest work day (looking backward first)
- `NWD` — next work day counting today
- `PWD` — previous work day counting today
- `DWD` — closest work day (counting today, using `TomorrowFirst`)
- `IBD` — discard date if not a business day
- `NBD` — discard date if it is a business day
- `IWn` — discard date if not the nth day of week (1=Monday)
- `NWn` — discard date if it is the nth day of week

**Special modifier:**

- `EASTER` — set date to Easter for the current year

### Frequency Notation

The frequency is a colon-separated list: `Y:M:W:D:H:MN:S`. One colon may be replaced by an asterisk (`*`), or an asterisk may be prepended. The part left of the asterisk is the interval (delta), the part right is the rtime (specific values).

Examples:

- `0:0:0:2*12:30:0` — every 2 days at 12:30
- `1:2*3:4:0:0:0` — every 1 year, 2 months on the 3rd Thursday
- `*1990-1995:12:0:1:0:0:0` — Dec 1 in 1990 through 1995

Rtime fields can be single values, ranges (e.g. `2-4`), comma-separated lists, or negative values (e.g. `-1` for last). Multiple values in multiple fields produce all combinations.

Day-of-week values: 1=Monday, 7=Sunday (ISO 8601), regardless of `FirstDay` config.

When both week and day are non-zero: day refers to day-of-week. When week is zero and month non-zero: day is day-of-month (1-31 or -1 to -31). When month and week zero and year non-zero: day is day-of-year (1-366). When week non-zero and day zero: refers to first day of the week (as defined by `FirstDay`) in that week.

## Examples

perl
use Date::Manip::Recur;
use Date::Manip::Date;

my $recur = new Date::Manip::Recur;
$recur->parse("0:0:2*4:12:0:0");
$recur->start("2000-01-01-00:00:00");
$recur->end("2000-12-31-23:59:59");
my @dates = $recur->dates();
# @dates contains every other Thursday at noon in 2000

$recur->parse("0:1:0*-2:0:0:0");
# last day of every month

my ($date, $err) = $recur->nth(0);
# returns the 0th occurrence (base date)

$recur->parse("1*1:0:1:0:0:0*DWD");
$recur->start("2005-01-01-00:00:00");
$recur->end("2005-12-31-23:59:59");
$recur->modifiers("+", "DWD");
my @holidays = $recur->dates();
# New Year's Day observed (closest workday)
## See Also

[Date::Manip](http://localhost/phpMan.php/perldoc/Date%3A%3AManip/markdown) — main module documentation