hifitime

https://docs.rs/hifitime/latest/hifitime/
Admin
Hifitime is a powerful Rust and Python library designed for precise time management. It offers...
Tokens:162,496
Snippets:1,420
Trust Score:9.7
Update:6 days ago
Show doc for...
Tokens:
Raw
### next weekday example

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Shows how to get the next occurrence of a given weekday from a starting epoch. The example uses a Saturday epoch and asserts the next Sunday through Saturday dates.

```rust
use hifitime::prelude::*;

let epoch = Epoch::from_gregorian_utc_at_midnight(1988, 1, 2);
assert_eq!(epoch.weekday_utc(), Weekday::Saturday);
assert_eq!(epoch.next(Weekday::Sunday), Epoch::from_gregorian_utc_at_midnight(1988, 1, 3));
assert_eq!(epoch.next(Weekday::Monday), Epoch::from_gregorian_utc_at_midnight(1988, 1, 4));
assert_eq!(epoch.next(Weekday::Tuesday), Epoch::from_gregorian_utc_at_midnight(1988, 1, 5));
assert_eq!(epoch.next(Weekday::Wednesday), Epoch::from_gregorian_utc_at_midnight(1988, 1, 6));
assert_eq!(epoch.next(Weekday::Thursday), Epoch::from_gregorian_utc_at_midnight(1988, 1, 7));
assert_eq!(epoch.next(Weekday::Friday), Epoch::from_gregorian_utc_at_midnight(1988, 1, 8));
assert_eq!(epoch.next(Weekday::Saturday), Epoch::from_gregorian_utc_at_midnight(1988, 1, 9));
```

--------------------------------

### Example: floor method usage

Source: https://docs.rs/hifitime/latest/hifitime/struct.Duration.html

Example demonstrating the floor method on Duration, which floors the duration to the closest provided duration from the bottom. The example shows various assertions including flooring by a longer duration resulting in zero.

```rust
use hifitime::{Duration, TimeUnits};

let two_hours_three_min = 2.hours() + 3.minutes();
assert_eq!(two_hours_three_min.floor(1.hours()), 2.hours());
assert_eq!(two_hours_three_min.floor(30.minutes()), 2.hours());
// This is zero because we floor by a duration longer than the current duration, rounding it down
assert_eq!(two_hours_three_min.floor(4.hours()), 0.hours());
assert_eq!(two_hours_three_min.floor(1.seconds()), two_hours_three_min);
assert_eq!(two_hours_three_min.floor(1.hours() + 1.minutes()), 2.hours() + 2.minutes());
assert_eq!(two_hours_three_min.floor(1.hours() + 5.minutes()), 1.hours() + 5.minutes());
```

--------------------------------

### day_of_month example

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Shows how to get the day of the month from an Epoch using from_gregorian_tai_at_midnight and assert_eq.

```rust
use hifitime::Epoch;
let dt = Epoch::from_gregorian_tai_at_midnight(2025, 7, 3);
assert_eq!(dt.day_of_month(), 3);
```

--------------------------------

### TimeSeries::inclusive example

Source: https://docs.rs/hifitime/latest/hifitime/struct.TimeSeries.html

Creates a TimeSeries that is inclusive on both start and end. The example iterates from 2017-01-14 midnight to noon with a 2-hour step, printing each epoch and counting them. The assertion verifies that 7 epochs are produced.

```rust
use hifitime::{Epoch, Unit, TimeSeries};
let start = Epoch::from_gregorian_utc_at_midnight(2017, 1, 14);
let end = Epoch::from_gregorian_utc_at_noon(2017, 1, 14);
let step = Unit::Hour * 2;
let time_series = TimeSeries::inclusive(start, end, step);
let mut cnt = 0;
for epoch in time_series {
    println!("{}", epoch);
    cnt += 1
}
assert_eq!(cnt, 7)
```

--------------------------------

### Example: ceil method usage

Source: https://docs.rs/hifitime/latest/hifitime/struct.Duration.html

Example demonstrating the ceil method on Duration, which ceils the duration to the closest provided duration. The example shows various assertions including adding the requested duration when the current duration is not a multiple.

```rust
use hifitime::{Duration, TimeUnits};

let two_hours_three_min = 2.hours() + 3.minutes();
assert_eq!(two_hours_three_min.ceil(1.hours()), 3.hours());
assert_eq!(two_hours_three_min.ceil(30.minutes()), 2.hours() + 30.minutes());
assert_eq!(two_hours_three_min.ceil(4.hours()), 4.hours());
assert_eq!(two_hours_three_min.ceil(1.seconds()), two_hours_three_min + 1.seconds());
assert_eq!(two_hours_three_min.ceil(1.hours() + 5.minutes()), 2.hours() + 10.minutes());
```

--------------------------------

### precise_timescale_conversion example with GPST-UTC polynomials

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Shows forward and backward conversion between GPST and UTC using a polynomial correction. The reference epoch should be close to the target epoch (e.g., within a day) to minimize interpolation error. The example verifies the conversion by reversing it and adding a nanosecond correction.

