Finish the initial implementation of time primitives (#380)

Author: c410-f3r

.scripts/internal-tests-0.sh

@@ -15,6 +15,7 @@ $rt test-with-features wtx arbitrary
 $rt test-with-features wtx argon2
 $rt test-with-features wtx base64
 $rt test-with-features wtx borsh
+$rt test-with-features wtx calendar
 $rt test-with-features wtx chrono
 $rt test-with-features wtx cl-aux
 $rt test-with-features wtx client-api-framework

README.md

@@ -27,6 +27,7 @@ In a way, `WTX` can be seen as an amalgamation that consolidates the functionali
 
 | Technology                                             | Similar Projects                                                   | Feature (`wtx`)          |
 | ------------------------------------------------------ | ------------------------------------------------------------------ | ------------------------ |
+| [Calendar][calendar-doc]                               | [chrono][chrono], [time][time]                                     | calendar                 |
 | [Client API Framework][client-api-framework-doc]       | N/A                                                                | client-api-framework     |
 | [Database Client][database-client-doc]                 | [jdbc][jdbc], [odbc][odbc], [sqlx][sqlx]                           | postgres, mysql          |
 | [Database Schema Manager][database-schema-manager-doc] | [flyway][flyway], [liquibase][liquibase], [refinery][refinery]     | schema-manager           |
@@ -98,6 +99,7 @@ Demonstrations of different use-cases can be found in the `wtx-instances` direct
 
 [^2]: The sum of optional and required dependencies used by the associated binaries.
 
+[calendar-doc]: https://c410-f3r.github.io/wtx/calendar/index.html
 [client-api-framework-doc]: https://c410-f3r.github.io/wtx/client-api-framework/index.html
 [database-client-doc]: https://c410-f3r.github.io/wtx/database-client/index.html
 [database-schema-manager-doc]: https://c410-f3r.github.io/wtx/database-schema-manager/index.html
@@ -110,6 +112,7 @@ Demonstrations of different use-cases can be found in the `wtx-instances` direct
 
 [axum]: https://github.com/tokio-rs/axum
 [bb8]: https://github.com/djc/bb8
+[chrono]: https://github.com/chronotope/chrono
 [deadpool]: https://github.com/deadpool-rs/deadpool
 [diesel]: https://github.com/diesel-rs/diesel
 [fastapi]: https://github.com/fastapi/fastapi
@@ -125,6 +128,7 @@ Demonstrations of different use-cases can be found in the `wtx-instances` direct
 [reqwest]: https://github.com/seanmonstar/reqwest
 [spring-boot]: https://github.com/spring-projects/spring-boot
 [sqlx]: https://github.com/launchbadge/sqlx
+[time]: https://github.com/time-rs/time
 [tokio-tungstenite]: https://github.com/snapview/tokio-tungstenite
 [tonic]: https://github.com/hyperium/tonic
 [uWebSockets]: https://github.com/uNetworking/uWebSockets

wtx-docs/src/SUMMARY.md

@@ -1,6 +1,7 @@
 # Summary
 
 - [Introduction](README.md)
+- [Calendar](calendar/README.md)
 - [Client API Framework](client-api-framework/README.md)
 - [Database Client](database-client/README.md)
   - [Encrypted Connections](database-client/encrypted-connections.md)
@@ -12,7 +13,6 @@
 - [HTTP/2](http2/README.md)
 - [Internal Development](internal-development/README.md)
 - [Pool](pool/README.md)
-- [Time](time/README.md)
 - [UI tools](ui-tools/README.md)
 - [WebSocket](web-socket/README.md)
 - [WebSocket over HTTP/2](web-socket-over-http2/README.md)

wtx-docs/src/calendar/README.md

@@ -0,0 +1,15 @@
+# Calendar
+
+Provides basic primitives to work with time-related operations.
+
+* `Time`: Clock time with nanosecond precision.
+* `Date`: Proleptic Gregorian calendar. Can represent years from -32767 to 32766.
+* `DateTime`: ISO-8601 representation without timezones.
+
+To use this functionality, it is necessary to activate the `calendar` feature.
+
+## Example
+
+```rust,edition2024,no_run
+{{#rustdoc_include ../../../wtx-instances/generic-examples/calendar.rs}}
+```

wtx-docs/src/time/README.md

@@ -2,7 +2,7 @@
 
 #![no_main]
 
-use wtx::time::DateTime;
+use wtx::calendar::DateTime;
 
 libfuzzer_sys::fuzz_target!(|(value, fmt): (Vec<u8>, Vec<u8>)| {
   let _rslt = DateTime::parse(&value, &value);

wtx-fuzz/date_time.rs

@@ -49,6 +49,11 @@ required-features = ["database-client-postgres-enum"]
 
 # Generic Examples
 
+[[example]]
+name = "calendar"
+path = "generic-examples/calendar.rs"
+required-features = ["calendar"]
+
 [[example]]
 name = "client-api-framework"
 path = "generic-examples/client-api-framework.rs"
@@ -74,10 +79,6 @@ name = "pool"
 path = "generic-examples/pool.rs"
 required-features = ["pool"]
 
-[[example]]
-name = "time"
-path = "generic-examples/time.rs"
-
 # HTTP Server Framework Examples
 
 [[example]]
@@ -154,6 +155,7 @@ database-client-postgres = ["postgres"]
 database-client-postgres-composite-type = ["postgres"]
 database-client-postgres-enum = ["postgres"]
 
+calendar = ["wtx/calendar"]
 client-api-framework = ["serde", "wtx/client-api-framework", "wtx/http-client-pool", "wtx/serde_json", "wtx/web-socket-handshake", "wtx-macros"]
 grpc-client = ["grpc", "wtx/grpc-client"]
 grpc-server = ["grpc", "wtx/grpc-server", "wtx/nightly"]

wtx-instances/Cargo.toml

@@ -0,0 +1,13 @@
+//! Basic time operation.
+
+extern crate wtx;
+
+use wtx::calendar::{Duration, Instant};
+
+fn main() -> wtx::Result<()> {
+  println!(
+    "ISO 8601 representation of the next 2 minutes in UTC: {}",
+    Instant::now_date_time(0)?.add(Duration::from_minutes(2)?)?
+  );
+  Ok(())
+}

wtx-instances/generic-examples/calendar.rs

@@ -52,6 +52,7 @@ x509-certificate = { default-features = false, optional = true, version = "0.24"
 32-tuple-impls = []
 arbitrary = ["dep:arbitrary", "std"]
 borsh = ["dep:borsh", "std"]
+calendar = []
 client-api-framework = ["data-transformation"]
 data-transformation = []
 database = []
@@ -78,7 +79,7 @@ postgres = ["base64", "crypto-common", "database", "digest", "foldhash", "hashbr
 quick-protobuf = ["dep:quick-protobuf", "std"]
 rand-compat = ["rand_core"]
 rustls = ["dep:rustls", "rustls-pki-types"]
-schema-manager = ["database"]
+schema-manager = ["calendar", "database"]
 schema-manager-dev = ["schema-manager"]
 serde = ["cl-aux?/serde", "dep:serde"]
 serde_json = ["serde", "dep:serde_json", "std"]

wtx-instances/generic-examples/time.rs

@@ -0,0 +1,93 @@
+//! Simple time utilities
+
+mod calendar_error;
+mod instant;
+
+#[cfg(feature = "calendar")]
+#[macro_use]
+mod macros;
+
+#[cfg(feature = "calendar")]
+mod ce_days;
+#[cfg(feature = "calendar")]
+mod date;
+#[cfg(feature = "calendar")]
+mod date_time;
+#[cfg(feature = "calendar")]
+mod day;
+#[cfg(feature = "calendar")]
+mod day_of_year;
+#[cfg(feature = "calendar")]
+mod duration;
+#[cfg(feature = "calendar")]
+mod format;
+#[cfg(feature = "calendar")]
+mod hour;
+#[cfg(feature = "calendar")]
+mod microsecond;
+#[cfg(feature = "calendar")]
+mod millisecond;
+#[cfg(feature = "calendar")]
+mod minute;
+#[cfg(feature = "calendar")]
+mod misc;
+#[cfg(feature = "calendar")]
+mod month;
+#[cfg(feature = "calendar")]
+mod nanosecond;
+#[cfg(feature = "calendar")]
+mod second;
+#[cfg(feature = "calendar")]
+mod time;
+#[cfg(feature = "calendar")]
+mod weekday;
+#[cfg(feature = "calendar")]
+mod year;
+
+#[cfg(feature = "calendar")]
+mod gated {
+  pub use crate::calendar::{
+    ce_days::CeDays,
+    date::Date,
+    date_time::DateTime,
+    day::Day,
+    day_of_year::DayOfYear,
+    duration::Duration,
+    format::{parse_bytes_into_tokens, time_token::TimeToken},
+    hour::Hour,
+    microsecond::Microsecond,
+    millisecond::Millisecond,
+    minute::Minute,
+    month::Month,
+    nanosecond::Nanosecond,
+    second::Second,
+    time::Time,
+    weekday::Weekday,
+    year::Year,
+  };
+
+  pub(crate) const DAYS_PER_4_YEARS: u16 = 1_461;
+  pub(crate) const DAYS_PER_NON_LEAP_YEAR: u16 = 365;
+  pub(crate) const DAYS_PER_QUADCENTURY: u32 = 146_097;
+  /// Number of days between the Common Era and the UNIX epoch.
+  pub(crate) const EPOCH_CE_DAYS: u32 = 719_163;
+  pub(crate) const MINUTES_PER_HOUR: u8 = 60;
+  pub(crate) const MILLISECONDS_PER_SECOND: u16 = 1_000;
+  pub(crate) const NANOSECONDS_PER_MICROSECONDS: u32 = 1_000;
+  pub(crate) const NANOSECONDS_PER_MILLISECOND: u32 = 1_000_000;
+  pub(crate) const NANOSECONDS_PER_SECOND: u32 = 1_000_000_000;
+  pub(crate) const SECONDS_PER_DAY: u32 = crate::calendar::misc::u16u32(SECONDS_PER_HOUR) * 24;
+  pub(crate) const SECONDS_PER_HOUR: u16 = crate::calendar::misc::u8u16(SECONDS_PER_MINUTE) * 60;
+  pub(crate) const SECONDS_PER_MINUTE: u8 = 60;
+  pub(crate) const YEARS_PER_QUADCENTURY: u16 = 400;
+
+  pub(crate) static DAYS_OF_MONTHS: [[u16; 12]; 2] = [
+    [0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334],
+    [0, 31, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335],
+  ];
+}
+
+pub use calendar_error::CalendarError;
+#[cfg(feature = "calendar")]
+pub use gated::*;
+pub use instant::Instant;

wtx/Cargo.toml

@@ -1,8 +1,10 @@
-/// Time error
+/// Calendar error
 #[derive(Debug)]
-pub enum TimeError {
+pub enum CalendarError {
   // Generic
   //
+  /// Underlying time structure couldn't hold the value generated during an arithmetic operation.
+  ArithmeticOverflow,
   /// Days from CE must be within the `-11967900` ~ `11967535` range
   InvalidCeDays {
     /// Invalid received number
@@ -47,7 +49,7 @@ pub enum TimeError {
     /// Invalid received number
     received: Option<u8>,
   },
-  /// A second can only have up to `999_999_999` nanoseconds
+  /// A second can only have up to `999_999_999` nanosecond
   InvalidNanosecond {
     /// Invalid received number
     received: u32,
@@ -61,8 +63,6 @@ pub enum TimeError {
   },
   /// A timestamp in this project can only go up to `32768-12-31`.
   InvalidTimestamp,
-  /// Underlying time structure couldn't hold the value generated during an arithmetic operation.
-  InvalidTimeArithmetic,
   /// A weekday must be, for example, "Mon" or "Monday"
   InvalidWeekday,
   /// A year be must between `-32767` and `32766`.

wtx/src/calendar.rs

@@ -1,4 +1,4 @@
-use crate::time::{Date, TimeError};
+use crate::calendar::{CalendarError, Date};
 
 /// Number of days since the common era (0001-01-01)
 #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
@@ -12,9 +12,9 @@ impl CeDays {
 
   /// Creates a new instance from a valid `num` number.
   #[inline]
-  pub const fn from_num(num: i32) -> Result<Self, TimeError> {
+  pub const fn from_num(num: i32) -> Result<Self, CalendarError> {
     if num < Date::MIN.ce_days() || num > Date::MAX.ce_days() {
-      return Err(TimeError::InvalidCeDays { received: num });
+      return Err(CalendarError::InvalidCeDays { received: num });
     }
     Ok(Self(num))
   }