//! Utility functions, including updating time zone information.

use core::num::NonZero;

pub(crate) use time_core::util::{days_in_month_leap, range_validated};

pub use time_core::util::{days_in_year, is_leap_year, weeks_in_year};

use crate::Month;

/// Which direction arithmetic overflow occurred in.

#[derive(Debug, Clone, Copy)]

pub(crate) enum Overflow {

    /// The overflow was positive (i.e. towards positive infinity).

    Positive,

    /// The overflow was negative (i.e. towards negative infinity).

    Negative,

}

/// Whether to adjust the date, and in which direction. Useful when implementing arithmetic.

pub(crate) enum DateAdjustment {

    /// The previous day should be used.

    Previous,

    /// The next day should be used.

    Next,

    /// The date should be used as-is.

    None,

}

/// Get the number of days in the month of a given year.

///

/// ```rust

/// # use time::{Month, util};

/// assert_eq!(util::days_in_month(Month::February, 2020), 29);

/// ```

#[inline]

pub const fn days_in_month(month: Month, year: i32) -> u8 {

    time_core::util::days_in_month(month as u8, year)

}

/// Get the number of days in the month of a given year.

///

/// ```rust

/// # #![expect(deprecated)]

/// # use time::{Month, util};

/// assert_eq!(util::days_in_year_month(2020, Month::February), 29);

/// ```

#[deprecated(

    since = "0.3.37",

    note = "use `days_in_month` or `Month::length` instead"

)]

#[inline]

pub const fn days_in_year_month(year: i32, month: Month) -> u8 {

    days_in_month(month, year)

}

/// Given whether a year is a leap year and the ordinal day, return the month and day of the month.

#[inline]

pub(crate) const fn leap_ordinal_to_month_day(leap: bool, ordinal: u16) -> (Month, u8) {

    let ordinal = ordinal as u32;

    let jan_feb_len = 59 + leap as u32;

    let (month_adj, ordinal_adj) = if ordinal <= jan_feb_len {

        (0, 0)

    } else {

        (2, jan_feb_len)

    };

    let ordinal = ordinal - ordinal_adj;

    let month = (ordinal * 268 + 8031) >> 13;

    let days_in_preceding_months = (month * 3917 - 3866) >> 7;

    let day = ordinal - days_in_preceding_months;

    let month = month + month_adj;

    (

        // Safety: `month` is guaranteed to be between 1 and 12 inclusive.

        unsafe {

            match Month::from_number(NonZero::new_unchecked(month as u8)) {

                Ok(month) => month,

                Err(_) => core::hint::unreachable_unchecked(),

            }

        },

        day as u8,

    )

}

/// Update time zone information from the system.

///

/// For a version of this function that is guaranteed to be sound, see [`refresh_tz`].

///

/// # Safety

///

/// This is a system call with specific requirements. The following is from POSIX's description of

/// `tzset`:

///

/// > If a thread accesses `tzname`, `daylight`, or `timezone` directly while another thread is in a

/// > call to `tzset()`, or to any function that is required or allowed to set timezone information

/// > as if by calling `tzset()`, the behavior is undefined.

///

/// Effectively, this translates to the requirement that at least one of the following must be true:

///

/// - The operating system provides a thread-safe environment.

/// - The process is single-threaded.

/// - The process is multi-threaded **and** no other thread is mutating the environment in any way

///   at the same time a call to a method that obtains the local UTC offset. This includes adding,

///   removing, or modifying an environment variable.

///

/// ## Soundness is global

///

/// You must not only verify this safety conditions for your code, but for **all** code that will be

/// included in the final binary. Notably, it applies to both direct and transitive dependencies and

/// to both Rust and non-Rust code. **For this reason it is not possible for a library to soundly

/// call this method.**

///

/// ## Forward compatibility

///

/// This currently only does anything on Unix-like systems. On other systems, it is a no-op. This

/// may change in the future if necessary, expanding the safety requirements. It is expected that,

/// at a minimum, calling this method when the process is single-threaded will remain sound.

#[cfg(feature = "local-offset")]

#[inline]

pub unsafe fn refresh_tz_unchecked() {

    // Safety: The caller must uphold the safety requirements.

    unsafe { crate::sys::refresh_tz_unchecked() };

}

/// Attempt to update time zone information from the system.

///

/// Returns `None` if the call is not known to be sound.

#[cfg(feature = "local-offset")]

#[inline]

pub fn refresh_tz() -> Option<()> {

    crate::sys::refresh_tz()

}

#[doc(hidden)]

#[cfg(feature = "local-offset")]

#[expect(

    clippy::missing_const_for_fn,

    reason = "no longer used; original implementation was not const"

)]

#[deprecated(since = "0.3.37", note = "no longer needed; TZ is refreshed manually")]

pub mod local_offset {

    #[derive(Debug, Clone, Copy, PartialEq, Eq)]

    pub enum Soundness {

        Sound,

        Unsound,

    }

    #[inline]

    pub unsafe fn set_soundness(_: Soundness) {}

    #[inline]

    pub fn get_soundness() -> Soundness {

        Soundness::Sound

    }

}