```rust
use hifitime::{Epoch, TimeScale, Polynomial, Unit};

// random GPST Epoch for forward conversion to UTC
let t_gpst = Epoch::from_gregorian(2020, 01, 01, 0, 0, 0, 0, TimeScale::GPST);

// Let's say we know the GPST-UTC polynomials for that day,
// They allow precise forward transition from GPST to UTC,
// and precise backward transition from UTC to GPST.
let gpst_utc_polynomials = Polynomial::from_constant_offset_nanoseconds(1.0);

// This is the reference [Epoch] attached to the publication of these polynomials.
// You should use polynomials that remain valid and were provided recently (usually one day at most).
// Example: polynomials were published 1 hour ago.
let gpst_reference = t_gpst - 1.0 * Unit::Hour;

// Forward conversion (to UTC) GPST - a0 + a1 *dt + a2*dt² = UTC
let t_utc = t_gpst.precise_timescale_conversion(true, gpst_reference, gpst_utc_polynomials, TimeScale::UTC)
    .unwrap();

// Verify we did transition to UTC
assert_eq!(t_utc.time_scale, TimeScale::UTC);

// Verify the resulting [Epoch] is the coarse GPST->UTC transition + fine correction
let reversed = t_utc.to_time_scale(TimeScale::GPST) + 1.0 * Unit::Nanosecond;
assert_eq!(reversed, t_gpst);

// Apply the backward transition, from t_utc back to t_gpst.
// The timescale conversion works both ways: (from UTC) GPST = UTC + a0 + a1 *dt + a2*dt²
let backwards = t_utc.precise_timescale_conversion(false, gpst_reference, gpst_utc_polynomials, TimeScale::GPST)
    .unwrap();

assert_eq!(backwards, t_gpst);

// It is important to understand that your reference point does not have to be in the past.
// The only logic that should prevail is to always minimize interpolation gap.
// In other words, if you can access future interpolation information that would minimize the data gap, they should prevail.
// Example: +30' in the future.
let gpst_reference = t_gpst + 30.0 * Unit::Minute;

// Forward conversion (to UTC) but using polynomials that were released 1 hour after t_gpst
let t_utc = t_gpst.precise_timescale_conversion(true, gpst_reference, gpst_utc_polynomials, TimeScale::UTC)
    .unwrap();

// Verifications
assert_eq!(t_utc.time_scale, TimeScale::UTC);

let reversed = t_utc.to_time_scale(TimeScale::GPST) + 1.0 * Unit::Nanosecond;
assert_eq!(reversed, t_gpst);
```

--------------------------------

### Iterate with TimeSeries (Rust)

Source: https://docs.rs/hifitime/latest/hifitime/index.html

Shows how to create an inclusive TimeSeries from start to end with a fixed step and iterate over it, counting the epochs.

```rust
use hifitime::prelude::*;

let start = Epoch::from_gregorian_utc_at_midnight(2017, 1, 14);
let end = start + 12.hours();
let step = 2.hours();

let time_series = TimeSeries::inclusive(start, end, step);
let mut cnt = 0;
for epoch in time_series {
    #[cfg(feature = "std")]
    println!("{}", epoch);
    cnt += 1
}
// Check that there are indeed seven two-hour periods in a half a day,
// including start and end times.
assert_eq!(cnt, 7)
```

--------------------------------

### Get Current Time and Next/Previous Weekday (Rust)

Source: https://docs.rs/hifitime/latest/hifitime/index.html

Shows how to get the current system time in UTC (requires std feature) and find the next Tuesday or previous Sunday.

```rust
use hifitime::prelude::*;

#[cfg(feature = "std")]
{
    let now = Epoch::now().unwrap();
    println!("{}", now.next(Weekday::Tuesday));
    println!("{}", now.previous(Weekday::Sunday));
}
```

--------------------------------

### from_gregorian_str parsing example

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Shows how to parse ISO8601/RFC3339 strings into an Epoch, including optional time scale, offset, and fractional seconds. The example asserts equality with from_gregorian_utc and from_gregorian_utc_hms, covering UTC, offsets, and fractional seconds.

```rust
use hifitime::Epoch;
let dt = Epoch::from_gregorian_utc(2017, 1, 14, 0, 31, 55, 0);
assert_eq!(
    dt,
    Epoch::from_gregorian_str("2017-01-14T00:31:55 UTC").unwrap()
);
assert_eq!(
    dt,
    Epoch::from_gregorian_str("2017-01-14T00:31:55.0000 UTC").unwrap()
);
assert_eq!(
    dt,
    Epoch::from_gregorian_str("2017-01-14T00:31:55").unwrap()
);
assert_eq!(
    dt,
    Epoch::from_gregorian_str("2017-01-14 00:31:55").unwrap()
);
// Regression test for #90
assert_eq!(
    Epoch::from_gregorian_utc(2017, 1, 14, 0, 31, 55, 811000000),
    Epoch::from_gregorian_str("2017-01-14 00:31:55.811 UTC").unwrap()
);
assert_eq!(
    Epoch::from_gregorian_utc(2017, 1, 14, 0, 31, 55, 811200000),
    Epoch::from_gregorian_str("2017-01-14 00:31:55.8112 UTC").unwrap()
);
// Example from https://www.w3.org/TR/NOTE-datetime
assert_eq!(
    Epoch::from_gregorian_utc_hms(1994, 11, 5, 13, 15, 30),
    Epoch::from_gregorian_str("1994-11-05T13:15:30Z").unwrap()
);
assert_eq!(
    Epoch::from_gregorian_utc_hms(1994, 11, 5, 13, 15, 30),
    Epoch::from_gregorian_str("1994-11-05T08:15:30-05:00").unwrap()
);
```

