Struct YmdHms 

pub struct YmdHms { /* private fields */ }

Combined date + time object.

Has calendar aware and, when the jiff-tz feature is enabled, timezone aware math functions.

Examples

Creating a YmdHms.

use deep_time::{Dt, Scale};

// clamped to 29
let x = Dt::from_ymd(2000, 2, 30, Scale::UTC, 0, 0, 0, 0).to_ymd();

assert_eq!(x.day(), 29);

Adding a year. 2000 is a leap year and Feb. 29th is possible, but 2001 isn’t a leap year so the day is clamped to the 28th.

use deep_time::{Dt, Scale};

let x = Dt::from_ymd(2000, 2, 29, Scale::UTC, 0, 0, 0, 0).to_ymd();
let x = x.add_yr(1);

assert_eq!(x.day(), 28);

Implementations

impl YmdHms

pub const fn new( yr: i64, mo: u8, day: u8, scale: Scale, hr: u8, min: u8, sec: u8, attos: u64, ) -> YmdHms

Create a new YmdHms, wrapper around Dt::from_ymd.

pub const fn to_dt(&self) -> Dt

Returns the Dt that was used to make this YmdHms object.

pub const fn add_yr(&self, n: i64) -> Self

Adds (or subtracts) whole years, preserving month and day-of-month.

• Uses standard last-day-of-month clamping.
• Negative values subtract.

pub const fn add_mo(&self, n: i64) -> Self

Adds (or subtracts) calendar months. Negative values subtract.

pub const fn add_wk(&self, n: i64) -> Self

Adds (or subtracts) calendar weeks. Negative values subtract.

pub const fn add_days(&self, n: i64) -> Self

Adds (or subtracts) calendar days. Negative values subtract.

pub const fn add_attos(&self, n: i128) -> Self

Adds (or subtracts) attoseconds. Negative values subtract.

pub const fn add_sec(&self, n: i64) -> Self

Adds (or subtracts) whole seconds. Negative values subtract.

pub const fn add_min(&self, n: i64) -> Self

Adds (or subtracts) whole minutes. Negative values subtract.

pub const fn add_hr(&self, n: i64) -> Self

Adds (or subtracts) whole hours. Negative values subtract.

pub const fn yr(&self) -> i64

Returns the year component.

pub const fn mo(&self) -> u8

Returns the month component (1–12).

pub const fn day(&self) -> u8

Returns the day-of-month component (1–31, depending on month/year).

Examples found in repository

examples/readme.rs (line 105)

