Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_datime/README.md

6.4 KiB, 13 runs

created by r1870400018:6285, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1# fe2o3_datime
2
3A comprehensive date and time library for the Hematite ecosystem with modern serialization and universal identification.
4
5## Features
6
7### 🗓️ **Multiple Calendar Systems**
8- **Gregorian** (default): International standard calendar
9- **Julian**: Pre-reform calendar with simpler leap year rules
10- **Islamic/Hijri**: Lunar calendar starting from Hijra (622 CE)
11- **Japanese**: Imperial era-based calendar system
12- **Thai Buddhist**: Gregorian structure + 543 years
13- **Minguo (ROC)**: Republic of China calendar starting from 1912
14- **Holocene**: Scientific calendar adding 10,000 years
15
16### 📊 **JDAT Serialization Integration**
17- **String format**: Human-readable, leverages existing parsers
18- **Binary format**: Ultra-compact with namex LocalId (1 byte per calendar)
19- **Structured format**: Rich metadata for configuration and debugging
20
21### 🏷️ **Namex Universal Identification**
22- **NamexId**: 256-bit globally unique identifiers
23- **LocalId**: 8-bit efficient identifiers for binary operations
24- **Database integration**: Support for namex metadata databases
25
26### 🌐 **Advanced Timezone Support**
27- **IANA TZif integration**: Complete binary format parsing
28- **DST handling**: Automatic daylight saving time transitions
29- **Historical accuracy**: Support for timezone rule changes over time
30- **Ambiguity resolution**: Handles "spring forward" and "fall back" scenarios
31
32### ⚡ **High Performance**
33- **Nanosecond precision**: Sub-second accuracy for all operations
34- **Efficient conversions**: Optimized calendar-to-calendar transformations
35- **Binary serialization**: Minimal overhead for storage and transmission
36- **Batch operations**: Optimized time series processing
37
38## Quick Start
39
40```rust
41use oxedyne_fe2o3_datime::{
42 calendar::Calendar,
43 time::{CalClock, CalClockZone},
44};
45use oxedyne_fe2o3_core::prelude::*;
46
47// Create dates in different calendar systems
48let gregorian = Calendar::Gregorian;
49let islamic = Calendar::Islamic;
50let zone = res!(CalClockZone::new("UTC"));
51
52// Create a date - new API using Calendar enum
53let greg_date = res!(gregorian.date(2024, 6, 23, zone.clone()));
54let islamic_date = res!(islamic.date(1445, 12, 15, zone.clone()));
55
56// Convert between calendar systems
57let converted = res!(gregorian.convert_date(&islamic_date, &gregorian));
58
59// Create complete date-time objects
60let now = res!(CalClock::now_utc());
61let custom_time = res!(CalClock::new(2024, 6, 23, 14, 30, 15, 123456789, zone));
62
63// JDAT serialization examples
64let calendar_text = res!(gregorian.to_dat()); // "gregorian"
65let calendar_binary = res!(gregorian.to_dat_binary()); // 1 byte
66let datetime_text = res!(now.to_dat()); // "2024-06-23 14:30:15.123456789 UTC"
67let datetime_binary = res!(now.to_dat_binary()); // 16 bytes
68```
69
70## JDAT Integration Examples
71
72### Configuration with Multiple Formats
73
74```rust
75use oxedyne_fe2o3_jdat::prelude::*;
76
77// User-friendly configuration
78#[derive(FromDatMap, ToDatMap)]
79struct CalendarConfig {
80 default_calendar: Calendar, // Serializes as "gregorian"
81 timezone: String, // "America/New_York"
82 business_hours_start: ClockTime, // "09:00:00"
83 business_hours_end: ClockTime, // "17:00:00"
84}
85
86// Time series with efficient binary storage
87let measurements: Vec<(CalClock, f64)> = collect_sensor_data();
88let binary_data = res!(measurements.to_dat()?.to_bytes(Vec::new()));
89// Saves ~60% space compared to JSON
90```
91
92### API Integration
93
94```rust
95// REST API response with type-safe serialization
96let api_response = mapdat! {
97 "current_time" => res!(CalClock::now_utc().to_dat()),
98 "supported_calendars" => listdat![
99 Calendar::all().map(|c| res!(c.to_dat())).collect::<Result<Vec<_>, _>>()
100 ],
101 "timezone_info" => res!(zone.to_dat_structured()),
102};
103
104let json_response = res!(api_response.encode_string());
105```
106
107## Namex Integration
108
109### Universal Calendar Identification
110
111```rust
112use oxedyne_fe2o3_namex::id::InNamex;
113
114// Get universal 256-bit identifier
115let namex_id = res!(Calendar::Gregorian.name_id());
116let local_id = Calendar::Gregorian.local_id(); // LocalId(1)
117
118// Binary serialization uses efficient LocalId
119let compact_binary = res!(Calendar::Islamic.to_dat_binary()); // Just 1 byte!
120
121// Structured format includes rich metadata
122let metadata = res!(Calendar::Japanese.to_dat_structured());
123// Includes: id, name, description, namex_id, local_id, epoch_year
124```
125
126## Performance Characteristics
127
128### Space Efficiency
129
130| Format | Calendar Reference | CalClock Timestamp |
131|--------|-------------------|-------------------|
132| **String** | ~10 bytes ("gregorian") | ~30 bytes ("2024-06-23T14:30:15Z") |
133| **Binary** | **1 byte** (LocalId) | **16 bytes** (i64 + zone) |
134| **Savings** | **90%** | **47%** |
135
136### Use Case Performance
137
138- **Configuration files**: Human-readable with automatic parsing
139- **Time series**: Ultra-compact binary with nanosecond precision
140- **APIs**: JSON-compatible with type safety
141- **Inter-service**: Efficient binary with universal identification
142
143## Calendar System Details
144
145### Epoch Years and Conversions
146
147| Calendar | Epoch Year | Example Conversion |
148|----------|------------|-------------------|
149| **Gregorian** | 1 CE | 2024 = 2024 |
150| **Islamic** | 622 CE | 1445 ≈ 2024 |
151| **Thai** | -543 CE | 2567 = 2024 |
152| **Minguo** | 1912 CE | 113 = 2024 |
153| **Holocene** | -9999 CE | 12024 = 2024 |
154
155### Leap Year Rules
156
157- **Gregorian/Thai/Minguo/Holocene**: Every 4 years, except centuries not divisible by 400
158- **Julian**: Every 4 years, no exceptions
159- **Islamic**: 30-year cycle with leap years in positions 2, 5, 7, 10, 13, 16, 18, 21, 24, 26, 29
160
161## Integration with fe2o3 Ecosystem
162
163fe2o3_datime seamlessly integrates with other Hematite components:
164
165- **fe2o3_jdat**: Type-safe serialization with multiple format levels
166- **fe2o3_namex**: Universal identification and metadata databases
167- **fe2o3_core**: Error handling with `res!` macro and `Outcome` types
168- **fe2o3_data**: Efficient data structures for time series operations
169
170## Migration from calclock
171
172```rust
173// OLD API (calclock)
174use oxedyne_fe2o3_calclock::calendar::CalendarDate;
175let date = CalendarDate::new(2024, 1, 15, zone)?;
176
177// NEW API (datime)
178use oxedyne_fe2o3_datime::calendar::Calendar;
179let calendar = Calendar::new(); // Default Gregorian
180let date = res!(calendar.date(2024, 1, 15, zone));
181```
182
183The new API provides:
184- **Type safety**: Calendar system is explicit
185- **Extensibility**: Easy to add new calendar systems
186- **Efficiency**: Direct conversion between any calendar systems
187- **Serialization**: Built-in JDAT and namex support