--------------------------------

### Create Epoch in Different Time Scales (Python)

Source: https://docs.rs/hifitime/latest/hifitime/index.html

Python equivalent of the Rust example, showing epoch creation, timedelta, and conversions to GPS days and MJD TT duration.

```python
>>> from hifitime import *
>>> epoch = Epoch("2000-02-29T14:57:29.000000037 UTC")
>>> epoch
2000-02-29T14:57:29.000000037 UTC
>>> epoch_tai = Epoch.init_from_gregorian_tai(2000, 2, 29, 14, 57, 29, 37)
>>> epoch_tai
2000-02-29T14:57:29.000000037 TAI
>>> epoch.timedelta(epoch_tai)
32 s
>>> epoch.to_gpst_days()
7359.623402777777
>>> epoch.to_mjd_tt_duration()
51603 days 14 h 58 min 33 s 184 ms 37 ns
>>>
```

--------------------------------

### TimeSeries::exclusive example

Source: https://docs.rs/hifitime/latest/hifitime/struct.TimeSeries.html

Creates a TimeSeries that is inclusive on start and exclusive on end. The example iterates from 2017-01-14 midnight to noon with a 2-hour step, printing each epoch and counting them. The assertion verifies that 6 epochs are produced.

```rust
use hifitime::{Epoch, Unit, TimeSeries};
let start = Epoch::from_gregorian_utc_at_midnight(2017, 1, 14);
let end = Epoch::from_gregorian_utc_at_noon(2017, 1, 14);
let step = Unit::Hour * 2;
let time_series = TimeSeries::exclusive(start, end, step);
let mut cnt = 0;
for epoch in time_series {
    println!("{}", epoch);
    cnt += 1
}
assert_eq!(cnt, 6)
```

--------------------------------

### Iterate with TimeSeries (Python)

Source: https://docs.rs/hifitime/latest/hifitime/index.html

Python equivalent of the Rust TimeSeries example, showing iteration over an inclusive time series with a two-hour step.

```python
>>> from hifitime import *
>>> start = Epoch.init_from_gregorian_utc_at_midnight(2017, 1, 14)
>>> end = start + Unit.Hour*12
>>> iterator = TimeSeries(start, end, step=Unit.Hour*2, inclusive=True)
>>> for epoch in iterator:
...     print(epoch)
...
2017-01-14T00:00:00 UTC
2017-01-14T02:00:00 UTC
2017-01-14T04:00:00 UTC
2017-01-14T06:00:00 UTC
2017-01-14T08:00:00 UTC
2017-01-14T10:00:00 UTC
2017-01-14T12:00:00 UTC
>>>
```

--------------------------------

### Duration::from_str parsing example

Source: https://docs.rs/hifitime/latest/hifitime/struct.Duration.html

Shows how to parse strings into Duration using FromStr. Supports units like d, h, min, s, ms, us, ns, and timezone offsets with + or -. The example asserts equality with Unit constants.

```rust
use hifitime::{Duration, Unit};
use std::str::FromStr;

assert_eq!(Duration::from_str("1 d").unwrap(), Unit::Day * 1);
assert_eq!(Duration::from_str("10.598 days").unwrap(), Unit::Day * 10.598);
assert_eq!(Duration::from_str("10.598 min").unwrap(), Unit::Minute * 10.598);
assert_eq!(Duration::from_str("10.598 us").unwrap(), Unit::Microsecond * 10.598);
assert_eq!(Duration::from_str("10.598 seconds").unwrap(), Unit::Second * 10.598);
assert_eq!(Duration::from_str("10.598 nanosecond").unwrap(), Unit::Nanosecond * 10.598);
assert_eq!(Duration::from_str("5 h 256 ms 1 ns").unwrap(), 5 * Unit::Hour + 256 * Unit::Millisecond + Unit::Nanosecond);
assert_eq!(Duration::from_str("-01:15:30").unwrap(), -(1 * Unit::Hour + 15 * Unit::Minute + 30 * Unit::Second));
assert_eq!(Duration::from_str("+3615").unwrap(), 36 * Unit::Hour + 15 * Unit::Minute);
assert_eq!(Duration::from_str("-5 h 256 ms 1 ns").unwrap(), -(5 * Unit::Hour + 256 * Unit::Millisecond + Unit::Nanosecond));
```

--------------------------------

### to_gregorian_utc example

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Converts an Epoch to Gregorian UTC parts and demonstrates the difference between TAI and UTC representations.

