Struct Instant 

pub struct Instant {
    pub raw: i64,
}

A module for handling time and date conversions. Time is stored natively as the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC) with leap seconds accounted for.

The Instant struct provides methods for converting to and from Unix time, GPS time, Julian Date, Modified Julian Date, and Gregorian calendar date.

Why do we need another structure that handles time?

This structure is necessary as it is time scale aware, i.e. it can handle different time scales such as UTC, TAI, TT, UT1, GPS, etc. This is necessary for high-precision coordinate transforms and orbit propagation.

Fields

raw: i64

The number of microseconds since Unix epoch (1970-01-01 00:00:00 UTC)

Implementations

impl Instant

pub const J2000: Self

J2000 epoch is 2000-01-01 12:00:00 TT TT (Terrestrial Time) is 32.184 seconds ahead of TAI

pub const UNIX_EPOCH: Self

Unix epoch is 1970-01-01 00:00:00 UTC

pub const GPS_EPOCH: Self

GPS epoch is 1980-01-06 00:00:00 UTC

pub const INVALID: Self

pub const MJD_EPOCH: Self

Modified Julian day epoch is 1858-11-17 00:00:00 UTC

pub const fn new(raw: i64) -> Self

Construct a new Instant from raw microseconds

Arguments

• raw - The number of microseconds since unixtime epoch

Returns

A new Instant object

Example

use satkit::Instant;
let now = Instant::new(1234567890);

pub fn from_gps_week_and_second(week: i32, sow: f64) -> Self

Construct a new Instant from GPS week and second of week

Arguments

• week - The GPS week number
• sow - The second of week

Returns

A new Instant object

pub fn from_unixtime(unixtime: f64) -> Self

Construct a new Instant from Unix time

Arguments

• unixtime - The Unix time in seconds

Returns

A new Instant object representing the input Unix time

Note:

Unixtime is the number of non-leap seconds since Jan 1 1970 00:00:00 UTC (Leap seconds are ignored!!)

pub fn as_unixtime(&self) -> f64

Convert Instant to Unix time

Returns

The Unix time in seconds (since 1970-01-01 00:00:00 UTC)

Note

Unixtime is the number of non-leap seconds since 1970-01-01 00:00:00 UTC.

pub fn day_of_week(&self) -> Weekday

Return the day of the week 0 = Sunday, 1 = Monday, …, 6 = Saturday

See: https://en.wikipedia.org/wiki/Determination_of_the_day_of_the_week

pub fn as_mjd(&self) -> f64

👎Deprecated:

Use as_mjd_utc() for explicit scale, or as_mjd_with_scale()

As Modified Julian Date (UTC) Days since 1858-11-17 00:00:00 UTC where each day is 86,400 seconds (no leap seconds)

pub fn as_mjd_utc(&self) -> f64

As Modified Julian Date (UTC) Days since 1858-11-17 00:00:00 UTC where each day is 86,400 seconds (no leap seconds)

pub fn from_mjd(mjd: f64) -> Self

👎Deprecated:

Use from_mjd_utc() for explicit scale, or from_mjd_with_scale()

Create Instant from Modified Julian Date (UTC)

Arguments

• mjd - Modified Julian Date (UTC)

Returns

A new Instant object representing the given MJD

pub fn from_mjd_utc(mjd: f64) -> Self

Create Instant from Modified Julian Date (UTC)

Arguments

• mjd - Modified Julian Date (UTC)

Returns

A new Instant object representing the given MJD

pub fn from_jd(jd: f64) -> Self

👎Deprecated:

Use from_jd_utc() for explicit scale, or from_jd_with_scale()

Create Instant from Julian Date (UTC)

Arguments

• jd - Julian Date (UTC)

Returns

A new Instant object representing the given JD

pub fn from_jd_utc(jd: f64) -> Self

Create Instant from Julian Date (UTC)

Arguments

• jd - Julian Date (UTC)

Returns

A new Instant object representing the given JD

pub fn from_jd_with_scale(jd: f64, scale: TimeScale) -> Self

Create Instant from Julian Date with given time scale (UTC, TAI, TT, UT1, GPS) Days since 4713 BC January 1, 12:00 UTC

Arguments

• jd - Julian Date
• scale - The time scale to use

Returns

A new Instant object representing the given JD at given time scale