fn main() -> Result<(), DtErr> {
    // ============================================
    // Parsing
    // ============================================

    // Smart auto-parsing (multi-language + timezone)
    let cfg = ParseCfg {
        lang: Lang::Fr,
        ..Default::default()
    };
    let dt = Dt::from_str_parse("15 août 2024 à 14:30 [Europe/Paris]", &cfg)?;
    let s = dt.to_str_rfc9557("Europe/Paris")?;
    assert_eq!("2024-08-15T14:30:00+02:00[Europe/Paris]", s);

    // or with .parse
    let dt: Dt = "1 jan 2000 07:00 [America/New_York] TAI".parse()?; // noon
    assert_eq!(Dt::ZERO, dt);

    // Relative dates are also supported
    let ref_time = Dt::from_ymd(2026, 6, 16, Scale::UTC, 12, 0, 0, 0);
    let en_cfg = ParseCfg {
        ref_time: Some(ref_time),
        ..Default::default()
    };

    let dt = Dt::from_str_parse("2 days from now at 9am", &en_cfg)?;
    assert_eq!(dt, Dt::from_ymd(2026, 6, 18, Scale::UTC, 9, 0, 0, 0));

    let dt = Dt::from_str_parse("next Monday at 14:00", &en_cfg)?;
    assert_eq!(dt, Dt::from_ymd(2026, 6, 22, Scale::UTC, 14, 0, 0, 0));

    // Relative dates use Dt::now if the `std` feature is enabled and no
    // ref_time is provided in the ParseCfg
    let _ = Dt::from_str_parse("next Monday at 14:00", &ParseCfg::DEFAULT)?;

    // Fast ISO parsing with time scale and no alloc output
    let dt = Dt::from_str_iso("2000-01-01T12:00:00 TAI")?;
    let lite_str: LiteStr<512> = dt.to_str_lite_iso8601()?;
    assert_eq!("2000-01-01T12:00:00+00:00", lite_str.as_str());

    // ============================================
    // Formatting
    // ============================================

    let s = dt.to_str_in_tz("%A, %d %B %Y %I:%M%P", "America/New_York", Lang::En)?;
    assert_eq!("Saturday, 01 January 2000 07:00am", s);

    let s = dt.to_str_in_tz("%A, %-d de %B de %Y %H:%M", "America/New_York", Lang::Es)?;
    assert_eq!("Sábado, 1 de enero de 2000 07:00", s);

    // ============================================
    // Duration parsing
    // ============================================

    let span: Dt = Dt::from_str_duration("3 days 12 hours", Lang::En)?;
    let dur = span.to_str_lite_media_duration();
    assert_eq!("3:12:00:00", dur.to_string());

    // ============================================
    // Time scale conversions + round-tripping
    // ============================================

    let dt = Dt::from_ymd(2000, 1, 1, Scale::TAI, 0, 0, 0, 123456789);
    let tt = dt.to(Scale::TT);
    let tdb = tt.to(Scale::TDB);
    let ltc = tdb.to(Scale::LTC);
    let utc = ltc.to(Scale::UTC);
    let tcl = utc.to(Scale::TCL);
    let tcg = tcl.to(Scale::TCG);
    let tai = tcg.to_tai();

    // round trips work for pretty much everything except UTCHist
    assert_eq!(dt, tai);
    let ymd: YmdHms = tai.to_ymd();
    assert_eq!(ymd.attos(), 123456789);

    // ============================================
    // Other conversions
    // ============================================

    // unix
    let dt = Dt::from_ymd(1970, 1, 1, Scale::UTC, 0, 0, 0, 0);
    let unix = dt.to_unix().to_sec_f();
    assert_eq!(unix, 0.0);

    // or to milliseconds
    let unix: i128 = dt.add_ms(1000).to_unix().to_ms();
    assert_eq!(unix, 1000);

    // to and from jd
    let jd = Dt::ZERO.to_jd_f();
    assert_eq!(2451545.0, jd);
    let dt = Dt::from_jd_f(jd, Scale::TAI);
    assert_eq!(0, dt.attos);

    // ============================================
    // Calendar math
    // ============================================

    // calendar math and negative year
    let dt = Dt::from_ymd(-2000, 1, 31, Scale::TAI, 12, 0, 0, 0);
    let ymd = dt.add_mo(1).to_ymd();
    assert_eq!(ymd.day(), 29);

    // Timezone-aware calendar math (respects DST transitions, requires jiff-tz feature)
    let dt = Dt::from_str_iso("2025-03-30T00:30:00Z")?; // Just before London DST start

    // Normal (naive) addition — ignores DST rules
    let normal = dt.add_hr(1);

    // Timezone-aware addition — correctly handles the transition
    let aware = dt.add_hr_tz(1, "Europe/London")?;

    println!("Normal: {}", normal.to_str_rfc9557("Europe/London")?);
    println!("Aware:  {}", aware.to_str_rfc9557("Europe/London")?);

    // ============================================
    // Leap seconds
    // ============================================

    // genuine leap second input round trips
    let dt: Dt = "2015-06-30T23:59:60".parse()?;
    let s = dt.to_str_iso8601();
    assert_eq!("2015-06-30T23:59:60+00:00", s);

    Ok(())
}

pub const fn hr(&self) -> u8