```rust
use hifitime::Epoch;

let dt_tai = Epoch::from_tai_parts(1, 537582752000000000);

let dt_str = "2017-01-14T00:31:55 UTC";
let dt = Epoch::from_gregorian_str(dt_str).unwrap();

let (y, m, d, h, min, s, _) = dt_tai.to_gregorian_utc();
assert_eq!(y, 2017);
assert_eq!(m, 1);
assert_eq!(d, 14);
assert_eq!(h, 0);
assert_eq!(min, 31);
assert_eq!(s, 55);
#[cfg(feature = "std")]
{
assert_eq!("2017-01-14T00:31:55 UTC", format!("{dt_tai:?}"));
// dt_tai is initialized from TAI, so the default print is the Gregorian in that time system
assert_eq!("2017-01-14T00:32:32 TAI", format!("{dt_tai}"));
// But dt is initialized from UTC, so the default print and the debug print are both in UTC.
assert_eq!("2017-01-14T00:31:55 UTC", format!("{dt}"));
}
```

--------------------------------

### to_gregorian example

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Converts an Epoch to Gregorian parts in a specified time scale, showing the difference between TAI and UTC.

```rust
use hifitime::{Epoch, TimeScale};
let dt = Epoch::from_gregorian_tai_at_midnight(1972, 1, 1);
let (y, m, d, h, min, s, n) = dt.to_gregorian(TimeScale::TAI);
assert_eq!(y, 1972);
assert_eq!(m, 1);
assert_eq!(d, 1);
assert_eq!(h, 0);
assert_eq!(min, 0);
assert_eq!(s, 0);
assert_eq!(n, 0);

// The epoch will be converted to UTC prior to returning the Gregorian parts.
let (y, m, d, h, min, s, n) = dt.to_gregorian(TimeScale::UTC);
assert_eq!(y, 1971);
assert_eq!(m, 12);
assert_eq!(d, 31);
assert_eq!(h, 23);
assert_eq!(min, 59);
assert_eq!(s, 50);
assert_eq!(n, 0);
```

--------------------------------

### Epoch::floor - Floors to closest duration

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Floors this epoch to the closest provided duration. The example shows flooring to 1 hour and 3 minutes, with expected results.

```rust
use hifitime::{Epoch, TimeUnits};

let e = Epoch::from_gregorian_tai_hms(2022, 5, 20, 17, 57, 43);
assert_eq!(
    e.floor(1.hours()),
    Epoch::from_gregorian_tai_hms(2022, 5, 20, 17, 0, 0)
);

let e = Epoch::from_gregorian_tai(2022, 10, 3, 17, 44, 29, 898032665);
assert_eq!(
    e.floor(3.minutes()),
    Epoch::from_gregorian_tai_hms(2022, 10, 3, 17, 42, 0)
);
```

--------------------------------

### Parsing Epoch from string with FromStr

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Example from the FromStr trait implementation showing how to parse Epoch from various string formats (JD, MJD, SEC) with different time scales. Uses assert! to verify successful parsing.

```rust
use hifitime::Epoch;
use core::str::FromStr;

assert!(Epoch::from_str("JD 2452312.500372511 TDB").is_ok());
assert!(Epoch::from_str("JD 2452312.500372511 ET").is_ok());
assert!(Epoch::from_str("JD 2452312.500372511 TAI").is_ok());
assert!(Epoch::from_str("MJD 51544.5 TAI").is_ok());
assert!(Epoch::from_str("SEC 0.5 TAI").is_ok());
assert!(Epoch::from_str("SEC 66312032.18493909 TDB").is_ok());
```

--------------------------------

### Python development setup commands

Source: https://docs.rs/hifitime/latest/hifitime/index.html

Commands to activate a virtual environment, install pytest, build hifitime with maturin, install the wheel, and run tests.

```bash
source .venv/bin/activate
```

```bash
pip install pytest
```

```bash
maturin build -F python --out dist
```

```bash
pip install dist/hifitime-4.0.0.alpha1-cp311-cp311-linux_x86_64.whl
```

```bash
.venv/bin/pytest
```

--------------------------------

### Create Epoch in Different Time Scales (Rust)

Source: https://docs.rs/hifitime/latest/hifitime/index.html

Shows how to create an Epoch from Gregorian UTC and TAI, parse from string, compute leap seconds, and convert to GPS days and MJD TT duration.

```rust
use hifitime::prelude::*;
use core::str::FromStr;
// Create an epoch in UTC
let epoch = Epoch::from_gregorian_utc(2000, 2, 29, 14, 57, 29, 37);
// Or from a string
let epoch_from_str = Epoch::from_str("2000-02-29T14:57:29.000000037 UTC").unwrap();
assert_eq!(epoch, epoch_from_str);
// Creating it from TAI will effectively show the number of leap seconds in between UTC an TAI at that epoch
let epoch_tai = Epoch::from_gregorian_tai(2000, 2, 29, 14, 57, 29, 37);
// The difference between two epochs is a Duration
let num_leap_s = epoch - epoch_tai;
assert_eq!(format!("{num_leap_s}"), "32 s");

// Trivially convert to another time scale
// Either by grabbing a subdivision of time in that time scale
assert_eq!(epoch.to_gpst_days(), 7359.623402777777); // Compare to the GPS time scale

// Or by fetching the exact duration
let mjd_offset = Duration::from_str("51603 days 14 h 58 min 33 s 184 ms 37 ns").unwrap();
assert_eq!(epoch.to_mjd_tt_duration(), mjd_offset); // Compare to the modified Julian days in the Terrestrial Time time scale.
```

