nautilus_core/ffi/
datetime.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Thin FFI wrappers around the date/time conversion utilities in `nautilus-core`.
17//!
18//! The Rust implementation lives in `crate::datetime`; this module exposes the conversions to C.
19//! Each exported function forwards directly to its Rust counterpart and inherits the same semantics
20//! and safety guarantees.
21
22use std::ffi::c_char;
23
24use crate::{
25    datetime::{unix_nanos_to_iso8601, unix_nanos_to_iso8601_millis},
26    ffi::{abort_on_panic, string::str_to_cstr},
27};
28
29/// Converts a UNIX nanoseconds timestamp to an ISO 8601 (RFC 3339) format C string pointer.
30#[cfg(feature = "ffi")]
31#[unsafe(no_mangle)]
32pub extern "C" fn unix_nanos_to_iso8601_cstr(timestamp_ns: u64) -> *const c_char {
33    abort_on_panic(|| str_to_cstr(&unix_nanos_to_iso8601(timestamp_ns.into())))
34}
35
36/// Converts a UNIX nanoseconds timestamp to an ISO 8601 (RFC 3339) format C string pointer
37/// with millisecond precision.
38#[cfg(feature = "ffi")]
39#[unsafe(no_mangle)]
40pub extern "C" fn unix_nanos_to_iso8601_millis_cstr(timestamp_ns: u64) -> *const c_char {
41    abort_on_panic(|| str_to_cstr(&unix_nanos_to_iso8601_millis(timestamp_ns.into())))
42}
43
44/// Converts seconds to nanoseconds (ns).
45#[cfg(feature = "ffi")]
46#[unsafe(no_mangle)]
47pub extern "C" fn secs_to_nanos(secs: f64) -> u64 {
48    abort_on_panic(|| crate::datetime::secs_to_nanos_unchecked(secs))
49}
50
51/// Converts seconds to milliseconds (ms).
52///
53/// # Panics
54///
55/// Panics if [`crate::datetime::secs_to_millis`] returns an error for `secs`.
56/// The panic is caught by [`abort_on_panic`] and converted into a process abort
57/// across the FFI boundary.
58#[cfg(feature = "ffi")]
59#[unsafe(no_mangle)]
60pub extern "C" fn secs_to_millis(secs: f64) -> u64 {
61    abort_on_panic(|| {
62        crate::datetime::secs_to_millis(secs).expect("secs_to_millis: invalid or overflowing input")
63    })
64}
65
66/// Converts milliseconds (ms) to nanoseconds (ns).
67#[cfg(feature = "ffi")]
68#[unsafe(no_mangle)]
69pub extern "C" fn millis_to_nanos(millis: f64) -> u64 {
70    abort_on_panic(|| crate::datetime::millis_to_nanos_unchecked(millis))
71}
72
73/// Converts microseconds (μs) to nanoseconds (ns).
74#[cfg(feature = "ffi")]
75#[unsafe(no_mangle)]
76pub extern "C" fn micros_to_nanos(micros: f64) -> u64 {
77    abort_on_panic(|| crate::datetime::micros_to_nanos_unchecked(micros))
78}
79
80/// Converts nanoseconds (ns) to seconds.
81#[cfg(feature = "ffi")]
82#[unsafe(no_mangle)]
83pub extern "C" fn nanos_to_secs(nanos: u64) -> f64 {
84    abort_on_panic(|| crate::datetime::nanos_to_secs(nanos))
85}
86
87/// Converts nanoseconds (ns) to milliseconds (ms).
88#[cfg(feature = "ffi")]
89#[unsafe(no_mangle)]
90pub extern "C" fn nanos_to_millis(nanos: u64) -> u64 {
91    abort_on_panic(|| crate::datetime::nanos_to_millis(nanos))
92}
93
94/// Converts nanoseconds (ns) to microseconds (μs).
95#[cfg(feature = "ffi")]
96#[unsafe(no_mangle)]
97pub extern "C" fn nanos_to_micros(nanos: u64) -> u64 {
98    abort_on_panic(|| crate::datetime::nanos_to_micros(nanos))
99}
100
101#[cfg(test)]
102mod tests {
103    use std::ffi::CStr;
104
105    use rstest::rstest;
106
107    use super::*;
108    use crate::ffi::string::cstr_drop;
109
110    #[rstest]
111    fn test_unix_nanos_to_iso8601_cstr_conversions() {
112        let timestamp_ns = 1_702_857_600_123_456_789;
113
114        let nanos = take_cstr(unix_nanos_to_iso8601_cstr(timestamp_ns));
115        let millis = take_cstr(unix_nanos_to_iso8601_millis_cstr(timestamp_ns));
116
117        assert_eq!(nanos, "2023-12-18T00:00:00.123456789Z");
118        assert_eq!(millis, "2023-12-18T00:00:00.123Z");
119    }
120
121    #[rstest]
122    fn test_time_unit_conversions() {
123        assert_eq!(secs_to_nanos(1.25), 1_250_000_000);
124        assert_eq!(secs_to_millis(1.25), 1_250);
125        assert_eq!(millis_to_nanos(1.25), 1_250_000);
126        assert_eq!(micros_to_nanos(1.25), 1_250);
127        assert_eq!(
128            nanos_to_secs(42_897_123_111).to_bits(),
129            42.897_123_111_f64.to_bits()
130        );
131        assert_eq!(nanos_to_millis(1_234_567_890), 1_234);
132        assert_eq!(nanos_to_micros(1_234_567_890), 1_234_567);
133    }
134
135    fn take_cstr(ptr: *const c_char) -> String {
136        // SAFETY: The FFI conversion functions return valid pointers allocated by `str_to_cstr`
137        let value = unsafe { CStr::from_ptr(ptr) }.to_str().unwrap().to_owned();
138        // SAFETY: The pointer was allocated by `str_to_cstr` and has not been freed
139        unsafe { cstr_drop(ptr) };
140        value
141    }
142}
nautilus_core/ffi/datetime.rs

nautilus_core/ffi/
datetime.rs
