time/
util.rs

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

time/
util.rs
