cftime_rs/
lib.rs

1//! # cftime-rs
2//!
3//! Cf time implementation in rust based on the [CF Conventions](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#time-coordinate)
4//!
5//! ## Quickstart
6//!
7//! ### Decoding
8//!
9//! Decoding needs units, and calendar and can work with `i32`, `i64`, `f32`, ``f64`` and their corresponding vector type `Vec<i32>`, `Vec<i64>`, `Vec<f32>` and `Vec<f64>`. From these type it return either a `CFDatetime` object or a `Vec<CFDatetime>`.
10//!
11//! ```rust
12//! use cftime_rs::calendars::Calendar;
13//! use cftime_rs::decoder::*;
14//! use std::str::FromStr;
15//!
16//! let to_decode = vec![0, 1, 2, 3, 4, 5];
17//! let units = "days since 2000-01-01 00:00:00";
18//! let calendar = Calendar::from_str("standard").unwrap();
19//! let datetimes = to_decode.decode_cf(units, calendar).unwrap();
20//! for (i, datetime) in datetimes.iter().enumerate() {
21//!    println!("{}", datetime);
22//! }
23//! ```
24//! will print :
25//! ```shell
26//! 2000-01-01 00:00:00.000
27//! 2000-01-02 00:00:00.000
28//! 2000-01-03 00:00:00.000
29//! 2000-01-04 00:00:00.000
30//! 2000-01-05 00:00:00.000
31//! 2000-01-06 00:00:00.000
32//! ```
33//!
34//! ### Encoding
35//!
36//! Encoding needs units and calendar and can convert a `CFDatetime` object into an `i32`, `i64`, `f32` or  `f64` or a `Vec<CFDatetime>` into `Vec<i32>`, `Vec<i64>`, `Vec<f32>` or `Vec<f64>`.
37//!
38//! ```rust
39//! use cftime_rs::calendars::Calendar;
40//! use cftime_rs::datetime::CFDatetime;
41//! use cftime_rs::encoder::*;
42//! use cftime_rs::errors::Error;
43//! use std::str::FromStr;
44//! let calendar = Calendar::from_str("standard").unwrap();
45//! // Create vector of datetimes and convert Vec<Result<CFDatetime, Error>>
46//! // into Result<Vec<CFDatetime>, Error>
47//! let to_encode: Result<Vec<CFDatetime>, Error> = vec![
48//!    CFDatetime::from_ymd(2000, 1, 1, calendar),
49//!    CFDatetime::from_ymd(2000, 1, 2, calendar),
50//!    CFDatetime::from_ymd(2000, 1, 3, calendar),
51//!    CFDatetime::from_ymd(2000, 1, 4, calendar),
52//!    CFDatetime::from_ymd(2000, 1, 5, calendar),
53//!    CFDatetime::from_ymd(2000, 1, 6, calendar),
54//! ]
55//! .into_iter()
56//! .collect();
57//! // Define the units
58//! let units = "days since 2000-01-01 00:00:00";
59//! // The type annotation for result allow us to cast to type we want
60//! // here we use Vec<i64>
61//! let results: Vec<i64> = to_encode.unwrap().encode_cf(units, calendar).unwrap();
62//! for result in results {
63//!    println!("{}", result);
64//! }
65//! ```
66//! will print :
67//! ```shell
68//! 0
69//! 1
70//! 2
71//! 3
72//! 4
73//! 5
74//! ```
75//!
76//! ## Known issues
77//!
78//! While this date calculation library can handle a wide range of dates, from approximately -291,672,107,014 BC to 291,672,107,014 AD, there are some performance considerations you should be aware of.
79//! As you move further away from the reference date of 1970-01-01 00:00:00, the time of calculation increases. This is because the library needs to account for leap years in various calendars.
80//!
81//! Here is an example of the computation of 1_000_000_000_000_000 seconds using the units "seconds since 2000-01-01 00:00:00" on my personal computer in release mode :
82//!
83//! | Calendar          | Computation Time |
84//! |-------------------|------------------|
85//! | Standard Calendar | 44.470405ms      |
86//! | Leap Day Calendar | 8.052179ms       |
87//! | 360-Day Calendar  | 12.834µs         |
88//!
89
90pub mod calendars;
91pub mod constants;
92pub mod datetime;
93pub mod datetimes;
94pub mod decoder;
95pub mod duration;
96pub mod encoder;
97pub mod errors;
98pub mod parser;
99pub mod py_bindings;
100pub mod timezone;
101pub mod utils;
cftime_rs/lib.rs

cftime_rs/
lib.rs