--------------------------------

### __new__

Source: https://docs.rs/hifitime/latest/hifitime/ut1/struct.Ut1Provider.html

Python binding constructor for Ut1Provider.

```APIDOC
## __new__

### Description
Python binding constructor for Ut1Provider.

### Method
__new__

### Signature
pub fn __new__() -> Result<Self, HifitimeError>

### Parameters
None.

### Return
Result<Self, HifitimeError>

```

--------------------------------

### Frequencies usage example with assertions

Source: https://docs.rs/hifitime/latest/hifitime/trait.Frequencies.html

Example usage of the Frequencies trait with assertions. Note the precision limitations: 240 MHz is truncated to 4 ns, and 10 GHz is truncated to 0 ns.

```rust
use hifitime::prelude::*;

assert_eq!(1.Hz(), 1.seconds());
assert_eq!(10.Hz(), 0.1.seconds());
assert_eq!(100.Hz(), 0.01.seconds());
assert_eq!(1.MHz(), 1.microseconds());
assert_eq!(250.MHz(), 4.nanoseconds());
assert_eq!(1.GHz(), 1.nanoseconds());
// LIMITATIONS
assert_eq!(240.MHz(), 4.nanoseconds()); // 240 MHz is actually 4.1666.. nanoseconds, not 4 exactly!
assert_eq!(10.GHz(), 0.nanoseconds()); // As 10 GHz corresponds to 0.1 ns, it's truncated to 0 ns.
```

--------------------------------

### now

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Initializes a new Epoch from the current system time. Assumes the system time is UTC. Available only with the 'std' feature.

```APIDOC
## now

### Description
Initializes a new Epoch from `now`. WARNING: This assumes that the system time returns the time in UTC (which is the case on Linux). Uses `std::time::SystemTime::now` or javascript interop under the hood.

### Method
pub fn now() -> Result<Self, HifitimeError>

### Returns
- **Result<Self, HifitimeError>** - The current epoch or an error.

### Availability
Available on **crate feature `std`** only.
```

--------------------------------

### from_str_with_format

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Initializes an Epoch from the provided Format.

```APIDOC
## from_str_with_format

### Description
Initializes an Epoch from the provided Format.

### Method
Constructor

### Parameters
- **s_in** (&str) - Required - Input string to parse.
- **format** (Format) - Required - Format to use for parsing.

### Returns
- **Result<Self, HifitimeError>** - The constructed Epoch or an error.

```

--------------------------------

### duration_in_year

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Returns the duration since the start of the year.

```APIDOC
## duration_in_year

### Description
Returns the duration since the start of the year.

### Method
`pub fn duration_in_year(&self) -> Duration`

### Returns
- `Duration` - The duration since the start of the year.
```

--------------------------------

### LeapSecondsFile::__new__

Source: https://docs.rs/hifitime/latest/hifitime/leap_seconds/struct.LeapSecondsFile.html

Constructor for LeapSecondsFile, likely for Python bindings.

```APIDOC
## LeapSecondsFile::__new__

### Description
Constructor for LeapSecondsFile, likely for Python bindings.

### Method
__new__

### Signature
pub fn __new__(path: String) -> Result<Self, HifitimeError>

### Parameters
- **path** (String) - Required - The path to the leap seconds file.

### Returns
- **Result<Self, HifitimeError>** - The LeapSecondsFile instance or an error.
```

--------------------------------

### to_gregorian_tai example

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Converts an Epoch to Gregorian TAI parts.

```rust
use hifitime::Epoch;
let dt = Epoch::from_gregorian_tai_at_midnight(1972, 1, 1);
let (y, m, d, h, min, s, _) = dt.to_gregorian_tai();
assert_eq!(y, 1972);
assert_eq!(m, 1);
assert_eq!(d, 1);
assert_eq!(h, 0);
assert_eq!(min, 0);
assert_eq!(s, 0);
```

--------------------------------

### from_gregorian_tai_at_noon

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Initializes an Epoch from the Gregorian date at noon in TAI.

```APIDOC
## from_gregorian_tai_at_noon

### Description
Initializes an Epoch from the Gregorian date at noon in TAI.

### Method
Function

### Signature
`pub fn from_gregorian_tai_at_noon(year: i32, month: u8, day: u8) -> Self`

### Parameters
- `year` (i32) - Required - The year.
- `month` (u8) - Required - The month (1-12).
- `day` (u8) - Required - The day of the month.

### Returns
- `Self` - The resulting Epoch.

```

--------------------------------

### day_of_year

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Returns the number of days since the start of the year.

```APIDOC
## day_of_year

### Description
Returns the number of days since the start of the year.

### Method
`pub fn day_of_year(&self) -> f64`

### Returns
- `f64` - The number of days since the start of the year.
```