Returns the hour component (0–23).

pub const fn min(&self) -> u8

Returns the minute component (0–59).

pub const fn sec(&self) -> u8

Returns the second component (0–60). The value 60 only occurs during a positive leap second on Scale::UTC / UtcSpice / UtcHist.

pub const fn attos(&self) -> u64

Returns the attosecond (sub-second) component (0 ≤ attos < 10¹⁸).

Examples found in repository

examples/readme.rs (line 77)

fn main() -> Result<(), DtErr> {
    // ============================================
    // Parsing
    // ============================================

    // Smart auto-parsing (multi-language + timezone)
    let cfg = ParseCfg {
        lang: Lang::Fr,
        ..Default::default()
    };
    let dt = Dt::from_str_parse("15 août 2024 à 14:30 [Europe/Paris]", &cfg)?;
    let s = dt.to_str_rfc9557("Europe/Paris")?;
    assert_eq!("2024-08-15T14:30:00+02:00[Europe/Paris]", s);

    // or with .parse
    let dt: Dt = "1 jan 2000 07:00 [America/New_York] TAI".parse()?; // noon
    assert_eq!(Dt::ZERO, dt);

    // Relative dates are also supported
    let ref_time = Dt::from_ymd(2026, 6, 16, Scale::UTC, 12, 0, 0, 0);
    let en_cfg = ParseCfg {
        ref_time: Some(ref_time),
        ..Default::default()
    };

    let dt = Dt::from_str_parse("2 days from now at 9am", &en_cfg)?;
    assert_eq!(dt, Dt::from_ymd(2026, 6, 18, Scale::UTC, 9, 0, 0, 0));

    let dt = Dt::from_str_parse("next Monday at 14:00", &en_cfg)?;
    assert_eq!(dt, Dt::from_ymd(2026, 6, 22, Scale::UTC, 14, 0, 0, 0));

    // Relative dates use Dt::now if the `std` feature is enabled and no
    // ref_time is provided in the ParseCfg
    let _ = Dt::from_str_parse("next Monday at 14:00", &ParseCfg::DEFAULT)?;

    // Fast ISO parsing with time scale and no alloc output
    let dt = Dt::from_str_iso("2000-01-01T12:00:00 TAI")?;
    let lite_str: LiteStr<512> = dt.to_str_lite_iso8601()?;
    assert_eq!("2000-01-01T12:00:00+00:00", lite_str.as_str());

    // ============================================
    // Formatting
    // ============================================

    let s = dt.to_str_in_tz("%A, %d %B %Y %I:%M%P", "America/New_York", Lang::En)?;
    assert_eq!("Saturday, 01 January 2000 07:00am", s);

    let s = dt.to_str_in_tz("%A, %-d de %B de %Y %H:%M", "America/New_York", Lang::Es)?;
    assert_eq!("Sábado, 1 de enero de 2000 07:00", s);

    // ============================================
    // Duration parsing
    // ============================================

    let span: Dt = Dt::from_str_duration("3 days 12 hours", Lang::En)?;
    let dur = span.to_str_lite_media_duration();
    assert_eq!("3:12:00:00", dur.to_string());

    // ============================================
    // Time scale conversions + round-tripping
    // ============================================

    let dt = Dt::from_ymd(2000, 1, 1, Scale::TAI, 0, 0, 0, 123456789);
    let tt = dt.to(Scale::TT);
    let tdb = tt.to(Scale::TDB);
    let ltc = tdb.to(Scale::LTC);
    let utc = ltc.to(Scale::UTC);
    let tcl = utc.to(Scale::TCL);
    let tcg = tcl.to(Scale::TCG);
    let tai = tcg.to_tai();

    // round trips work for pretty much everything except UTCHist
    assert_eq!(dt, tai);
    let ymd: YmdHms = tai.to_ymd();
    assert_eq!(ymd.attos(), 123456789);

    // ============================================
    // Other conversions
    // ============================================

    // unix
    let dt = Dt::from_ymd(1970, 1, 1, Scale::UTC, 0, 0, 0, 0);
    let unix = dt.to_unix().to_sec_f();
    assert_eq!(unix, 0.0);

    // or to milliseconds
    let unix: i128 = dt.add_ms(1000).to_unix().to_ms();
    assert_eq!(unix, 1000);

    // to and from jd
    let jd = Dt::ZERO.to_jd_f();
    assert_eq!(2451545.0, jd);
    let dt = Dt::from_jd_f(jd, Scale::TAI);
    assert_eq!(0, dt.attos);

    // ============================================
    // Calendar math
    // ============================================

    // calendar math and negative year
    let dt = Dt::from_ymd(-2000, 1, 31, Scale::TAI, 12, 0, 0, 0);
    let ymd = dt.add_mo(1).to_ymd();
    assert_eq!(ymd.day(), 29);

    // Timezone-aware calendar math (respects DST transitions, requires jiff-tz feature)
    let dt = Dt::from_str_iso("2025-03-30T00:30:00Z")?; // Just before London DST start

    // Normal (naive) addition — ignores DST rules
    let normal = dt.add_hr(1);

    // Timezone-aware addition — correctly handles the transition
    let aware = dt.add_hr_tz(1, "Europe/London")?;

    println!("Normal: {}", normal.to_str_rfc9557("Europe/London")?);
    println!("Aware:  {}", aware.to_str_rfc9557("Europe/London")?);

    // ============================================
    // Leap seconds
    // ============================================

    // genuine leap second input round trips
    let dt: Dt = "2015-06-30T23:59:60".parse()?;
    let s = dt.to_str_iso8601();
    assert_eq!("2015-06-30T23:59:60+00:00", s);

    Ok(())
}

