## Expand description

## RRules

A blazing fast and memory efficient library to manage recurrence rules inspired by the standards from RFC-5547. It provides the ability to define recurrence rules for events, and then iterate over them to get the dates that match the recurrence rules.

### How to use it

The easiest way to use this library is to start by loading a Recurrence instance from a string following the standards:

#### Loading from string

##### Required attributes:

- FREQ
- Defines the type of frequency (E.g. DAILY, WEEKLY, MONTHLY, etc)

- INTERVAL
- Defines the interval of the frequency (E.g. every 2 days, every 3 months, etc)

- DTSTART
- Defines the start date of the recurrence

Examples:

```
// Daily recurrence example:
use std::str::FromStr;
use chrono::{DateTime, Utc};
use rrules::Recurrence;
let recurrence = Recurrence::from_str("FREQ=DAILY;INTERVAL=1;DTSTART=2023-01-01T12:00:00Z").unwrap();
// You can then use the `Recurrence` as an iterator by looping over it or collecting the results into a `Vec`
for event in recurrence.clone().take(100) { // cloning to avoid moving the iterator
// ...
}
// or
let events: Vec<DateTime<Utc>> = recurrence.take(100).collect();
```

The

`Recurrence`

struct is an iterator that will yield all the dates that match the recurrence rules defined.

#### How to use it with structs definition

To define a recurrence rule, start by creating the desired `frequency`

rule definition:

```
use chrono::{Duration, Utc};
use rrules::Frequency;
use rrules::Recurrence;
let daily = Frequency::Daily {
interval: 1,
by_time: vec![],
};
// Then, create a `Recurrence` with the frequency defined:
let recurrence = Recurrence::new(
daily,
Utc::now(), // start date
Some(Utc::now() + Duration::days(1)), // end date
Some(Duration::hours(1)), // duration (optional
);
```

The `end`

attribute of a `Recurrence`

is optional, and if not specified, it will yield events until the `MAX_DATE`

.

The

`MAX_DATE`

is defined as`9999-12-31T23:59:59Z`

The `duration`

attribute of a `Recurrence`

is optional, and if not specified, it will use the default as 0 seconds `Duration::seconds(0)`

.

### Attribute standards

Attribute | Description | Example |
---|---|---|

FREQ | Defines the type of frequency (E.g. DAILY, WEEKLY, MONTHLY, etc) | FREQ=DAILY |

INTERVAL | Defines the interval of the frequency (E.g. every 2 days, every 3 months, etc) | INTERVAL=2 |

DTSTART | Defines the start date of the recurrence | DTSTART=2023-01-01T12:00:00Z |

DTEND | Defines the end date of the recurrence | DTEND=2023-01-01T12:00:00Z |

DURATION | Defines the duration of the recurrence | DURATION=PT1H |

BYDAY | Defines the days of the week that the recurrence will happen | BYDAY=MO,TU -> When FREQ=WEEKLY; BYDAY=1MO,3WE -> When FREQ=MONTHLY |

BYMONTHDAY | Defines the days of the month that the recurrence will happen | BYMONTHDAY=1,2,3,4, etc |

BYMONTH | Defines the months of the year that the recurrence will happen | BYMONTH=1,2,3,4,5,6,7,8,9,10,11,12 |

### Supported recurrence rule types + examples

Current supporting recurrence rules:

#### Secondly Frequencies

Represents the rules for a recurrence that happens every x seconds.

```
use std::str::FromStr;
use rrules::Recurrence;
let every_second_recurrence = Recurrence::from_str(
"FREQ=SECONDLY;INTERVAL=1;DTSTART=2023-01-01T12:00:00Z"
).unwrap();
```

#### Minutely Frequencies

Represents the rules for a recurrence that happens every x minutes.

```
use std::str::FromStr;
use rrules::Recurrence;
let every_5_minutes = Recurrence::from_str(
"FREQ=MINUTELY;INTERVAL=5;DTSTART=2023-01-01T12:00:00Z"
).unwrap();
```

#### Hourly Frequencies

