Crate relativedelta 

Rust implementation of relativedelta known from Python’s dateutil library. Calculate dates by adding relative and offset values to a datetime instance. Currently, the time and chrono crates are supported.

Usage

Run cargo add relativedelta to add this crate to your project or put this in your Cargo.toml:

[dependencies]
relativedelta = "0.3"

Minimum Supported Rust Version (MSRV)

This crate supports Rust 1.85.0 or later.

Optional features

• chrono: Enable support for the chrono crate.
• time: Enable support for the time crate.
• serde: Enable serialization/deserialization via serde.

Overview

The RelativeDelta datatype holds both relative and absolute values for year, month, day, hour, minute, second and nanosecond.

Relative parts are manipulated and accessed through methods typically ending in “s” (e.g. ::with_years, .and_days). Absolute values without “s” (e.g. ::with_year, .and_day).

All relative values represents an offset to date and time and therefore can take on both positive and negative values, and can take on any value within its datatypes limitations. On construction, a Builder will attempt to aggregate values up, so e.g. if hours are not in the range [-23;23], the final instance will be updated to instead add or subtract extra days, with only the remainder as hours. All offsets are set to zero as default.

Absolute values represents an explicit year, month, day and so on. So if one e.g. always seeks a certain day in a month, one would use the ::with_day() or .and_day() method. All absolute values are Options and defaults to None.

RelativeDelta also holds a weekday value, which is an Option of a tuple with (Weekday, nth). This allows one to e.g. ask for the second tuesday one year from today, with Utc::now() + RelativeDelta::with_years(1).and_weekday(Some(Weekday::Tue, 2)).build().

Examples

Here are some examples of how to use the RelativeDelta library:

Basic Construction

Create a RelativeDelta representing 1 year:

let years1 = RelativeDelta::with_years(1).build();

Create a RelativeDelta representing 12 months (equivalent to 1 year):

let months12 = RelativeDelta::with_months(12).build();

Combining relative values:

let one_year_32_days = RelativeDelta::with_years(1).and_days(32).build();

If the same parameter is specified twice, only the latest is applied:

let months6 = RelativeDelta::with_months(12).and_months(6).build();

Combining absolute and relative values:

// Set year to 2020, add 1 year, set month to January, add 3 months, add 12 days
let complex = RelativeDelta::with_year(2020)
.and_years(1)
.and_month(Some(1))
.and_months(3)
.and_days(12)
.build();

Operations Between RelativeDelta Instances

Addition and subtraction (note that absolute values are lost in these operations):

let delta1 = RelativeDelta::with_years( - 4).and_months(3).build();
let delta2 = RelativeDelta::with_years(1).and_months(42).build();

// Addition
let sum = delta1 + delta2; // RelativeDelta::with_years(-3).and_months(45).build()

// Subtraction
let diff = delta1 - delta2; // RelativeDelta::with_years(-5).and_months(-39).build()

// Negation and addition
let neg_sum = - delta1 + delta2; // RelativeDelta::with_years(5).and_months(39).build()

Multiplication with a float:

let delta = RelativeDelta::with_years(4).and_months(6).build();
let half = delta * 0.5; // RelativeDelta::with_years(2).and_months(3).build()

Modifying an Existing RelativeDelta

Use the .builder() method to create a Builder from an existing RelativeDelta:

let original = RelativeDelta::with_years(1).build();
let modified = original.builder().and_months(6).and_days( - 5).build();

Using RelativeDelta with Datetime Libraries

With the chrono crate (requires the chrono feature):

use chrono;
// Get the last day of the current month
let last_day_of_month = chrono::Utc::now() + RelativeDelta::with_day(1)
.and_months(1)
.and_days(-1)
.build();
// Get the first Monday after one year from a specific date
let first_monday_after_one_year = chrono::Utc::now() + RelativeDelta::with_years(1)
.and_weekday(Some((Weekday::Mon, 1)))
.build();

With the time crate (requires the time feature):

use time;
// Add 1 year, 3 months, and 15 days to a date
let delta = RelativeDelta::with_years(1).and_months(3).and_days(15).build();
let result = time::UtcDateTime::now() + delta;
// Get the last day of a month
let last_day = time::UtcDateTime::now() + RelativeDelta::with_day(1)
.and_months(1)
.and_days(-1)
.build();

Working with Weekdays

Get the 3rd Tuesday of next month:

let third_tuesday_next_month = RelativeDelta::with_months(1)
.and_weekday(Some((Weekday::Tue, 3)))
.build();

Re-exports

pub use crate::weekday::Weekday;

pub use crate::relativedelta::RelativeDelta;

Modules

relativedelta

RelativeDelta is a relative date time representation for smart date calculations.

weekday

Weekday is a module that provides functionality for working with weekdays in the context of RelativeDelta.