span: allow ambiguous_negative_literals

This was bad timing. The lang team just stabilized (in nightly) a new
deny-by-default lint, named `ambiguous_negative_literals`, which
triggers an error for things like `-1.hour()`. While such things can be
confusingly ambiguous in some cases, in Jiff, `-1.hour()`, `(-1).hour()`
and `-(1.hour())` are all, very intentionally, precisely equivalent.

For now we just `allow` the lint. If the lint stays, we'll likely want
to recommend allowing it in the Jiff docs.

See: rust-lang/rust#121364

src/civil/date.rs

@@ -1367,6 +1367,8 @@ impl Date {
     /// # Example: negative spans are supported
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::Date, ToSpan};
     ///
     /// let d = Date::constant(2024, 3, 31);
@@ -1380,6 +1382,8 @@ impl Date {
     /// # Example: error on overflow
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::Date, ToSpan};
     ///
     /// let d = Date::constant(2024, 3, 31);
@@ -1471,6 +1475,8 @@ impl Date {
     /// # Example: negative spans are supported
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::Date, ToSpan};
     ///
     /// let d = Date::constant(2024, 3, 31);
@@ -1484,6 +1490,8 @@ impl Date {
     /// # Example: error on overflow
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::Date, ToSpan};
     ///
     /// let d = Date::constant(2024, 3, 31);
@@ -1535,6 +1543,8 @@ impl Date {
     /// # Example: negative spans are supported
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::Date, ToSpan};
     ///
     /// let d = Date::constant(2024, 3, 31);
@@ -1547,6 +1557,8 @@ impl Date {
     /// # Example: saturation on overflow
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::Date, ToSpan};
     ///
     /// let d = Date::constant(2024, 3, 31);
@@ -1604,6 +1616,8 @@ impl Date {
     /// # Example: negative spans are supported
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::Date, ToSpan};
     ///
     /// let d = Date::constant(2024, 3, 31);
@@ -1616,6 +1630,8 @@ impl Date {
     /// # Example: saturation on overflow
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::Date, ToSpan};
     ///
     /// let d = Date::constant(2024, 3, 31);
@@ -1669,6 +1685,8 @@ impl Date {
     /// # Examples
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::Date, ToSpan};
     ///
     /// let earlier = Date::constant(2006, 8, 24);
@@ -1839,6 +1857,8 @@ impl Date {
     /// # Examples
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::Date, ToSpan};
     ///
     /// let earlier = Date::constant(2006, 8, 24);
@@ -2035,6 +2055,8 @@ impl Date {
     /// When did the most recent Friday the 13th occur?
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::{Date, Weekday}, ToSpan};
     ///
     /// let start = Date::constant(2024, 3, 13);
@@ -2689,6 +2711,8 @@ impl DateDifference {
     /// This shows how to always round "up" towards positive infinity.
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::{Date, DateDifference}, RoundMode, ToSpan, Unit};
     ///
     /// let d1 = "2024-01-15".parse::<Date>()?;

src/civil/datetime.rs

@@ -1482,6 +1482,8 @@ impl DateTime {
     /// # Example: negative spans are supported
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::date, ToSpan};
     ///
     /// let dt = date(2024, 3, 31).at(19, 5, 59, 999_999_999);
@@ -1496,6 +1498,8 @@ impl DateTime {
     /// # Example: error on overflow
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::date, ToSpan};
     ///
     /// let dt = date(2024, 3, 31).at(13, 13, 13, 13);
@@ -1581,6 +1585,8 @@ impl DateTime {
     /// # Example: negative spans are supported
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::date, ToSpan};
     ///
     /// let dt = date(2024, 3, 31).at(19, 5, 59, 999_999_999);
@@ -1595,6 +1601,8 @@ impl DateTime {
     /// # Example: error on overflow
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::date, ToSpan};
     ///
     /// let dt = date(2024, 3, 31).at(13, 13, 13, 13);
@@ -1642,6 +1650,8 @@ impl DateTime {
     /// # Example: negative spans are supported
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::date, ToSpan};
     ///
     /// let dt = date(2024, 3, 31).at(19, 5, 59, 999_999_999);
@@ -1654,6 +1664,8 @@ impl DateTime {
     /// # Example: saturation on overflow
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::{DateTime, date}, ToSpan};
     ///
     /// let dt = date(2024, 3, 31).at(13, 13, 13, 13);
@@ -1708,6 +1720,8 @@ impl DateTime {
     /// # Example: negative spans are supported
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::date, ToSpan};
     ///
     /// let dt = date(2024, 3, 31).at(19, 5, 59, 999_999_999);
@@ -1720,6 +1734,8 @@ impl DateTime {
     /// # Example: saturation on overflow
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::{DateTime, date}, ToSpan};
     ///
     /// let dt = date(2024, 3, 31).at(13, 13, 13, 13);
@@ -1780,6 +1796,8 @@ impl DateTime {
     /// # Example
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::date, ToSpan};
     ///
     /// let earlier = date(2006, 8, 24).at(22, 30, 0, 0);
@@ -1950,6 +1968,8 @@ impl DateTime {
     /// # Example
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::date, ToSpan};
     ///
     /// let earlier = date(2006, 8, 24).at(22, 30, 0, 0);