pub fn from_mjd_with_scale(mjd: f64, scale: TimeScale) -> Self

Construct an instant from a given Modified Julian Date and time scale

Arguments

• mjd - The Modified Julian Date
• scale - The time scale to use

Returns

A new Instant object representing the given MJD at given time scale

pub fn as_jd(&self) -> f64

👎Deprecated:

Use as_jd_utc() for explicit scale, or as_jd_with_scale()

As Julian Date (UTC) Days since 4713 BC January 1, 12:00 UTC where each day is 86,400 seconds (no leap seconds)

pub fn as_jd_utc(&self) -> f64

As Julian Date (UTC) Days since 4713 BC January 1, 12:00 UTC where each day is 86,400 seconds (no leap seconds)

pub fn as_jd_with_scale(&self, scale: TimeScale) -> f64

As Julian Date with given time scale Days since 4713 BC January 1, 12:00 UTC

Arguments

• scale - The time scale to use

Returns

The Julian Date in the given time scale

pub fn add_utc_days(&self, days: f64) -> Self

Add given floating-point number of days to Instant instance, and return new instance representing new time.

Days are defined in this case to have exactly 86400.0 seconds In other words, this will ignore leap seconds and the integer part of the floating point will increment the number of days and the decimal part will increment the fractions of a day.

So, for example, adding 1.0 to a day with a leap second will increment by a full day

Arguments

• days - The number of days to add

Returns

A new Instant object representing the new time

pub fn as_mjd_with_scale(&self, scale: TimeScale) -> f64

As Modified Julian Date with given time scale Days since 1858-11-17 00:00:00 UTC

Arguments

• scale - The time scale to use

Returns

The Modified Julian Date in the given time scale

pub fn as_datetime(&self) -> (i32, i32, i32, i32, i32, f64)

Return the Gregorian date and time

Returns

(year, month, day, hour, minute, second), UTC

pub fn from_date(year: i32, month: i32, day: i32) -> Result<Self>

Construct an instant from a given UTC date

Arguments

• year - The year
• month - The month
• day - The day

Returns

A new Instant object representing the given date

pub fn day_of_year(&self) -> u32

Return the day of the year (1-based, Gregorian); leap-year aware.

Returns

The day of the year (1-based, Gregorian); leap-year aware.

Notes:

• Gregorian Jan 1 = 1

Example

// Examples checked against google query

let thedate = satkit::Instant::from_date(2023, 1, 1).unwrap();
assert_eq!(thedate.day_of_year(), 1);

let thedate = satkit::Instant::from_date(2025, 8, 16).unwrap();
assert_eq!(thedate.day_of_year(), 228);

pub fn utc( year: i32, month: i32, day: i32, hour: i32, minute: i32, second: f64, ) -> Result<Self>

Convenience alias for from_datetime

Construct an instant from a given Gregorian UTC date and time

Arguments

• year - The year
• month - The month (1-12)
• day - The day (1-31)
• hour - The hour (0-23)
• minute - The minute (0-59)
• second - The second (0.0-60.0)

Returns

A new Instant object representing the given date and time, or error if invalid

pub fn from_datetime( year: i32, month: i32, day: i32, hour: i32, minute: i32, second: f64, ) -> Result<Self>

Construct an instant from a given Gregorian UTC date and time

Arguments

• year - The year
• month - The month
• day - The day
• hour - The hour
• minute - The minute
• second - The second

Returns

A new Instant object representing the given date and time, or error if invalid or error if the month, day, hour, minute, or second are out of bounds

pub fn now() -> Self

Current time

Returns

The current time as an Instant object

Example

use satkit::Instant;
let now = Instant::now();

impl Instant

pub fn from_string(s: &str) -> Result<Self>

Parse a string into an Instant object

Attempts to guess the string format. Use sparingly and with caution. This is probably not what you want.

Arguments:

s (str): The string to parse

Returns:

Instant: The instant object

Raises:

SCErr: If the string cannot be parsed

pub fn strptime(s: &str, format: &str) -> Result<Self>

Parse a string into an Instant object

Notes:

• The format string is a subset of the Python datetime module

Arguments:

• s (str): The string to parse
• format (str): The format string

Format Codes:

