spinoso_time/lib.rs
1#![warn(clippy::all, clippy::pedantic, clippy::undocumented_unsafe_blocks)]
2#![allow(
3 clippy::let_underscore_untyped,
4 reason = "https://github.com/rust-lang/rust-clippy/pull/10442#issuecomment-1516570154"
5)]
6#![allow(
7 clippy::question_mark,
8 reason = "https://github.com/rust-lang/rust-clippy/issues/8281"
9)]
10#![allow(clippy::manual_let_else, reason = "manual_let_else was very buggy on release")]
11#![allow(clippy::missing_errors_doc, reason = "A lot of existing code fails this lint")]
12#![allow(
13 clippy::unnecessary_lazy_evaluations,
14 reason = "https://github.com/rust-lang/rust-clippy/issues/8109"
15)]
16#![cfg_attr(
17 test,
18 allow(clippy::non_ascii_literal, reason = "tests sometimes require UTF-8 string content")
19)]
20#![allow(unknown_lints)]
21#![warn(
22 missing_copy_implementations,
23 missing_debug_implementations,
24 missing_docs,
25 rust_2024_compatibility,
26 trivial_casts,
27 trivial_numeric_casts,
28 unused_qualifications,
29 variant_size_differences
30)]
31#![forbid(unsafe_code)]
32// Enable feature callouts in generated documentation:
33// https://doc.rust-lang.org/beta/unstable-book/language-features/doc-cfg.html
34//
35// This approach is borrowed from tokio.
36#![cfg_attr(docsrs, feature(doc_cfg))]
37#![cfg_attr(docsrs, feature(doc_alias))]
38
39//! Time is an abstraction of dates and times.
40//!
41//! This module implements the [`Time`] class from Ruby Core.
42//!
43//! In Artichoke, Time is represented as a 64-bit signed integer of seconds
44//! since January 1, 1970 UTC (the Unix Epoch) and an unsigned 32-bit integer of
45//! subsecond nanoseconds. This allows representing roughly 584 billion years.
46//!
47//! You can use this class in your application by accessing it directly. As a
48//! Core class, it is globally available:
49//!
50//! ```ruby
51//! Time.now
52//! ```
53//!
54//! This implementation of `Time` is dependent on the selected feature. The
55//! **tzrs** feature uses the [`tzdb`] crate for getting the local timezone
56//! information, and combines with the [`tz-rs`] crate to generate the time.
57//!
58//! # Crate features
59//!
60//! This crate can support several backends, which are designed to be
61//! independent of each other. The availability of different backends is
62//! controlled by Cargo features, all of which are enabled by default:
63//!
64//! - **tzrs**: Enable a `Time` backend which is implemented by the [`tz-rs`] and
65//! [`tzdb`] crates.
66//!
67//! ## Additional features
68//!
69//! - **tzrs-local**: Enable the detection of the system timezone with the
70//! **tzrs** backend. This feature is enabled by default. Enabling this
71//! feature also activates the **tzrs** feature.
72//!
73//! If the **tzrs-local** feature is disabled, the local timezone is defaulted
74//! to GMT (not UTC).
75//!
76//! This crate requires [`std`], the Rust Standard Library.
77//!
78//! [`Time`]: https://ruby-doc.org/core-3.1.2/Time.html
79//! [`tz-rs`]: https://crates.io/crates/tz-rs
80//! [`tzdb`]: https://crates.io/crates/tzdb
81
82// Ensure code blocks in `README.md` compile
83#[cfg(all(doctest, feature = "tzrs"))]
84#[doc = include_str!("../README.md")]
85mod readme {}
86
87use core::time::Duration;
88
89#[cfg(feature = "tzrs")]
90pub use strftime;
91
92mod time;
93
94#[cfg(feature = "tzrs")]
95pub use time::tzrs;
96
97/// Number of nanoseconds in one second.
98#[expect(clippy::cast_possible_truncation, reason = "1e9 < u32::MAX")]
99pub const NANOS_IN_SECOND: u32 = Duration::from_secs(1).as_nanos() as u32;
100
101/// Number of microseconds in one nanosecond.
102#[expect(clippy::cast_possible_truncation, reason = "1000 < u32::MAX")]
103pub const MICROS_IN_NANO: u32 = Duration::from_micros(1).as_nanos() as u32;