src/civil/time.rs

@@ -1180,6 +1180,8 @@ impl Time {
     /// # Examples
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::Time, ToSpan};
     ///
     /// let t1 = Time::constant(22, 35, 1, 0);
@@ -1267,6 +1269,8 @@ impl Time {
     /// # Examples
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::Time, ToSpan};
     ///
     /// let t1 = Time::constant(22, 35, 1, 0);
@@ -1468,6 +1472,8 @@ impl Time {
     /// Or go backwards every 6.5 hours:
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::{civil::Time, ToSpan};
     ///
     /// let start = Time::constant(23, 0, 0, 0);

src/lib.rs

@@ -575,6 +575,8 @@ specifiers and other APIs.
 #![warn(missing_debug_implementations)]
 // Document ALL THE THINGS!
 #![deny(missing_docs)]
+// See: https://github.com/rust-lang/rust/pull/121364
+#![allow(unknown_lints, ambiguous_negative_literals)]
 
 // It should be possible to support other pointer widths, but this library
 // hasn't been tested nor thought about much in contexts with pointers less

src/span.rs

@@ -87,9 +87,16 @@ use crate::{
 ///
 /// # Negative spans
 ///
+/// **WARNING:** As of nightly Rust 2024-07-26, negating spans like
+/// `-2.hours()` triggers a deny-by-default lint due to an ambiguous negative
+/// literal. However, in Jiff's case, this is a false positive. Feel free to
+/// `allow` the lint or write the span as `(-2).hours()` or `-(2.hours())`.
+///
 /// A span may be negative. All of these are equivalent:
 ///
 /// ```
+/// # // See: https://github.com/rust-lang/rust/pull/121364
+/// # #![allow(unknown_lints, ambiguous_negative_literals)]
 /// use jiff::{Span, ToSpan};
 ///
 /// let span = -Span::new().days(5);
@@ -118,6 +125,8 @@ use crate::{
 /// then all of its units are negative:
 ///
 /// ```
+/// # // See: https://github.com/rust-lang/rust/pull/121364
+/// # #![allow(unknown_lints, ambiguous_negative_literals)]
 /// use jiff::ToSpan;
 ///
 /// let span = -5.days().hours(10).minutes(1);
@@ -130,6 +139,8 @@ use crate::{
 /// as negative:
 ///
 /// ```
+/// # // See: https://github.com/rust-lang/rust/pull/121364
+/// # #![allow(unknown_lints, ambiguous_negative_literals)]
 /// use jiff::ToSpan;
 ///
 /// // It's the same thing.
@@ -541,6 +552,8 @@ use crate::{
 /// span positive before converting it to a `Duration`:
 ///
 /// ```
+/// # // See: https://github.com/rust-lang/rust/pull/121364
+/// # #![allow(unknown_lints, ambiguous_negative_literals)]
 /// use std::time::Duration;
 ///
 /// use jiff::{Span, ToSpan};
@@ -990,6 +1003,8 @@ impl Span {
     /// # Example
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::ToSpan;
     ///
     /// let span = -100.seconds();
@@ -1055,6 +1070,8 @@ impl Span {
     /// # Example
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::ToSpan;
     ///
     /// assert!(!2.months().is_negative());
@@ -1072,6 +1089,8 @@ impl Span {
     /// # Example
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::ToSpan;
     ///
     /// assert!(!2.months().is_negative());
@@ -1108,6 +1127,8 @@ impl Span {
     /// # Example
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::ToSpan;
     ///
     /// let span = 4.days().seconds(8);
@@ -1129,6 +1150,8 @@ impl Span {
     /// happens on overflow.
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::ToSpan;
     ///
     /// let span = 4.days().seconds(8);
@@ -1493,6 +1516,8 @@ impl Span {
     /// # Example: negative spans are less than zero
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use jiff::ToSpan;
     ///
     /// let span1 = -1.second();
@@ -1893,6 +1918,8 @@ impl Span {
     /// the span positive before converting it to a `Duration`:
     ///
     /// ```
+    /// # // See: https://github.com/rust-lang/rust/pull/121364
+    /// # #![allow(unknown_lints, ambiguous_negative_literals)]
     /// use std::time::Duration;
     ///
     /// use jiff::{civil::date, Span, ToSpan};
@@ -2790,6 +2817,8 @@ impl core::ops::Mul<Span> for i64 {
 /// span positive before converting it to a `Duration`:
 ///
 /// ```
+/// # // See: https://github.com/rust-lang/rust/pull/121364
+/// # #![allow(unknown_lints, ambiguous_negative_literals)]
 /// use std::time::Duration;
 ///
 /// use jiff::{Span, ToSpan};
@@ -3039,6 +3068,8 @@ impl quickcheck::Arbitrary for Span {
 /// # Example
 ///
 /// ```
+/// # // See: https://github.com/rust-lang/rust/pull/121364
+/// # #![allow(unknown_lints, ambiguous_negative_literals)]
 /// use jiff::ToSpan;
 ///
 /// assert_eq!(5.days().to_string(), "P5d");