Represents the rules for a recurrence that happens every x hours.

```
use std::str::FromStr;
use rrules::Recurrence;
let every_6_hours = Recurrence::from_str(
"FREQ=HOURLY;INTERVAL=6;DTSTART=2023-01-01T12:00:00Z"
).unwrap();
```

#### Daily Frequencies

Represents the rules for a recurrence that happens x times every x days.

```
use std::str::FromStr;
use rrules::Recurrence;
let every_3_days = Recurrence::from_str(
"FREQ=DAILY;INTERVAL=3;DTSTART=2023-01-01T12:00:00Z"
).unwrap();
let every_day_at_8am = Recurrence::from_str(
"FREQ=DAILY;INTERVAL=1;DTSTART=2023-01-01T08:00:00Z"
).unwrap();
let every_other_day_at_12pm_and_16pm = Recurrence::from_str(
"FREQ=DAILY;INTERVAL=2;DTSTART=2023-01-01T00:00:00Z;BYTIME=12:00,16:00"
).unwrap();
```

#### Weekly Frequencies

Represents the rules for a recurrence that happens x times every x weeks.

```
use std::str::FromStr;
use rrules::Recurrence;
let every_week = Recurrence::from_str(
"FREQ=WEEKLY;INTERVAL=1;DTSTART=2023-01-01T12:00:00Z"
).unwrap();
let every_week_mon_and_tue = Recurrence::from_str(
"FREQ=WEEKLY;INTERVAL=1;DTSTART=2023-01-01T12:00:00Z;BYDAY=MO,TU"
).unwrap();
```

#### Monthly Frequencies

Represents the rules for a recurrence that happens x times every x months.

```
use std::str::FromStr;
use rrules::Recurrence;
let monthly = Recurrence::from_str(
"FREQ=MONTHLY;INTERVAL=1;DTSTART=2023-01-01T12:00:00Z"
).unwrap();
```

##### Monthly by month day

When specifying `BYMONTHDAY`

, it will only yield the dates that match the days of the month specified.

```
use std::str::FromStr;
use rrules::Recurrence;
let every_15th = Recurrence::from_str(
"FREQ=MONTHLY;INTERVAL=1;DTSTART=2023-01-01T12:00:00Z;BYMONTHDAY=15"
).unwrap();
let every_15th_and_25th = Recurrence::from_str(
"FREQ=MONTHLY;INTERVAL=1;DTSTART=2023-01-01T12:00:00Z;BYMONTHDAY=15,25"
).unwrap();
```

##### Monthly by nth day

When specifying `BYDAY`

, it will only yield the dates that match the nth days of the week specified.
I.g. if you want to have a recurrence every first Monday of the month, you can do:

```
use std::str::FromStr;
use rrules::Recurrence;
let every_first_monday = Recurrence::from_str(
"FREQ=MONTHLY;INTERVAL=1;DTSTART=2023-01-01T12:00:00Z;BYDAY=1MO"
).unwrap();
let every_first_monday_and_wednesday = Recurrence::from_str(
"FREQ=MONTHLY;INTERVAL=1;DTSTART=2023-01-01T12:00:00Z;BYDAY=1MO,1WE"
).unwrap();
```

#### Yearly Frequencies

Represents the rules for a recurrence that happens x times every x years.

```
use std::str::FromStr;
use rrules::Recurrence;
let yearly = Recurrence::from_str(
"FREQ=YEARLY;INTERVAL=1;DTSTART=2023-01-01T12:00:00Z"
).unwrap();
```

##### Yearly by month day

When specifying `BYMONTH`

and `BYMONTHDAY`

, it will only yield the dates that match the days of the month specified.
E.g. if you want to have a recurrence every 15th January of the year, you can do:

```
use std::str::FromStr;
use rrules::Recurrence;
let every_15th_january = Recurrence::from_str(
"FREQ=YEARLY;INTERVAL=1;DTSTART=2023-01-01T12:00:00Z;BYMONTH=1;BYMONTHDAY=15"
).unwrap();
```