--------------------------------

### impl PyClassImpl for Weekday

Source: https://docs.rs/hifitime/latest/hifitime/enum.Weekday.html

Detailed PyO3 class implementation details for Weekday.

```APIDOC
## impl PyClassImpl for Weekday

### Description
Detailed PyO3 class implementation details for Weekday.

### Associated Constants

#### const MODULE: Option<&str> = None
Module which the class will be associated with.

#### const IS_BASETYPE: bool = false
Indicates if this is a base type.

#### const IS_SUBCLASS: bool = false
Indicates if this is a subclass.

#### const IS_MAPPING: bool = false
Indicates if this is a mapping.

#### const IS_SEQUENCE: bool = false
Indicates if this is a sequence.

#### const IS_IMMUTABLE_TYPE: bool = false
Indicates if this is an immutable type.

#### const RAW_DOC: &'static CStr = c"\x00"
Docstring for the class.

#### const DOC: &'static CStr
Fully rendered class doc.

### Associated Types

#### type Layout = <<Weekday as PyClassImpl>::BaseNativeType as PyClassBaseType>::Layout<Weekday>
Memory layout description.

#### type BaseType = PyAny
Base class.

#### type ThreadChecker = NoopThreadChecker
Handles thread safety.

#### type Inventory = Pyo3MethodsInventoryForWeekday
Available on crate feature `multiple-pymethods` only.

#### type PyClassMutability = <<PyAny as PyClassBaseType>::PyClassMutability as PyClassMutability>::MutableChild
Immutable or mutable.

#### type Dict = PyClassDummySlot
Specifies if class has `#[pyclass(dict)]`.

#### type WeakRef = PyClassDummySlot
Specifies if class has `#[pyclass(weakref)]`.

#### type BaseNativeType = PyAny
The closest native ancestor.

### Methods

#### fn items_iter() -> PyClassItemsIter
Returns an iterator over class items.

#### fn lazy_type_object() -> &'static LazyTypeObject<Self>
Returns the lazy type object.

#### fn dict_offset() -> Option<PyObjectOffset>
Provides the dictoffset slot.

#### fn weaklist_offset() -> Option<PyObjectOffset>
Provides the weaklistoffset slot.
```

--------------------------------

### py_ut1_offset

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Get the accumulated offset between this epoch and UT1. Python binding.

```APIDOC
## py_ut1_offset

### Description
Get the accumulated offset between this epoch and UT1. Python binding.

### Method
py_ut1_offset

