Crate erfars 

A Rust crate that provides safe Rust bindings to the Essential Routines for Fundamental Astronomy (ERFA) C library, which is based on the Standards of Fundamental Astronomy (SOFA) library published by the International Astronomical Union (IAU).

Usage

With this crate, functions in ERFA can be called safely in Rust:

use erfars::calendar::Cal2jd;

fn main() {
    let ((jd0, jd1), _) = Cal2jd(2025, 1, 22).unwrap();
    assert_eq!(jd0+jd1, 2460697.5)
}

A note on array arguments in functions

Many of the ERFA C functions pass data in the form of multidimensional arrays. For example, a double[3][3] represents a 3x3 matrix of double-precision floating-point values. However, Rust does not have an equivalent and clean way of representing this in code. A double[3][3] is stored in row-major order, so the Rust equivalent in memory is simply an array [f64; 9]. More specifically, the following variable declarations are equivalent:

In C:

double xyz[3][3] = { {0.0, 0.0, 0.0}, {0.0, 0.0, 0.0}, {0.0, 0.0, 0.0} };

In Rust:

let xyz: [f64; 9] = [0.0; 9];

Where the first three elements of the Rust array are the first row of the C array, and the second group of three elements in the Rust array are the second row of the C array, and so on.

For the user, this means that wherever you see something like a double[2][3] or a double[3][3] in the ERFA C API, you can safely pass a [f64; 6] or a [f64; 9] Rust value.

A note on return values for some ERFA functions

Some of the safe Rust ERFA functions return a ERFAResult, which encapsulates both warnings and errors returned from ERFA. The Ok value of this result contains both the actual result and the warning code as a tuple. The warning code is equal to zero if all is ok. Warning codes from ERFA are always greater than zero, which means you can handle errors using something like:

use erfars::calendar::Jdcalf;

fn main() {
    // Panics on error
    // If a warning is raised, `warn` is > 0
    let (res, warn) = Jdcalf(2460697.0, 0.5, 2).unwrap();
    if warn > 0 {
        // Do something
    }
}

The meaning of the warning/error codes can be found in the ERFA docs for the relevant function.

Modules

astrometry

ERFA Astrometry Functions

calendar

ERFA Calendar Functions

constants

ERFA Constants

eclipticcoordinates

ERFA Ecliptic Coordinates Functions

ephemerides

ERFA Ephemerides Functions

fundamentalargs

ERFA Fundamental Arguments for Nutation

galacticcoordinates

ERFA Galactic Coordinates Functions

geodeticgeocentric

ERFA Geodetic/Geocentric Functions

gnomonic

ERFA Gnomonic Projection Functions

horizonequatorial

ERFA Horizon/Equatorial Functions

precnutpolar

ERFA Precession, Nutation, and Polar Motion Functions

raw

Raw bindings to the ERFA C library

rotationtime

ERFA Earth Rotation Angle and Sidereal Time Functions

spacemotion

ERFA Space Motion Functions

starcatalogs

ERFA Star Catalog Functions

timescales

ERFA Timescales Functions

Structs

Astrom

Star-independent astrometry parameters

LDBody

Body parameters for light deflection

Type Aliases

ERFAResult

A return type for ERFA functions which contains both a warning code and an error code.