• %Y - Year with century as a decimal number
• %m - Month as a zero-padded decimal number [01, 12]
• %B - Full month name (January, February, etc.)
• %b - Abbreviated month name (Jan, Feb, etc.)
• %d - Day of the month as a zero-padded decimal number [01, 31]
• %H - Hour (24-hour clock) as a zero-padded decimal number
• %M - Minute as a zero-padded decimal number
• %S - Second as a zero-padded decimal number
• %f - Microsecond as a decimal number, allowing for trailing zeros
• %z - UTC offset in the form +HHMM or -HHMM or ‘Z’ for UTC

Returns:

Instant: The instant object

pub fn from_rfc3339(rfc3339: &str) -> Result<Self, InstantError>

Parse a string in RFC3339 format

Arguments:

rfc3339 (str): The string in RFC3339 format

Notes:

• Only allows a subset of the RFC3339 format: “YYYY-MM-DDTHH:MM:SS.sssZ”

Returns:

Instant: The instant object

pub fn as_rfc3339(&self) -> String

Format the Instant object as a string in RFC3339 format

Returns:

str: The formatted string in RFC3339 format: “YYYY-MM-DDTHH:MM:SS.sssZ”

Notes:

• This is the same as ISO8601 format

pub fn as_iso8601(&self) -> String

Format the Instant object as a string in ISO8601 format

Returns:

str: The formatted string in ISO8601 format: “YYYY-MM-DDTHH:MM:SS.sssZ”

Notes:

• This is the same as RFC3339 format

pub fn strftime(&self, format: &str) -> Result<String, InstantError>

Format the Instant object as a string

Notes:

• The format string is a subset of the Python datetime module

Arguments:

format (str): The format string

Format Codes:

• %Y - Year with century as a decimal number
• %m - Month as a zero-padded decimal number [01, 12]
• %B - Full month name (January, February, etc.)
• %b - Abbreviated month name (Jan, Feb, etc.)
• %d - Day of the month as a zero-padded decimal number [01, 31]
• %H - Hour (24-hour clock) as a zero-padded decimal number
• %M - Minute as a zero-padded decimal number
• %S - Second as a zero-padded decimal number
• %f - Microsecond as a decimal number
• %A - Full weekday name (Sunday, Monday, etc.)
• %w - Weekday as a decimal number [0(Sunday), 6(Saturday)]

Returns:

str: The formatted string

Trait Implementations

impl Add<Duration> for &Instant

type Output = Instant

The resulting type after applying the + operator.

fn add(self, other: Duration) -> Instant

Performs the + operation.

impl Add<Duration> for Instant

type Output = Instant

The resulting type after applying the + operator.

fn add(self, other: Duration) -> Self

Performs the + operation.

impl AddAssign<Duration> for Instant

fn add_assign(&mut self, other: Duration)

Performs the += operation.

impl Clone for Instant

fn clone(&self) -> Instant

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Instant

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Instant

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Instant

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

Formats the value using the given formatter.

impl Ord for Instant

fn cmp(&self, other: &Self) -> 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<Instant> for SpaceWeatherRecord

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

fn eq(&self, other: &Self) -> 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<Instant> for SpaceWeatherRecord

fn partial_cmp(&self, other: &Instant) -> 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 PartialOrd for Instant

fn partial_cmp(&self, other: &Self) -> 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 Serialize for Instant

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Sub<Duration> for &Instant

type Output = Instant

The resulting type after applying the - operator.

fn sub(self, other: Duration) -> Instant

Performs the - operation.

impl Sub<Duration> for Instant

type Output = Instant

The resulting type after applying the - operator.

fn sub(self, other: Duration) -> Self

Performs the - operation.

impl Sub<Instant> for &Instant

type Output = Duration

The resulting type after applying the - operator.

fn sub(self, other: Instant) -> Duration

Performs the - operation.

impl Sub for Instant

type Output = Duration

The resulting type after applying the - operator.

fn sub(self, other: Self) -> Duration

Performs the - operation.

impl SubAssign<Duration> for Instant

fn sub_assign(&mut self, other: Duration)

Performs the -= operation.

impl TimeLike for Instant

fn as_mjd_with_scale(&self, scale: TimeScale) -> f64

Modified Julian Date with the provided time scale.

fn as_jd_with_scale(&self, scale: TimeScale) -> f64

Julian Date with the provided time scale.

fn as_instant(&self) -> Instant

Convert to a satkit Instant in UTC.

impl Copy for Instant

impl Eq for Instant