astrotime 0.2.0

Time related types
Documentation
  • Coverage
  • 88.89%
    40 out of 45 items documented0 out of 0 items with examples
  • Size
  • Source code size: 133.26 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 7.8 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 15s Average build duration of successful builds.
  • all releases: 11s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • mikedilger/astrotime
    7 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • mikedilger

astrotime

Astrotime is a rust library for dealing with time for scientific and astronomical purposes on the surface of the Earth, or for satellites of the Earth. It is not sufficient for space travel or for solar system objects.

This library is lightweight and high performance.

Features

The following features are currently available:

  • Durations:
    • Handles times covering the entire duration of the universe.
    • Handles times to attosecond precision.
  • Instants:
    • Math operations with Durations
    • now() functionality (via std::time::SystemTime)
    • Julian Day support
    • NTP Date support
  • Epochs
    • Supplies precise instants for well known Epochs such as J1900.0, J2000.0, the Unix epoch, Y2K, NTP dates, Spreadsheet date epoch, etc.
  • Standards of time, and conversions between them
    • UTC, TT, TAI, and TCG.
    • Handling leap seconds precisely, including edge cases.
    • Geocentric coordinate time with Einsteinian correction for gravity.
  • DateTime calendar representations of time
    • Day, month, year, hour, minute, second
    • Handles the well known month length and leap year oddities.
    • Using and converting between calendar standards: Gregorian, Julian
  • Conversion between Instants and DateTimes.
  • Optional serde serialization (enable feature 'serde')

Currently Excluded

We do not currently deal with these civil time issues:

  • Timezones
  • Daylight savings time
  • AM/PM

UTC is the closest we get to civil time, primarily because Internet time standards are based on it.

Possible Improvements

The following are NOT available currently, but we are not against PRs that implement any of these:

  • The ability to update leapseconds from the IETF source online.
  • Handling of civil time issues such as
    • Time zones
    • Daylight Savings Time
    • AM/PM versus 24-hour time
  • Provides (possibly lossy) conversions for types in the 'chrono' and 'time' crates, including rust std SystemTime.
  • Add GPS time and LORAN-C
  • Add Sidereal time
  • impl ApproxEq from the float_cmp trait for Duration, Instant, and DateTime

Types

Duration

Duration represents an interval of time.

Durations can handle lengths of time about 40 times as long as the age of the universe, and have attosecond (10^-18) precision.

Negative values are supported.

Why attoseconds? Why not just nanoseconds?

I don't have a personal use for such precision, but the data types were 96 bits with nanoseconds, and since computers these days tend to be 64-bit, it seemed that half a word was being wasted. So I extended the fractional seconds part to handle attoseconds. The biggest downside is typing all 18 zeroes.

DateTime and Instant

There are two types that represent an instant or moment in time.

The first type is a DateTime<Calendar, Standard>, which allows easy creation and manipulation of dates using Calendars such as Gregorian or Julian, and which may flexibly represent different time standards (Utc, Tai, or Tt). This type internally stores the year, month, day, hour, minute, second and attosecond in a packed format. It is 128 bits in size.

A DateTime can have a minimum and maximum year within an i32 type. Thus it does not span the same duration of time that a Duration does.

The second type is an Instant with an opaque implementation, which is also 128 bits in size. Instants can be subtracted to get a Duration, and a Duration can be added to or subtracted from an Instant to get a different Instant. Instants can span the full duration of time that Duration supports. Instants can convert to and from DateTimes of varying Calendar and Stanadard parameters providing automatic conversion between said Calendars and Standards. Instants can also be converted to and from Julian Days.

Epochs

Well known points in time are provided such as the start of the JulianPeriod, or the start of the JulianCalendar, J1900_0, Unix (the start of UNIXTIME), Y2k, etc.

Curiousities about Time

UnixTime is discontinuous and has overlapping seconds. Some values of unixtime refer to two different points in time exactly one second apart. UTC differentiate these two seconds with a :59 and a :60 but unixtime has no such differentiator.

Spreadsheets (starting with MicroSoft Excel?) store dates as a floating point count of days since December 30, 1899, at midnight. This epoch is 18 hours before J1900.0.

Astronomers use the TT (terrestrial time) standard, because leap second shifting, while it accounts for the rotation of the earth, confuses all other astronomical timings. For example, the position of the Earth in it's orbit around the Sun has nothing to do with whether or not Earth's rotation on it's axis has changed. TT differs from UTC by a little over a minute.

Astronomers use Julian Days which start and end at noon GMT so that the entire night lies within a single Julian day (astronomers work at night).

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.