pub const fn time_scale(&self) -> Scale

The time scale that the object was created on.

pub const fn iso_yr(&self) -> i64

Returns the ISO week year (can differ from the calendar year near January 1 / December 31).

pub const fn iso_wk(&self) -> u8

Returns the ISO week number (1–53). Weeks start on Monday; week 1 is the week containing the first Thursday of the year.

pub const fn day_of_yr(&self) -> u16

Returns the day of the year (ordinal date), 1-based (Jan 1 = 1, Dec 31 = 365 or 366 in leap years).

pub const fn wkday(&self) -> u8

Returns the weekday number according to Dt::jd_to_wkday (typically 0 = Sunday … 6 = Saturday; exact convention is defined by the Julian Day helper).

pub const fn wk_of_yr_sun(&self) -> u8

Returns the week of year number when weeks are considered to start on Sunday (US-style numbering).

pub const fn wk_of_yr_mon(&self) -> u8

Returns the week of year number when weeks are considered to start on Monday.

impl YmdHms

pub fn add_yr_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr>

Adds the given number of years in the specified IANA timezone, respecting timezone rules (including DST) and proper calendar arithmetic.

Errors

• Jiff only supports years in the range -9999..=9999. Years outside this range will return a DtErr.
• If Jiff cannot find the timezone name or if applying the timezone would cause the jiff::Zoned to be outside the -9999..=9999 year range then a DtErr with DtErrKind::InvalidTimezoneOffset is returned.

pub fn add_mo_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr>

Adds the given number of months in the specified IANA timezone, respecting timezone rules and calendar month-end clamping.

Errors

• Jiff only supports years in the range -9999..=9999. Years outside this range will return a DtErr.
• If Jiff cannot find the timezone name or if applying the timezone would cause the jiff::Zoned to be outside the -9999..=9999 year range then a DtErr with DtErrKind::InvalidTimezoneOffset is returned.

pub fn add_wk_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr>

Adds the given number of weeks in the specified IANA timezone.

Errors

