universal-date-parser 1.0.0

# Universal Date Parser - Comprehensive Date Parsing Library

## Introduction

The Universal Date Parser is a high-performance Rust library designed to intelligently parse dates from virtually any format into standardized output. Built with performance, reliability, and ease of use in mind, it provides automatic format detection, timezone awareness, and multi-language bindings.

## Architecture Overview

### Core Components

The library is structured around several key components:

1. **ParsedDate Structure**: The fundamental data structure that represents a successfully parsed date
2. **UniversalDateParser**: The main parsing engine with configurable options
3. **Format Detection Engine**: Intelligent pattern matching for automatic format recognition
4. **Multi-Language Bindings**: C FFI and WebAssembly exports for cross-platform compatibility

### Design Principles

#### Performance First
- Zero-copy parsing where possible
- Lazy regex compilation using `lazy_static`
- Efficient pattern matching with early returns
- Benchmarked performance: 300-600ns per parse operation

#### Intelligent Detection
The parser uses a sophisticated format detection system:

```rust
pub fn detect_format(&self, input: &str) -> Option<&'static str> {
    // ISO 8601 formats (highest priority)
    if ISO_DATETIME_REGEX.is_match(input) {
        return Some("ISO 8601 DateTime");
    }
    
    // Unix timestamps
    if UNIX_TIMESTAMP_REGEX.is_match(input) {
        return if input.len() > 10 {
            Some("Unix Timestamp (ms)")
        } else {
            Some("Unix Timestamp")
        };
    }
    
    // Regional formats with ambiguity resolution
    // ... sophisticated pattern matching
}
```

#### Timezone Awareness
The library provides flexible timezone handling:

- **AssumeUtc**: Treat all dates as UTC (fastest)
- **AssumeLocal**: Use system timezone
- **PreserveOffset**: Maintain original timezone information
- **ConvertToUtc**: Convert all dates to UTC

## Format Support

### ISO 8601 Standard
Full support for ISO 8601 date-time formats:
- `2023-12-25T10:30:00Z`
- `2023-12-25T10:30:00+05:30`
- `2023-12-25`
- `20231225T103000Z`

### Regional Formats
Intelligent handling of ambiguous date formats:
- US Format: `12/25/2023` (MM/DD/YYYY)
- European Format: `25/12/2023` (DD/MM/YYYY)
- Context-aware disambiguation

### Unix Timestamps
Support for both second and millisecond precision:
- `1703520645` (seconds since epoch)
- `1703520645000` (milliseconds since epoch)

### Natural Language (Future)
Extensible architecture for natural language parsing:
- "yesterday", "next week", "2 days ago"
- Relative date expressions
- Holiday and event names

## Performance Characteristics

### Benchmark Results

Based on comprehensive benchmarks using Criterion:

| Format Type | Average Time | Throughput |
|-------------|--------------|------------|
| ISO 8601 DateTime | 388ns | 2.6M ops/sec |
| ISO 8601 Date | 344ns | 2.9M ops/sec |
| US Format | 392ns | 2.6M ops/sec |
| European Format | 618ns | 1.6M ops/sec |
| Unix Timestamp | 483ns | 2.1M ops/sec |
| Unix Timestamp (ms) | 598ns | 1.7M ops/sec |

### Memory Usage
- Minimal heap allocations
- Efficient regex caching
- Stack-allocated intermediate values
- Zero-copy string processing where possible

## Error Handling

The library provides comprehensive error handling with detailed error messages:

```rust
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum ParseError {
    InvalidFormat(String),
    AmbiguousFormat(String),
    TimezoneError(String),
    ChronoParseError(String),
}
```

Each error variant provides specific context about what went wrong, making debugging and error recovery straightforward.

## Multi-Language Integration

### C FFI Interface
```c
// Simple C interface
char* parse_date_c(const char* input);
void free_string_c(char* ptr);
```

### WebAssembly Support
```javascript
// JavaScript/TypeScript integration
import { parse_date_wasm } from './pkg/universal_date_parser.js';

const result = parse_date_wasm("2023-12-25T10:30:00Z");
console.log(JSON.parse(result));
```

### Rust Native
```rust
use universal_date_parser::{UniversalDateParser, ParserConfig};

let parser = UniversalDateParser::new();
let result = parser.parse("2023-12-25")?;
println!("Parsed: {}", result.datetime);
```

## Configuration Options

The parser supports extensive configuration:

```rust
let config = ParserConfig::new()
    .timezone_strategy(TimezoneStrategy::ConvertToUtc)
    .strict_mode(false)
    .enable_fuzzy_matching(true);

let parser = UniversalDateParser::with_config(config);
```

### Strict Mode
- When enabled: Only exact format matches accepted
- When disabled: Fuzzy matching and format guessing enabled

### Timezone Strategies
- **AssumeUtc**: Fastest, treats all as UTC
- **AssumeLocal**: Uses system timezone
- **PreserveOffset**: Maintains original timezone info
- **ConvertToUtc**: Normalizes all to UTC

## Testing Strategy

The library includes comprehensive test coverage:

### Unit Tests
- Format detection accuracy
- Parsing correctness
- Error condition handling
- Edge case validation

### Integration Tests
- Multi-language binding verification
- Configuration option combinations
- Real-world data parsing

### Performance Tests
- Benchmark suite with Criterion
- Memory usage profiling
- Throughput measurements
- Regression detection

## Future Enhancements

### Planned Features
1. **Natural Language Processing**: "next Monday", "in 2 weeks"
2. **Holiday Detection**: "Christmas 2023", "Easter 2024"
3. **Relative Date Parsing**: "2 days ago", "next quarter"
4. **Localization Support**: Multiple language natural formats
5. **Custom Format Registration**: User-defined parsing patterns

### Performance Optimizations
1. **SIMD Instructions**: Vector processing for bulk operations
2. **Compile-time Optimization**: More aggressive const evaluation
3. **Memory Pool**: Reusable allocation strategies
4. **Parallel Processing**: Multi-threaded bulk parsing

## Conclusion

The Universal Date Parser represents a comprehensive solution for date parsing needs across multiple programming languages and environments. Its combination of high performance, intelligent format detection, and robust error handling makes it suitable for production applications requiring reliable date processing.

The library's architecture supports extensibility while maintaining performance, and its comprehensive test suite ensures reliability across diverse input formats and edge cases.

For detailed usage examples and API documentation, see the main README.md file and inline documentation.