time/
util.rs

1//! Utility functions, including updating time zone information.
2
3pub(crate) use time_core::util::{days_in_month_leap, range_validated};
4pub use time_core::util::{days_in_year, is_leap_year, weeks_in_year};
5
6use crate::Month;
7
8/// Whether to adjust the date, and in which direction. Useful when implementing arithmetic.
9pub(crate) enum DateAdjustment {
10    /// The previous day should be used.
11    Previous,
12    /// The next day should be used.
13    Next,
14    /// The date should be used as-is.
15    None,
16}
17
18/// Get the number of days in the month of a given year.
19///
20/// ```rust
21/// # use time::{Month, util};
22/// assert_eq!(util::days_in_month(Month::February, 2020), 29);
23/// ```
24#[inline]
25pub const fn days_in_month(month: Month, year: i32) -> u8 {
26    time_core::util::days_in_month(month as u8, year)
27}
28
29/// Get the number of days in the month of a given year.
30///
31/// ```rust
32/// # #![expect(deprecated)]
33/// # use time::{Month, util};
34/// assert_eq!(util::days_in_year_month(2020, Month::February), 29);
35/// ```
36#[deprecated(
37    since = "0.3.37",
38    note = "use `days_in_month` or `Month::length` instead"
39)]
40#[inline]
41pub const fn days_in_year_month(year: i32, month: Month) -> u8 {
42    days_in_month(month, year)
43}
44
45/// Update time zone information from the system.
46///
47/// For a version of this function that is guaranteed to be sound, see [`refresh_tz`].
48///
49/// # Safety
50///
51/// This is a system call with specific requirements. The following is from POSIX's description of
52/// `tzset`:
53///
54/// > If a thread accesses `tzname`, `daylight`, or `timezone` directly while another thread is in a
55/// > call to `tzset()`, or to any function that is required or allowed to set timezone information
56/// > as if by calling `tzset()`, the behavior is undefined.
57///
58/// Effectively, this translates to the requirement that at least one of the following must be true:
59///
60/// - The operating system provides a thread-safe environment.
61/// - The process is single-threaded.
62/// - The process is multi-threaded **and** no other thread is mutating the environment in any way
63///   at the same time a call to a method that obtains the local UTC offset. This includes adding,
64///   removing, or modifying an environment variable.
65///
66/// ## Soundness is global
67///
68/// You must not only verify this safety conditions for your code, but for **all** code that will be
69/// included in the final binary. Notably, it applies to both direct and transitive dependencies and
70/// to both Rust and non-Rust code. **For this reason it is not possible for a library to soundly
71/// call this method.**
72///
73/// ## Forward compatibility
74///
75/// This currently only does anything on Unix-like systems. On other systems, it is a no-op. This
76/// may change in the future if necessary, expanding the safety requirements. It is expected that,
77/// at a minimum, calling this method when the process is single-threaded will remain sound.
78#[cfg(feature = "local-offset")]
79#[inline]
80pub unsafe fn refresh_tz_unchecked() {
81    // Safety: The caller must uphold the safety requirements.
82    unsafe { crate::sys::refresh_tz_unchecked() };
83}
84
85/// Attempt to update time zone information from the system.
86///
87/// Returns `None` if the call is not known to be sound.
88#[cfg(feature = "local-offset")]
89#[inline]
90pub fn refresh_tz() -> Option<()> {
91    crate::sys::refresh_tz()
92}
93
94#[doc(hidden)]
95#[cfg(feature = "local-offset")]
96#[expect(
97    clippy::missing_const_for_fn,
98    reason = "no longer used; original implementation was not const"
99)]
100#[deprecated(since = "0.3.37", note = "no longer needed; TZ is refreshed manually")]
101pub mod local_offset {
102    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
103    pub enum Soundness {
104        Sound,
105        Unsound,
106    }
107
108    #[inline]
109    pub unsafe fn set_soundness(_: Soundness) {}
110
111    #[inline]
112    pub fn get_soundness() -> Soundness {
113        Soundness::Sound
114    }
115}
time/util.rs

time/
util.rs
