Struct Event

pub struct Event { /* private fields */ }

Represents an event that happens at a given point in time and may span until an optional end datetime.

Single instant events can be created via Event::at, while Event::new and Event::try_new can be used to construct events with an explict end.

Example

use jiff::{ToSpan, civil::date};
use recurring::Event;

let start = date(2025, 1, 1).at(0, 0, 0, 0);
let end = date(2025, 1, 2).at(0, 0, 0, 0);
let event = Event::new(start, end);
assert_eq!(event.start(), start);
assert_eq!(event.end(), Some(end));
assert_eq!(event.duration().fieldwise(), 1.day());

Implementations

impl Event

pub fn at(instant: DateTime) -> Event

Creates a new Event which starts and ends at instant.

The event duration is effectively zero.

Example

use jiff::civil::date;
use recurring::Event;

let start = date(2025, 1, 1).at(0, 0, 0, 0);
let event = Event::at(start);

pub fn new(start: DateTime, end: DateTime) -> Event

Creates a new Event which spans from a start (inclusive) to an end (exclusive).

The fallible version of this method is Event::try_new.

Panics

Panics if start >= end.

Example

use jiff::civil::date;
use recurring::Event;

let start = date(2025, 1, 1).at(0, 0, 0, 0);
let end = date(2025, 1, 2).at(0, 0, 0, 0);
let event = Event::new(start, end);

pub fn try_new(start: DateTime, end: DateTime) -> Result<Event, Error>

Creates a new Event which spans from a start (inclusive) to an end (exclusive).

The panicking version of this method is Event::new.

Errors

Returns and Error if start >= end.

Example

use jiff::civil::date;
use recurring::Event;

let start = date(2025, 1, 1).at(0, 0, 0, 0);
let end = date(2025, 1, 2).at(0, 0, 0, 0);
let event = Event::try_new(start, end)?;

pub fn start(&self) -> DateTime

Returns the DateTime at which the event starts.

Example

use jiff::civil::date;
use recurring::Event;

let start = date(2025, 1, 1).at(0, 0, 0, 0);
let event = Event::at(start);
assert_eq!(event.start(), start);

pub fn end(&self) -> Option<DateTime>

Returns the DateTime at which the event ends if it has an end, None otherwise.

Example

use jiff::civil::date;
use recurring::Event;

let start = date(2025, 1, 1).at(0, 0, 0, 0);
let event = Event::at(start);
assert!(event.end().is_none());

let end = date(2025, 1, 2).at(0, 0, 0, 0);
let event = Event::new(start, end);
assert_eq!(event.end(), Some(end));

pub fn duration(&self) -> Span

Returns the duration between the events’ start and end.

For events that don’t have an end, this always returns a zero Span.

Example

use jiff::{ToSpan, civil::date};
use recurring::Event;

let start = date(2025, 1, 1).at(0, 0, 0, 0);
let event = Event::at(start);
assert!(event.duration().is_zero());

let end = date(2025, 1, 2).at(0, 0, 0, 0);
let event = Event::new(start, end);
assert_eq!(event.duration().fieldwise(), 1.day());

pub fn contains(&self, instant: DateTime) -> bool

Returns true if instant falls within the events’ duration, false otherwise.

For events that don’t have an end, this is equivalent to event.start() == instant.

Example

use jiff::{ToSpan, civil::date};
use recurring::Event;

let start = date(2025, 1, 1).at(0, 0, 0, 0);
let event = Event::at(start);
assert!(!event.contains(start - 1.nanosecond()));
assert!(event.contains(start));
assert!(!event.contains(start + 1.nanosecond()));

let end = date(2025, 1, 2).at(0, 0, 0, 0);
let event = Event::new(start, end);
assert!(!event.contains(start - 1.nanosecond()));
assert!(event.contains(start));
assert!(event.contains(start + 1.nanosecond()));
assert!(event.contains(end - 1.nanosecond()));
assert!(!event.contains(end));
assert!(!event.contains(end + 1.nanosecond()));

Trait Implementations

impl Clone for Event

fn clone(&self) -> Event

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Event

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Event

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Ord for Event

fn cmp(&self, other: &Event) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Event

fn eq(&self, other: &Event) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Event

fn partial_cmp(&self, other: &Event) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl ToSeries for Event

fn to_series<P: Pattern>(&self, pattern: P) -> Result<Series<P>, Error>

Converts an Event to a Series with the given recurrence Pattern.

Errors

Returns an error if the event duration cannot be represented as a Span or if the events’ start is DateTime::MAX.

Example

use jiff::civil::date;
use recurring::{Event, ToSeries, pattern::hourly};

let date = date(2025, 1, 1);
let start = date.at(0, 0, 0, 0);
let end = date.at(0, 30, 0, 0);

let event = Event::new(start, end);
let series = event.to_series(hourly(2))?;

let mut events = series.iter();

assert_eq!(events.next(), Some(Event::new(date.at(0, 0, 0, 0), date.at(0, 30, 0, 0))));
assert_eq!(events.next(), Some(Event::new(date.at(2, 0, 0, 0), date.at(2, 30, 0, 0))));

impl Eq for Event

impl StructuralPartialEq for Event