Crate cftime_rs

cftime-rs

Cf time implementation in rust based on the CF Conventions

Quickstart

Decoding

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>.

use cftime_rs::calendars::Calendar;
use cftime_rs::decoder::*;
use std::str::FromStr;

let to_decode = vec![0, 1, 2, 3, 4, 5];
let units = "days since 2000-01-01 00:00:00";
let calendar = Calendar::from_str("standard").unwrap();
let datetimes = to_decode.decode_cf(units, calendar).unwrap();
for (i, datetime) in datetimes.iter().enumerate() {
   println!("{}", datetime);
}

will print :

2000-01-01 00:00:00.000
2000-01-02 00:00:00.000
2000-01-03 00:00:00.000
2000-01-04 00:00:00.000
2000-01-05 00:00:00.000
2000-01-06 00:00:00.000

Encoding

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>.

use cftime_rs::calendars::Calendar;
use cftime_rs::datetime::CFDatetime;
use cftime_rs::encoder::*;
use cftime_rs::errors::Error;
use std::str::FromStr;
let calendar = Calendar::from_str("standard").unwrap();
// Create vector of datetimes and convert Vec<Result<CFDatetime, Error>>
// into Result<Vec<CFDatetime>, Error>
let to_encode: Result<Vec<CFDatetime>, Error> = vec![
   CFDatetime::from_ymd(2000, 1, 1, calendar),
   CFDatetime::from_ymd(2000, 1, 2, calendar),
   CFDatetime::from_ymd(2000, 1, 3, calendar),
   CFDatetime::from_ymd(2000, 1, 4, calendar),
   CFDatetime::from_ymd(2000, 1, 5, calendar),
   CFDatetime::from_ymd(2000, 1, 6, calendar),
]
.into_iter()
.collect();
// Define the units
let units = "days since 2000-01-01 00:00:00";
// The type annotation for result allow us to cast to type we want
// here we use Vec<i64>
let results: Vec<i64> = to_encode.unwrap().encode_cf(units, calendar).unwrap();
for result in results {
   println!("{}", result);
}

will print :

0
1
2
3
4
5

Known issues

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. 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.

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 :

Calendar	Computation Time
Standard Calendar	44.470405ms
Leap Day Calendar	8.052179ms
360-Day Calendar	12.834µs

Modules

• calendars
  Module defining the calendars and their methods
• constants
• datetime
• datetimes
  Crate that implement the logic for the different datetimes Here is the list of available datetimes :
• decoder
  Module that implements the decode_cf method for i32, i64, f32, f64, Vec<i32>, Vec<i64>, Vec<f32> and Vec<f64>.
• duration
  Module related to duration These CFDuration can be added to a CFDateTime by using the + or - operator Internally it uses the timestamp in seconds representation
• encoder
  Module that implements the encode_cf method forCFDatetime and Vec<CFDatetime>.
• errors
• parser
  Module related to parsing the date units Create a ParsedDatetime from units
• py_bindings
• timezone
• utils
  Utils crate where common behaviour for computing dates are shared