aimx/info_library/
date_cards.rs

1//! Date and time function documentation cards.
2//!
3//! Provides comprehensive FunctionCard instances for all 13 date manipulation
4//! functions in the Aim standard library, including detailed usage examples
5//! and cross-references between related functions.
6//!
7//! ## Date Format Specifications
8//!
9//! The date functions support strftime-style format patterns:
10//!
11//! ### Standard Formats
12//! - **YYYY-MM-DD**: ISO format (2024-01-15)
13//! - **MM/DD/YYYY**: US format (01/15/2024)
14//! - **DD/MM/YYYY**: European format (15/01/2024)
15//! - **YYYY-MM-DD HH:mm:ss**: Full datetime (2024-01-15 14:30:45)
16//!
17//! ### Custom Patterns
18//! - **yyyy**: 4-digit year
19//! - **yy**: 2-digit year
20//! - **MM**: 2-digit month
21//! - **dd**: 2-digit day
22//! - **HH**: 24-hour format
23//! - **mm**: Minutes
24//! - **ss**: Seconds
25//! - **Z**: Timezone offset
26//!
27//! ### Timezone Handling
28//! - All dates are stored and calculated in UTC by default
29//! - Automatic daylight saving time handling
30//! - Offset calculation for display purposes
31//! - Consistent behavior across different timezones
32//!
33//! ### Business Context
34//! Common use cases for date functions:
35//! - Invoice due date calculations
36//! - Report generation scheduling
37//! - Age calculations
38//! - Business day calculations
39//! - Deadline tracking
40//! - Timezone-aware operations
41//! - Date arithmetic (adding business days, month-end calculations)
42//! - Fiscal year operations and quarter boundaries
43
44use super::function_card::{ArgumentInfo, FunctionCard};
45
46/// All date function documentation cards.
47pub const DATE_CARDS: &[FunctionCard] = &[
48    // as_date(text, format) -> DateTime
49    FunctionCard {
50        identifier: "as_date",
51        signature: "as_date(text, format)",
52        brief: "Parse text into a date/time value using a format string.",
53        description: "Converts a text string into a DateTime value by parsing it according \
54                      to the specified format string. This function supports strftime-style \
55                      format patterns and is the inverse operation of format_date. It's \
56                      essential for importing dates from external sources, parsing user \
57                      input, or converting text representations to date values for calculations.",
58        arguments: &[
59            &ArgumentInfo {
60                label: "text",
61                description: "Text string to parse into a date",
62                type_hint: "Arc<str>",
63                optional: false,
64            },
65            &ArgumentInfo {
66                label: "format",
67                description: "Format string specifying the date pattern (e.g., \"YYYY-MM-DD\")",
68                type_hint: "Arc<str>",
69                optional: false,
70            },
71        ],
72        returns: "Parsed DateTime value",
73        errors: "Fails if text doesn't match the format pattern or contains invalid date values",
74        categories: &["date"],
75        examples: &[
76            r#"as_date("2024-01-15", "YYYY-MM-DD") => 2024-01-15T00:00:00Z"#,
77            r#"as_date("01/15/2024", "MM/DD/YYYY") => 2024-01-15T00:00:00Z"#,
78            r#"as_date("15/01/2024", "DD/MM/YYYY") => 2024-01-15T00:00:00Z"#,
79            r#"as_date("2024-01-15 14:30:45", "YYYY-MM-DD HH:mm:ss") => 2024-01-15T14:30:45Z"#,
80        ],
81    },
82    
83    // format_date(date, format) -> Arc<str>
84    FunctionCard {
85        identifier: "format_date",
86        signature: "format_date(date, format)",
87        brief: "Format a date/time value according to a format string.",
88        description: "Converts a DateTime value into a text string using the specified format \
89                      pattern. This function supports strftime-style format codes and is the \
90                      inverse operation of as_date. It's essential for displaying dates in \
91                      user-friendly formats, generating reports, or exporting data to text-based systems.",
92        arguments: &[
93            &ArgumentInfo {
94                label: "date",
95                description: "DateTime value to format",
96                type_hint: "DateTime",
97                optional: false,
98            },
99            &ArgumentInfo {
100                label: "format",
101                description: "Format string specifying the output pattern",
102                type_hint: "Arc<str>",
103                optional: false,
104            },
105        ],
106        returns: "Formatted date string (Arc<str>)",
107        errors: "Fails if format string contains invalid format codes",
108        categories: &["date"],
109        examples: &[
110            r#"format_date(today(), "YYYY-MM-DD") => "2024-01-15""#,
111            r#"format_date(today(), "MM/DD/YYYY") => "01/15/2024""#,
112            r#"format_date(today(), "DD/MM/YYYY") => "15/01/2024""#,
113            r#"format_date(today(), "YYYY-MM-DD HH:mm:ss") => "2024-01-15 14:30:45""#,
114        ],
115    },
116    
117    // today() -> DateTime
118    FunctionCard {
119        identifier: "today",
120        signature: "today()",
121        brief: "Get the current date and time in UTC.",
122        description: "Returns the current date and time at the moment of evaluation in UTC \
123                      timezone. This function is essential for timestamping events, calculating \
124                      durations, creating time-based conditions, or any operation that requires \
125                      the current date/time. The result is always in UTC to ensure consistent \
126                      behavior across different timezones.",
127        arguments: &[],
128        returns: "Current date and time (DateTime)",
129        errors: "None - always succeeds",
130        categories: &["date"],
131        examples: &[
132            r#"today() => 2024-01-15T14:30:45Z"#,
133            r#"year(today()) => 2024"#,
134            r#"month(today()) => 1"#,
135            r#"day(today()) => 15"#,
136        ],
137    },
138    
139    // now() -> DateTime
140    FunctionCard {
141        identifier: "now",
142        signature: "now()",
143        brief: "Get the current date and time in UTC (alias for today).",
144        description: "Returns the current date and time at the moment of evaluation in UTC \
145                      timezone. This is an alias for the today() function, providing \
146                      alternative naming that's more familiar to users coming from other \
147                      programming languages or spreadsheet applications.",
148        arguments: &[],
149        returns: "Current date and time (DateTime)",
150        errors: "None - always succeeds",
151        categories: &["date"],
152        examples: &[
153            r#"now() => 2024-01-15T14:30:45Z"#,
154            r#"year(now()) => 2024"#,
155            r#"days_between(now(), as_date("2024-12-31", "YYYY-MM-DD")) => 341"#,
156        ],
157    },
158    
159    // year(date) -> f64
160    FunctionCard {
161        identifier: "year",
162        signature: "year(date)",
163        brief: "Extract the year component from a date/time value.",
164        description: "Returns the year portion of a DateTime value as a numeric value. This \
165                      function is commonly used for date-based calculations, grouping data \
166                      by year, age calculations, or extracting temporal components for \
167                      analysis and reporting.",
168        arguments: &[
169            &ArgumentInfo {
170                label: "date",
171                description: "DateTime value to extract year from",
172                type_hint: "DateTime",
173                optional: false,
174            },
175        ],
176        returns: "Year as a number (f64)",
177        errors: "None - always succeeds",
178        categories: &["date"],
179        examples: &[
180            r#"year(as_date("2024-01-15", "YYYY-MM-DD")) => 2024"#,
181            r#"year(today()) => 2024"#,
182            r#"year(as_date("1999-12-31", "YYYY-MM-DD")) => 1999"#,
183        ],
184    },
185    
186    // month(date) -> f64
187    FunctionCard {
188        identifier: "month",
189        signature: "month(date)",
190        brief: "Extract the month component from a date/time value.",
191        description: "Returns the month portion of a DateTime value as a numeric value \
192                      (1-12). This function is useful for date-based calculations, grouping \
193                      data by month, seasonal analysis, or extracting temporal components \
194                      for reporting and analysis.",
195        arguments: &[
196            &ArgumentInfo {
197                label: "date",
198                description: "DateTime value to extract month from",
199                type_hint: "DateTime",
200                optional: false,
201            },
202        ],
203        returns: "Month as a number (1-12) (f64)",
204        errors: "None - always succeeds",
205        categories: &["date"],
206        examples: &[
207            r#"month(as_date("2024-01-15", "YYYY-MM-DD")) => 1"#,
208            r#"month(today()) => 1"#,
209            r#"month(as_date("2024-12-31", "YYYY-MM-DD")) => 12"#,
210        ],
211    },
212    
213    // day(date) -> f64
214    FunctionCard {
215        identifier: "day",
216        signature: "day(date)",
217        brief: "Extract the day component from a date/time value.",
218        description: "Returns the day of the month portion of a DateTime value as a numeric \
219                      value (1-31). This function is commonly used for date calculations, \
220                      extracting day components for analysis, or working with specific days \
221                      within a month.",
222        arguments: &[
223            &ArgumentInfo {
224                label: "date",
225                description: "DateTime value to extract day from",
226                type_hint: "DateTime",
227                optional: false,
228            },
229        ],
230        returns: "Day of month as a number (1-31) (f64)",
231        errors: "None - always succeeds",
232        categories: &["date"],
233        examples: &[
234            r#"day(as_date("2024-01-15", "YYYY-MM-DD")) => 15"#,
235            r#"day(today()) => 15"#,
236            r#"day(as_date("2024-12-31", "YYYY-MM-DD")) => 31"#,
237        ],
238    },
239    
240    // hour(date) -> f64
241    FunctionCard {
242        identifier: "hour",
243        signature: "hour(date)",
244        brief: "Extract the hour component from a date/time value.",
245        description: "Returns the hour portion of a DateTime value as a numeric value \
246                      (0-23). This function is useful for time-based analysis, extracting \
247                      hour components for scheduling, or working with time-of-day calculations.",
248        arguments: &[
249            &ArgumentInfo {
250                label: "date",
251                description: "DateTime value to extract hour from",
252                type_hint: "DateTime",
253                optional: false,
254            },
255        ],
256        returns: "Hour as a number (0-23) (f64)",
257        errors: "None - always succeeds",
258        categories: &["date"],
259        examples: &[
260            r#"hour(as_date("2024-01-15 14:30:45", "YYYY-MM-DD HH:mm:ss")) => 14"#,
261            r#"hour(today()) => 14"#,
262            r#"hour(as_date("2024-01-15 00:00:00", "YYYY-MM-DD HH:mm:ss")) => 0"#,
263        ],
264    },
265    
266    // minute(date) -> f64
267    FunctionCard {
268        identifier: "minute",
269        signature: "minute(date)",
270        brief: "Extract the minute component from a date/time value.",
271        description: "Returns the minute portion of a DateTime value as a numeric value \
272                      (0-59). This function is useful for time-based analysis, extracting \
273                      minute components for detailed time calculations, or working with \
274                      minute-level precision.",
275        arguments: &[
276            &ArgumentInfo {
277                label: "date",
278                description: "DateTime value to extract minute from",
279                type_hint: "DateTime",
280                optional: false,
281            },
282        ],
283        returns: "Minute as a number (0-59) (f64)",
284        errors: "None - always succeeds",
285        categories: &["date"],
286        examples: &[
287            r#"minute(as_date("2024-01-15 14:30:45", "YYYY-MM-DD HH:mm:ss")) => 30"#,
288            r#"minute(today()) => 30"#,
289            r#"minute(as_date("2024-01-15 14:00:00", "YYYY-MM-DD HH:mm:ss")) => 0"#,
290        ],
291    },
292    
293    // second(date) -> f64
294    FunctionCard {
295        identifier: "second",
296        signature: "second(date)",
297        brief: "Extract the second component from a date/time value.",
298        description: "Returns the second portion of a DateTime value as a numeric value \
299                      (0-59). This function is useful for time-based analysis, extracting \
300                      second components for precise time calculations, or working with \
301                      second-level precision in time-sensitive applications.",
302        arguments: &[
303            &ArgumentInfo {
304                label: "date",
305                description: "DateTime value to extract second from",
306                type_hint: "DateTime",
307                optional: false,
308            },
309        ],
310        returns: "Second as a number (0-59) (f64)",
311        errors: "None - always succeeds",
312        categories: &["date"],
313        examples: &[
314            r#"second(as_date("2024-01-15 14:30:45", "YYYY-MM-DD HH:mm:ss")) => 45"#,
315            r#"second(today()) => 45"#,
316            r#"second(as_date("2024-01-15 14:30:00", "YYYY-MM-DD HH:mm:ss")) => 0"#,
317        ],
318    },
319    
320    // days_between(date1, date2) -> f64
321    FunctionCard {
322        identifier: "days_between",
323        signature: "days_between(start_date, end_date)",
324        brief: "Calculate the number of days between two dates.",
325        description: "Returns the difference in days between two DateTime values. The result \
326                      is positive if the end_date is after start_date, negative if before, \
327                      and zero if they are the same. This function is essential for \
328                      calculating durations, age calculations, deadline tracking, or any \
329                      operation requiring date difference calculations.",
330        arguments: &[
331            &ArgumentInfo {
332                label: "start_date",
333                description: "Beginning date of the period",
334                type_hint: "DateTime",
335                optional: false,
336            },
337            &ArgumentInfo {
338                label: "end_date",
339                description: "Ending date of the period",
340                type_hint: "DateTime",
341                optional: false,
342            },
343        ],
344        returns: "Number of days between dates (f64)",
345        errors: "None - always succeeds",
346        categories: &["date"],
347        examples: &[
348            r#"days_between(as_date("2024-01-01", "YYYY-MM-DD"), as_date("2024-01-31", "YYYY-MM-DD")) => 30"#,
349            r#"days_between(today(), add_days(today(), 7)) => 7"#,
350            r#"days_between(as_date("2024-01-15", "YYYY-MM-DD"), as_date("2024-01-10", "YYYY-MM-DD")) => -5"#,
351        ],
352    },
353    
354    // add_days(date, days) -> DateTime
355    FunctionCard {
356        identifier: "add_days",
357        signature: "add_days(date, days)",
358        brief: "Add a specified number of days to a date.",
359        description: "Returns a new DateTime value that is the specified number of days \
360                      added to the input date. The days parameter can be positive (adding \
361                      days forward) or negative (subtracting days backward). This function \
362                      is useful for calculating future dates, deadline calculations, or \
363                      date arithmetic operations.",
364        arguments: &[
365            &ArgumentInfo {
366                label: "date",
367                description: "Starting date to add days to",
368                type_hint: "DateTime",
369                optional: false,
370            },
371            &ArgumentInfo {
372                label: "days",
373                description: "Number of days to add (can be negative)",
374                type_hint: "f64",
375                optional: false,
376            },
377        ],
378        returns: "New date with days added (DateTime)",
379        errors: "Fails if the resulting date is outside valid range",
380        categories: &["date"],
381        examples: &[
382            r#"add_days(as_date("2024-01-15", "YYYY-MM-DD"), 7) => 2024-01-22T00:00:00Z"#,
383            r#"add_days(today(), 30) => 2024-02-14T14:30:45Z"#,
384            r#"add_days(as_date("2024-01-15", "YYYY-MM-DD"), -5) => 2024-01-10T00:00:00Z"#,
385        ],
386    },
387    
388    // workdays(date1, date2) -> f64
389    FunctionCard {
390        identifier: "workdays",
391        signature: "workdays(start_date, end_date)",
392        brief: "Calculate approximate number of workdays between two dates.",
393        description: "Returns an approximation of the number of business days (Monday through \
394                      Friday) between two DateTime values. This is calculated as approximately \
395                      5/7 of the total days between the dates. For precise business day \
396                      calculations that exclude weekends and holidays, additional logic would \
397                      be needed to account for specific weekend days and holidays.",
398        arguments: &[
399            &ArgumentInfo {
400                label: "start_date",
401                description: "Beginning date of the period",
402                type_hint: "DateTime",
403                optional: false,
404            },
405            &ArgumentInfo {
406                label: "end_date",
407                description: "Ending date of the period",
408                type_hint: "DateTime",
409                optional: false,
410            },
411        ],
412        returns: "Approximate number of workdays (f64)",
413        errors: "None - always succeeds",
414        categories: &["date"],
415        examples: &[
416            r#"workdays(as_date("2024-01-01", "YYYY-MM-DD"), as_date("2024-01-31", "YYYY-MM-DD")) => 21"#,
417            r#"workdays(today(), add_days(today(), 14)) => 10"#,
418            r#"workdays(as_date("2024-01-15", "YYYY-MM-DD"), as_date("2024-01-22", "YYYY-MM-DD")) => 5"#,
419        ],
420    },
421];
aimx/info_library/date_cards.rs

aimx/info_library/
date_cards.rs
