Add support for Time and Time64 types (#258)

Co-authored-by: Shivanshu Raj Shrivastava <shivanshu1333@gmail.com>

Author: nohupped

Cargo.toml

@@ -78,6 +78,10 @@ required-features = ["time", "uuid", "chrono"]
 name = "data_types_variant"
 required-features = ["time"]
 
+[[example]]
+name = "time_types_example"
+required-features = ["time", "chrono"]
+
 [profile.release]
 debug = true
 

README.md

@@ -400,6 +400,38 @@ How to choose between all these features? Here are some considerations:
     }
 
 
+    ```
+    </details>
+* `Time` maps to/from i32 or a newtype around it. The Time data type is used to store a time value independent of any calendar date. It is ideal for representing daily schedules, event times, or any situation where only the time component (hours, minutes, seconds) is important.
+    * [`time:Duration`](https://docs.rs/time/latest/time/struct.Duration.html) is is supported by using `serde::time::*`, requiring the `time` feature.
+    * [`chrono::Duration`](https://docs.rs/chrono/latest/chrono/type.Duration.html) is supported by using `serde::chrono::*`, which is an alias to `TimeDelta`, requiring the `chrono` feature
+    <details>
+    <summary>Example</summary>
+
+    ```rust,ignore
+    #[derive(Row, Serialize, Deserialize)]
+    struct MyRow {
+        #[serde(with = "clickhouse::serde::chrono::time64::secs")]
+        t0: chrono::Duration,
+        #[serde(with = "clickhouse::serde::chrono::time64::secs::option")]
+        t0_opt: Option<chrono::Duration>,
+    }
+
+    ```
+    </details>
+* `Time64(_)` maps to/from i64 or a newtype around it. The Time data type is used to store a time value independent of any calendar date. It is ideal for representing daily schedules, event times, or any situation where only the time component (hours, minutes, seconds) is important.
+    * [`time:Duration`](https://docs.rs/time/latest/time/struct.Duration.html) is is supported by using `serde::time::*`, requiring the `time` feature.
+    * [`chrono::Duration`](https://docs.rs/chrono/latest/chrono/type.Duration.html) is supported by using `serde::chrono::*`, requiring the `chrono` feature
+    <details>
+    <summary>Example</summary>
+
+    ```rust,ignore
+    #[derive(Row, Serialize, Deserialize)]
+    struct MyRow {
+        #[serde(with = "clickhouse::serde::time::time")]
+        t0: Time,
+    }
+
     ```
     </details>
 * `Tuple(A, B, ...)` maps to/from `(A, B, ...)` or a newtype around it.

examples/time_types_example.rs

@@ -0,0 +1,131 @@
+use chrono::Duration;
+use clickhouse::Client;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Serialize, Deserialize, clickhouse::Row)]
+struct TimeExample {
+    #[serde(with = "clickhouse::serde::time::time")]
+    time_field: time::Duration,
+
+    #[serde(with = "clickhouse::serde::time::time::option")]
+    time_optional: Option<time::Duration>,
+
+    #[serde(with = "clickhouse::serde::time::time64::secs")]
+    time64_seconds: time::Duration,
+
+    #[serde(with = "clickhouse::serde::time::time64::millis")]
+    time64_millis: time::Duration,
+
+    #[serde(with = "clickhouse::serde::time::time64::micros")]
+    time64_micros: time::Duration,
+
+    #[serde(with = "clickhouse::serde::time::time64::nanos")]
+    time64_nanos: time::Duration,
+}
+
+#[derive(Debug, Serialize, Deserialize, clickhouse::Row)]
+struct TimeExampleChrono {
+    #[serde(with = "clickhouse::serde::chrono::time")]
+    time_field: Duration,
+
+    #[serde(with = "clickhouse::serde::chrono::time::option")]
+    time_optional: Option<Duration>,
+
+    #[serde(with = "clickhouse::serde::chrono::time64::secs")]
+    time64_seconds: Duration,
+
+    #[serde(with = "clickhouse::serde::chrono::time64::millis")]
+    time64_millis: Duration,
+
+    #[serde(with = "clickhouse::serde::chrono::time64::micros")]
+    time64_micros: Duration,
+
+    #[serde(with = "clickhouse::serde::chrono::time64::nanos")]
+    time64_nanos: Duration,
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let client = Client::default();
+
+    let create_table_sql = r#"
+        CREATE TABLE IF NOT EXISTS time_example (
+            time_field Time,
+            time_optional Nullable(Time),
+            time64_seconds Time64(0),
+            time64_millis Time64(3),
+            time64_micros Time64(6),
+            time64_nanos Time64(9)
+        ) ENGINE = MergeTree()
+        ORDER BY time_field
+    "#;
+
+    client.query(create_table_sql).execute().await?;
+
+    // Insert data using time crate
+    let time_example = TimeExample {
+        time_field: time::Duration::seconds(12 * 3600 + 34 * 60 + 56),
+        time_optional: Some(time::Duration::seconds(23 * 3600 + 59 * 60 + 59)),
+        time64_seconds: time::Duration::seconds(3600 + 2 * 60 + 3),
+        time64_millis: time::Duration::seconds(4 * 3600 + 5 * 60 + 6)
+            + time::Duration::milliseconds(123),
+        time64_micros: time::Duration::seconds(7 * 3600 + 8 * 60 + 9)
+            + time::Duration::microseconds(456_789),
+        time64_nanos: time::Duration::seconds(10 * 3600 + 11 * 60 + 12)
+            + time::Duration::nanoseconds(123_456_789),
+    };
+
+    let mut insert = client.insert::<TimeExample>("time_example")?;
+    insert.write(&time_example).await?;
+    insert.end().await?;
+
+    // Insert data using chrono crate
+    let time_example_chrono = TimeExampleChrono {
+        time_field: Duration::seconds(13 * 3600 + 45 * 60),
+        time_optional: Some(Duration::seconds(1)),
+        time64_seconds: Duration::seconds(2 * 3600 + 3 * 60 + 4),
+        time64_millis: Duration::seconds(5 * 3600 + 6 * 60 + 7) + Duration::milliseconds(456),
+        time64_micros: Duration::seconds(8 * 3600 + 9 * 60 + 10) + Duration::microseconds(789_012),
+        time64_nanos: Duration::seconds(11 * 3600 + 12 * 60 + 13)
+            + Duration::nanoseconds(987_654_321),
+    };
+
+    let mut insert = client.insert::<TimeExampleChrono>("time_example")?;
+    insert.write(&time_example_chrono).await?;
+    insert.end().await?;
+
+    // Insert chrono edge cases
+    let edge_cases = vec![
+        Duration::seconds(-999 * 3600 - 59 * 60 - 59), // Min
+        Duration::zero(),                              // Midnight
+        Duration::seconds(999 * 3600 + 59 * 60 + 59),  // Max
+    ];
+
+    for (i, edge) in edge_cases.into_iter().enumerate() {
+        let data = TimeExampleChrono {
+            time_field: edge,
+            time_optional: Some(edge),
+            time64_seconds: edge,
+            time64_millis: edge,
+            time64_micros: edge,
+            time64_nanos: edge,
+        };
+        let mut insert = client.insert::<TimeExampleChrono>("time_example")?;
+        insert.write(&data).await?;
+        insert.end().await?;
+        println!("Inserted edge case #{i}: {edge:?}");
+    }
+
+    // Query the data
+    let rows: Vec<TimeExample> = client
+        .query("SELECT * FROM time_example ORDER BY time_field")
+        .fetch_all()
+        .await?;
+    for time_example in rows {
+        println!("Time example: {time_example:?}");
+    }
+
+    println!("Time and Time64 types example completed successfully!");
+
+    Ok(())
+}

src/rowbinary/tests.rs

@@ -7,6 +7,12 @@ struct Timestamp32(u32);
 #[derive(Debug, PartialEq, Serialize, Deserialize)]
 struct Timestamp64(u64);
 
+#[derive(Debug, PartialEq, Serialize, Deserialize)]
+struct Time32(i32);
+
+#[derive(Debug, PartialEq, Serialize, Deserialize)]
+struct Time64(i64);
+
 #[derive(Debug, PartialEq, Serialize, Deserialize)]
 struct FixedPoint64(i64);
 
@@ -25,6 +31,8 @@ struct Sample<'a> {
     float64: f64,
     datetime: Timestamp32,
     datetime64: Timestamp64,
+    time32: Time32,
+    time64: Time64,
     decimal64: FixedPoint64,
     decimal128: FixedPoint128,
     string: &'a str,
@@ -51,6 +59,8 @@ impl Row for Sample<'_> {
         "float64",
         "datetime",
         "datetime64",
+        "time32",
+        "time64",
         "decimal64",
         "decimal128",
         "string",
@@ -61,7 +71,7 @@ impl Row for Sample<'_> {
         "array",
         "boolean",
     ];
-    const COLUMN_COUNT: usize = 19;
+    const COLUMN_COUNT: usize = 21;
     const KIND: crate::row::RowKind = crate::row::RowKind::Struct;
 
     type Value<'a> = Sample<'a>;
@@ -79,6 +89,8 @@ fn sample() -> Sample<'static> {
         float64: 42.42,
         datetime: Timestamp32(2_301_990_162),
         datetime64: Timestamp64(2_301_990_162_123),
+        time32: Time32(42_000), // 11:40:00 (42,000 seconds since midnight)
+        time64: Time64(42_000_000_000), // 11:40:00.000000000 (42,000,000,000 nanoseconds since midnight)
         decimal64: FixedPoint64(4242 * 10_000_000),
         decimal128: FixedPoint128(4242 * 10_000_000),
         string: "01234",
@@ -115,6 +127,10 @@ fn sample_serialized() -> Vec<u8> {
         // [DateTime64(3)] 2042-12-12 12:42:42'123
         //       (ts: 2301990162123)
         0xcb, 0x4e, 0x4e, 0xf9, 0x17, 0x02, 0x00, 0x00, //
+        // [Time32] 11:40:00 (42,000 seconds since midnight)
+        0x10, 0xa4, 0x00, 0x00, //
+        // [Time64] 11:40:00.000000000 (42,000,000,000 nanoseconds since midnight)
+        0x00, 0x24, 0x65, 0xc7, 0x09, 0x00, 0x00, 0x00, //
         // [Decimal64(9)] 42.420000000
         0x00, 0xd5, 0x6d, 0xe0, 0x09, 0x00, 0x00, 0x00, //
         // [Decimal128(9)] 42.420000000
@@ -160,3 +176,144 @@ fn it_deserializes() {
         assert_eq!(actual, sample());
     }
 }
+
+#[test]
+fn it_serializes_time64() {
+    let value = 42_000_000_000;
+    let time64 = Time64(value);
+    println!("Time64 value: {}", time64.0);
+    let mut actual = Vec::new();
+    super::serialize_into(&mut actual, &time64).unwrap();
+
+    // Expected: 42000000000 in little-endian
+    let expected = value.to_le_bytes();
+
+    assert_eq!(actual, expected, "Time64 serialization mismatch");
+}
+
+#[test]
+fn it_deserializes_time64() {
+    let value_bytes = 42_000_000_000_i64.to_le_bytes();
+    let time64 = { Time64(i64::from_le_bytes(value_bytes)) };
+    assert_eq!(time64.0, 42_000_000_000, "Time deserialization mismatch");
+}
+
+#[test]
+fn it_serializes_time32() {
+    let value = 42_000;
+    let time32 = Time32(value);
+    let mut actual = Vec::new();
+    super::serialize_into(&mut actual, &time32).unwrap();
+    let expected = value.to_le_bytes();
+    assert_eq!(actual, expected, "Time32 serialization mismatch");
+}
+
+#[test]
+fn it_deserializes_time32() {
+    let value_bytes = 42_000_i32.to_le_bytes();
+    let time64 = { Time32(i32::from_le_bytes(value_bytes)) };
+    assert_eq!(time64.0, 42_000, "Time deserialization mismatch");
+}
+
+#[test]
+fn it_serializes_option_time32_some() {
+    let value = 42_000;
+    let time: Option<Time32> = Some(Time32(value));
+    let mut actual = Vec::new();
+    super::serialize_into(&mut actual, &time).unwrap();
+
+    // Nullable encoding: 0x00 = not null, followed by value
+    let mut expected = vec![0x00];
+    // extend after not null
+    expected.extend_from_slice(&value.to_le_bytes());
+
+    assert_eq!(
+        actual, expected,
+        "Option<Time32> (Some) serialization mismatch"
+    );
+}
+
+#[cfg(feature = "chrono")]
+#[test]
+fn it_serializes_time32_overflow_fails() {
+    use crate::serde::chrono::time;
+    use chrono::Duration;
+
+    // Duration that exceeds i32::MAX
+    let value = Duration::seconds(i64::from(i32::MAX) + 1);
+
+    // Use a dummy serializer just to trigger the error
+    let result = time::serialize(&value, serde_json::value::Serializer);
+
+    assert!(result.is_err(), "Expected error due to overflow");
+
+    let err = result.unwrap_err().to_string();
+    assert!(
+        err.contains("cannot be represented as Time"),
+        "Unexpected error message: {err}"
+    );
+}
+
+#[cfg(feature = "time")]
+#[test]
+fn it_time_serializes_time64_millis_overflow_fails() {
+    use crate::serde::time::time64::millis;
+    use time::Duration;
+
+    let value = Duration::milliseconds(i64::MAX) + Duration::milliseconds(1);
+
+    let result = millis::serialize(&value, serde_json::value::Serializer);
+
+    assert!(
+        result.is_err(),
+        "Expected error due to milliseconds overflow"
+    );
+
+    let err = result.unwrap_err().to_string();
+    assert!(
+        err.contains("milliseconds too large for i64"),
+        "Unexpected error message: {err}"
+    );
+}
+
+#[cfg(feature = "time")]
+#[test]
+fn it_time_serializes_time64_micros_overflow_fails() {
+    use crate::serde::time::time64::micros;
+    use time::Duration;
+
+    let value = Duration::microseconds(i64::MAX) + Duration::microseconds(1);
+    let result = micros::serialize(&value, serde_json::value::Serializer);
+
+    assert!(
+        result.is_err(),
+        "Expected error due to microseconds overflow"
+    );
+
+    let err = result.unwrap_err().to_string();
+    assert!(
+        err.contains("microseconds too large for i64"),
+        "Unexpected error message: {err}"
+    );
+}
+
+#[cfg(feature = "time")]
+#[test]
+fn it_time_serializes_time64_nanos_overflow_fails() {
+    use crate::serde::time::time64::nanos;
+    use time::Duration;
+
+    let value = Duration::nanoseconds(i64::MAX) + Duration::nanoseconds(1);
+    let result = nanos::serialize(&value, serde_json::value::Serializer);
+
+    assert!(
+        result.is_err(),
+        "Expected error due to nanoseconds overflow"
+    );
+
+    let err = result.unwrap_err().to_string();
+    assert!(
+        err.contains("nanoseconds too large for i64"),
+        "Unexpected error message: {err}"
+    );
+}