### Parameters
- **provider** (PyRef<'_, Ut1Provider>) - Required - UT1 provider.

### Returns
- **Option<Duration>** - The offset.

### Notes
- Available on crate feature `ut1` only.
- Python types: provider: Ut1Provider, rtype: Duration.
```

--------------------------------

### leap_seconds_iers

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Get the accumulated number of leap seconds up to this Epoch accounting only for the IERS leap seconds.

```APIDOC
## leap_seconds_iers

### Description
Get the accumulated number of leap seconds up to this Epoch accounting only for the IERS leap seconds.

### Method
leap_seconds_iers

### Parameters
None

### Returns
- **i32** - The number of leap seconds.

### Notes
- Python rtype: int.
```

--------------------------------

### download_short_from_jpl

Source: https://docs.rs/hifitime/latest/hifitime/ut1/struct.Ut1Provider.html

Builds a UT1 provider by downloading short time scale UT1 data from JPL and parsing it.

```APIDOC
## download_short_from_jpl

### Description
Builds a UT1 provider by downloading the data from https://eop2-external.jpl.nasa.gov/eop2/latest_eop2.short (short time scale UT1 data) and parsing it.

### Method
download_short_from_jpl

### Signature
pub fn download_short_from_jpl() -> Result<Self, HifitimeError>

### Parameters
None.

### Return
Result<Self, HifitimeError>

```

--------------------------------

### Custom Format with C89 Tokens (Rust)

Source: https://docs.rs/hifitime/latest/hifitime/index.html

Demonstrates parsing and printing epochs with custom C89 format strings using from_format_str and Format::from_str.

```rust
use core::str::FromStr;
use hifitime::prelude::*;

let epoch = Epoch::from_gregorian_utc_hms(2015, 2, 7, 11, 22, 33);

// Parsing with a custom format
assert_eq!(
    Epoch::from_format_str("Sat, 07 Feb 2015 11:22:33", "%a, %d %b %Y %H:%M:%S").unwrap(),
    epoch
);

// And printing with a custom format
let fmt = Format::from_str("%a, %d %b %Y %H:%M:%S").unwrap();
assert_eq!(
    format!("{}", Formatter::new(epoch, fmt)),
    "Sat, 07 Feb 2015 11:22:33"
);
```

--------------------------------

### day_of_month

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Returns the number of days since the start of the Gregorian month in the current time scale.

```APIDOC
## day_of_month

### Description
Returns the number of days since the start of the Gregorian month in the current time scale.

### Method
`pub fn day_of_month(&self) -> u8`

### Returns
- `u8` - The day of the month.

### Example
```rust
use hifitime::Epoch;
let dt = Epoch::from_gregorian_tai_at_midnight(2025, 7, 3);
assert_eq!(dt.day_of_month(), 3);
```
```

--------------------------------

### from_qzsst_days

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Initializes an Epoch from the number of days since the QZSS Time Epoch (UTC midnight of January 5th to 6th 1980).

```APIDOC
## from_qzsst_days

### Description
Initialize an Epoch from the number of days since the QZSS Time Epoch, defined as UTC midnight of January 5th to 6th 1980 (cf. https://gssc.esa.int/navipedia/index.php/Time_References_in_GNSS#GPS_Time_.28GPST.29).

### Method
Constructor

### Parameters
- **days** (f64) - Required - The number of days since the QZSS epoch.

### Returns
- **Self** - The resulting Epoch.
```

--------------------------------

### py_from_eop_file

Source: https://docs.rs/hifitime/latest/hifitime/ut1/struct.Ut1Provider.html

Python binding to build a UT1 provider from a path to an EOP file.

```APIDOC
## py_from_eop_file

### Description
Python binding to build a UT1 provider from a path to an EOP file.

### Method
py_from_eop_file

### Signature
pub fn py_from_eop_file(_cls: &Bound<'_, PyType>, path: &str) -> Result<Self, HifitimeError>

### Parameters
- `path` (str) - Required - Path to the EOP file.

### Return
Result<Self, HifitimeError>

### Note
:type path: str
:rtype: Ut1Provider

```

--------------------------------

### from_eop_file

Source: https://docs.rs/hifitime/latest/hifitime/ut1/struct.Ut1Provider.html

Builds a UT1 provider from the provided path to an EOP file.

```APIDOC
## from_eop_file

### Description
Builds a UT1 provider from the provided path to an EOP file.

### Method
from_eop_file

### Signature
pub fn from_eop_file(path: &str) -> Result<Self, HifitimeError>

### Parameters
- `path` (str) - Required - Path to the EOP file.

### Return
Result<Self, HifitimeError>

```

--------------------------------

### leap_seconds_with

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Get the accumulated number of leap seconds up to this Epoch from the provided LeapSecondProvider. Returns None if the epoch is before 1960.

```APIDOC
## leap_seconds_with

### Description
Get the accumulated number of leap seconds up to this Epoch from the provided LeapSecondProvider. Returns None if the epoch is before 1960.

### Method
leap_seconds_with

### Parameters
- **iers_only** (bool) - Required - Whether to account only for IERS leap seconds.
- **provider** (L) - Required - Leap seconds provider (generic).

### Returns
- **Option<f64>** - The number of leap seconds, or None if before 1960.
```

--------------------------------

### from_gregorian_utc_at_noon

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Initializes an Epoch from a Gregorian date in UTC at noon.

```APIDOC
## from_gregorian_utc_at_noon

### Description
Initializes an Epoch from a Gregorian date in UTC at noon.

### Signature
```rust
pub fn from_gregorian_utc_at_noon(year: i32, month: u8, day: u8) -> Self
```

### Parameters
- **year** (i32) - Required - Gregorian year.
- **month** (u8) - Required - Gregorian month (1-12).
- **day** (u8) - Required - Gregorian day (1-31).

### Returns
- **Self** - The constructed Epoch at noon UTC.
```

--------------------------------

### leap_seconds_with_file

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Get the accumulated number of leap seconds up to this Epoch from the provided LeapSecondProvider. Returns None if the epoch is before 1960.

```APIDOC
## leap_seconds_with_file

### Description
Get the accumulated number of leap seconds up to this Epoch from the provided LeapSecondProvider. Returns None if the epoch is before 1960.

### Method
leap_seconds_with_file

### Parameters
- **iers_only** (bool) - Required - Whether to account only for IERS leap seconds.
- **provider** (LeapSecondsFile) - Required - Leap seconds provider.

### Returns
- **Option<f64>** - The number of leap seconds, or None if before 1960.

### Notes
- Available on crate feature `python` only.
- Python types: iers_only: bool, provider: LeapSecondsFile, rtype: float.
```

--------------------------------

### ut1_offset

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Get the accumulated offset between this epoch and UT1. Assumes the provider's records are sorted by ascending epoch.

```APIDOC
## ut1_offset

### Description
Get the accumulated offset between this epoch and UT1. Assumes the provider's records are sorted by ascending epoch.

### Method
ut1_offset

### Parameters
- **provider** (&Ut1Provider) - Required - Borrowed UT1 data source.

### Returns
- **Option<Duration>** - Some(Duration) for the last record with `record.epoch <= self`, otherwise None.

### Notes
- Available on crate feature `ut1` only.
```

--------------------------------

### TimeSeries::inclusive

Source: https://docs.rs/hifitime/latest/hifitime/struct.TimeSeries.html

Creates a TimeSeries iterator that yields Epochs from start to end, both inclusive, with a fixed step duration.

```APIDOC
## TimeSeries::inclusive

### Description
Returns an iterator of evenly spaced Epochs, inclusive on start and on end.

### Method
`pub fn inclusive(start: Epoch, end: Epoch, step: Duration) -> TimeSeries`

### Parameters
- **start** (Epoch) - Required - The first Epoch of the series (inclusive).
- **end** (Epoch) - Required - The last Epoch of the series (inclusive).
- **step** (Duration) - Required - The duration between consecutive Epochs.

### Returns
- **TimeSeries** - An iterator of evenly spaced Epochs.

### Example
```rust
use hifitime::{Epoch, Unit, TimeSeries};
let start = Epoch::from_gregorian_utc_at_midnight(2017, 1, 14);
let end = Epoch::from_gregorian_utc_at_noon(2017, 1, 14);
let step = Unit::Hour * 2;
let time_series = TimeSeries::inclusive(start, end, step);
let mut cnt = 0;
for epoch in time_series {
    println!("{}", epoch);
    cnt += 1
}
assert_eq!(cnt, 7)
```
```

--------------------------------

### from_bdt_days

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Initializes an Epoch from the number of days since the BDT Time Epoch, starting on January 1st 2006.

```APIDOC
## from_bdt_days

### Description
Initializes an Epoch from the number of days since the BDT Time Epoch, starting on January 1st 2006.

### Method
Constructor

### Parameters
- **days** (f64) - Required - Number of days since the BDT Time Epoch.

### Returns
- **Self** - The constructed Epoch.

```

--------------------------------

### download_from_jpl

Source: https://docs.rs/hifitime/latest/hifitime/ut1/struct.Ut1Provider.html

Builds a UT1 provider by downloading long time scale UT1 data from JPL and parsing it.

```APIDOC
## download_from_jpl

### Description
Builds a UT1 provider by downloading the data from https://eop2-external.jpl.nasa.gov/eop2/latest_eop2.long (long time scale UT1 data) and parsing it.

### Method
download_from_jpl

### Signature
pub fn download_from_jpl(version: &str) -> Result<Self, HifitimeError>

### Parameters
- `version` (str) - Required - Version identifier for the data.

### Return
Result<Self, HifitimeError>

```

--------------------------------

### from_bdt_seconds

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Initializes an Epoch from the number of seconds since the BDT Time Epoch, starting on January 1st 2006.

```APIDOC
## from_bdt_seconds

### Description
Initializes an Epoch from the number of seconds since the BDT Time Epoch, starting on January 1st 2006.

### Method
Constructor

### Parameters
- **seconds** (f64) - Required - Number of seconds since the BDT Time Epoch.

### Returns
- **Self** - The constructed Epoch.

```

--------------------------------

### Round Duration and Epoch differences in Rust

Source: https://docs.rs/hifitime/latest/hifitime/index.html

Demonstrates rounding a Duration to the nearest minute and computing the difference between two Epochs, then flooring and ceiling that difference to 15-day intervals. Asserts the expected formatted outputs.

```rust
use hifitime::prelude::*;

// Create a duration using the `TimeUnits` helping trait.
let d = 5.minutes() + 7.minutes() + 35.nanoseconds();
// Round to the nearest minute
let rounded = d.round(1.minutes());
assert_eq!(format!("{rounded}"), "12 min");

// And this works on Epochs as well.
let previous_post = Epoch::from_gregorian_utc_hms(2015, 2, 7, 11, 22, 33);
let example_now = Epoch::from_gregorian_utc_hms(2015, 8, 17, 22, 55, 01);

// We'll round to the nearest fifteen days
let this_much_ago = example_now - previous_post;
assert_eq!(format!("{this_much_ago}"), "191 days 11 h 32 min 28 s");
let about_this_much_ago_floor = this_much_ago.floor(15.days());
assert_eq!(format!("{about_this_much_ago_floor}"), "180 days");
let about_this_much_ago_ceil = this_much_ago.ceil(15.days());
assert_eq!(format!("{about_this_much_ago_ceil}"), "195 days");
```

--------------------------------

### from_format_str

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Initializes an Epoch from the Format as a string.

```APIDOC
## from_format_str

### Description
Initializes an Epoch from the Format as a string.

### Method
Constructor

### Parameters
- **s_in** (&str) - Required - Input string to parse.
- **format_str** (&str) - Required - Format string to use for parsing.

### Returns
- **Result<Self, HifitimeError>** - The constructed Epoch or an error.

```

--------------------------------

### from_time_of_week

Source: https://docs.rs/hifitime/latest/hifitime/struct.Epoch.html

Builds an Epoch from given week and nanoseconds within that week. For example, this is how GPS vehicles describe a GPST epoch.

```APIDOC
## from_time_of_week

### Description
Builds an Epoch from given `week`: elapsed weeks counter into the desired Time scale, and the amount of nanoseconds within that week.

### Method
Constructor

### Parameters
- **week** (u32) - Required - Elapsed weeks counter into the desired Time scale.
- **nanoseconds** (u64) - Required - Amount of nanoseconds within that week.
- **time_scale** (TimeScale) - Required - Time scale to use.

### Returns
- **Self** - The constructed Epoch.

```
Tokens:
Raw