rsimple_date 0.1.0

PHP-style date() formatting for Rust — use Y-m-d H:i:s instead of strftime
Documentation
//! PHP-like `date()`, `gmdate()`, and `time()`.
//!
//! These functions mirror the familiar PHP APIs and accept PHP format strings.
//! Extremely out-of-range Unix timestamps are clamped to the Unix epoch so
//! formatting never panics.

use crate::format::format_php;
use chrono::{DateTime, Local, TimeZone, Utc};

/// Return the current Unix timestamp in seconds (PHP `time()`).
///
/// # Examples
///
/// ```
/// use rsimple_date::time;
///
/// assert!(time() > 0);
/// ```
pub fn time() -> i64 {
    Utc::now().timestamp()
}

/// Format the current **local** time with a PHP format string (PHP `date($format)`).
///
/// # Examples
///
/// ```
/// use rsimple_date::date;
///
/// let s = date("Y-m-d H:i:s");
/// assert_eq!(s.len(), 19);
/// ```
pub fn date(format: &str) -> String {
    format_php(&Local::now(), format)
}

/// Format a Unix timestamp in the **local** timezone (PHP `date($format, $timestamp)`).
///
/// # Examples
///
/// ```
/// use rsimple_date::date_with;
///
/// assert_eq!(date_with("Y-m-d", 0).len(), 10);
/// assert_eq!(date_with("U", 1_000), "1000");
/// ```
pub fn date_with(format: &str, timestamp: i64) -> String {
    let dt = local_from_timestamp(timestamp);
    format_php(&dt, format)
}

/// Format the current **UTC** time (PHP `gmdate($format)`).
///
/// # Examples
///
/// ```
/// use rsimple_date::gmdate;
///
/// assert!(!gmdate("Y").is_empty());
/// ```
pub fn gmdate(format: &str) -> String {
    format_php(&Utc::now(), format)
}

/// Format a Unix timestamp in **UTC** (PHP `gmdate($format, $timestamp)`).
///
/// Prefer this over [`date_with`] when you need deterministic, timezone-independent
/// output (for example in tests or logs).
///
/// # Examples
///
/// ```
/// use rsimple_date::gmdate_with;
///
/// assert_eq!(gmdate_with("Y-m-d H:i:s", 978307200), "2001-01-01 00:00:00");
/// assert_eq!(gmdate_with("c", 946684800), "2000-01-01T00:00:00+00:00");
/// ```
pub fn gmdate_with(format: &str, timestamp: i64) -> String {
    let dt = utc_from_timestamp(timestamp);
    format_php(&dt, format)
}

fn utc_from_timestamp(timestamp: i64) -> DateTime<Utc> {
    DateTime::from_timestamp(timestamp, 0).unwrap_or_else(|| {
        // Extremely out-of-range timestamps: clamp to epoch.
        DateTime::from_timestamp(0, 0).unwrap()
    })
}

fn local_from_timestamp(timestamp: i64) -> DateTime<Local> {
    match Local.timestamp_opt(timestamp, 0) {
        chrono::LocalResult::Single(dt) | chrono::LocalResult::Ambiguous(dt, _) => dt,
        chrono::LocalResult::None => Local
            .timestamp_opt(0, 0)
            .single()
            .unwrap_or_else(Local::now),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn gmdate_fixed() {
        // 2001-03-10 17:16:18 UTC
        let ts = Utc
            .with_ymd_and_hms(2001, 3, 10, 17, 16, 18)
            .unwrap()
            .timestamp();
        assert_eq!(gmdate_with("Y-m-d H:i:s", ts), "2001-03-10 17:16:18");
        assert_eq!(gmdate_with("l jS", ts), "Saturday 10th");
        assert_eq!(gmdate_with("U", ts), ts.to_string());
    }

    #[test]
    fn time_is_reasonable() {
        let t = time();
        assert!(t > 1_000_000_000);
    }

    #[test]
    fn date_returns_non_empty() {
        assert!(!date("Y").is_empty());
        assert!(!gmdate("Y-m-d").is_empty());
    }
}