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