• Jiff only supports years in the range -9999..=9999. Years outside this range will return a DtErr.
• If Jiff cannot find the timezone name or if applying the timezone would cause the jiff::Zoned to be outside the -9999..=9999 year range then a DtErr with DtErrKind::InvalidTimezoneOffset is returned.

pub fn add_days_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr>

Adds the given number of calendar days in the specified IANA timezone.

Errors

• Jiff only supports years in the range -9999..=9999. Years outside this range will return a DtErr.
• If Jiff cannot find the timezone name or if applying the timezone would cause the jiff::Zoned to be outside the -9999..=9999 year range then a DtErr with DtErrKind::InvalidTimezoneOffset is returned.

pub fn add_hr_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr>

Adds the given number of hours in the specified IANA timezone, respecting timezone rules (including DST).

Errors

• Jiff only supports years in the range -9999..=9999. Years outside this range will return a DtErr.
• If Jiff cannot find the timezone name or if applying the timezone would cause the jiff::Zoned to be outside the -9999..=9999 year range then a DtErr with DtErrKind::InvalidTimezoneOffset is returned.

pub fn add_min_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr>

Adds the given number of minutes in the specified IANA timezone, respecting timezone rules (including DST).

Errors

• Jiff only supports years in the range -9999..=9999. Years outside this range will return a DtErr.
• If Jiff cannot find the timezone name or if applying the timezone would cause the jiff::Zoned to be outside the -9999..=9999 year range then a DtErr with DtErrKind::InvalidTimezoneOffset is returned.

pub fn add_sec_tz(&self, n: i64, tz: &str) -> Result<Self, DtErr>

Adds the given number of seconds in the specified IANA timezone.

Errors

• Jiff only supports years in the range -9999..=9999. Years outside this range will return a DtErr.
• If Jiff cannot find the timezone name or if applying the timezone would cause the jiff::Zoned to be outside the -9999..=9999 year range then a DtErr with DtErrKind::InvalidTimezoneOffset is returned.

Trait Implementations

impl Clone for YmdHms

fn clone(&self) -> YmdHms

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for YmdHms

impl Debug for YmdHms

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for YmdHms

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for YmdHms

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

Formats the value using the given formatter.

impl Eq for YmdHms

impl Hash for YmdHms

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for YmdHms

fn eq(&self, other: &YmdHms) -> 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 Serialize for YmdHms

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for YmdHms

impl Tsify for YmdHms

const DECL: &'static str = "/**\n * Combined date + time object.\n *\n * Has calendar aware and, when the `jiff-tz` feature is enabled,\n * timezone aware math functions.\n *\n * ## Examples\n *\n * **Creating a** [`YmdHms`].\n *\n * ```rust\n * use deep_time::{Dt, Scale};\n *\n * // clamped to 29\n * let x = Dt::from_ymd(2000, 2, 30, Scale::UTC, 0, 0, 0, 0).to_ymd();\n *\n * assert_eq!(x.day(), 29);\n * ```\n *\n * **Adding a year.** 2000 is a leap year and Feb. 29th is possible, but\n * 2001 isn\\\'t a leap year so the day is clamped to the 28th.\n *\n * ```rust\n * use deep_time::{Dt, Scale};\n *\n * let x = Dt::from_ymd(2000, 2, 29, Scale::UTC, 0, 0, 0, 0).to_ymd();\n * let x = x.add_yr(1);\n *\n * assert_eq!(x.day(), 28);\n * ```\n */\nexport interface YmdHms {\n yr: number;\n mo: number;\n day: number;\n hr: number;\n min: number;\n sec: number;\n attos: number;\n dt: Dt;\n}"

const SERIALIZATION_CONFIG: SerializationConfig

type JsType = JsType

fn into_js(&self) -> Result<Self::JsType, Error>

where Self: Serialize,

fn from_js<T>(js: T) -> Result<Self, Error>

where T: Into<JsValue>, Self: DeserializeOwned,