Skip to content

Commit f42855c

Browse files
pitdickerpitdicker
committed
Deprecate old formatting methods
1 parent 0ab9707 commit f42855c

File tree

5 files changed

+57
-211
lines changed

5 files changed

+57
-211
lines changed

‎benches/chrono.rs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -177,13 +177,15 @@ fn bench_format_with(c: &mut Criterion) {
177177
});
178178
}
179179

180+
#[allow(deprecated)]
180181
fn bench_format(c: &mut Criterion) {
181182
let dt = Local::now();
182183
c.bench_function("bench_format", |b| {
183184
b.iter(|| format!("{}", black_box(dt).format("%Y-%m-%dT%H:%M:%S%.f%:z")))
184185
});
185186
}
186187

188+
#[allow(deprecated)]
187189
fn bench_format_with_items(c: &mut Criterion) {
188190
let dt = Local::now();
189191
let items: Vec<_> = StrftimeItems::new("%Y-%m-%dT%H:%M:%S%.f%:z").collect();

‎src/datetime/mod.rs‎

Lines changed: 18 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -869,6 +869,7 @@ where
869869
#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
870870
#[inline]
871871
#[must_use]
872+
#[deprecated(since = "0.4.27", note = "Use DateTime::format_with() instead")]
872873
pub fn format_with_items<'a, I, B>(&self, items: I) -> DelayedFormat<I>
873874
where
874875
I: Iterator<Item = B> + Clone,
@@ -878,64 +879,33 @@ where
878879
DelayedFormat::new_with_offset(Some(local.date()), Some(local.time()), &self.offset, items)
879880
}
880881

881-
/// Formats the combined date and time per the specified format string.
882+
/// Formats the date and time with the specified format string.
882883
///
883-
/// See the [`crate::format::strftime`] module for the supported escape sequences.
884+
/// # Deprecated
884885
///
885-
/// # Example
886-
/// ```rust
887-
/// use chrono::prelude::*;
886+
/// Use [`format_to_string`](#method.format_to_string) or [`format_with`](#method.format_with)
887+
/// instead.
888888
///
889-
/// let date_time: DateTime<Utc> = Utc.with_ymd_and_hms(2017, 04, 02, 12, 50, 32).unwrap();
890-
/// let formatted = format!("{}", date_time.format("%d/%m/%Y %H:%M"));
891-
/// assert_eq!(formatted, "02/04/2017 12:50");
892-
/// ```
889+
/// # Errors/panics
890+
///
891+
/// The `Display` implementation of the returned `DelayedFormat` can return an error if the
892+
/// format string is invalid. This goes against the [contract for `Display`][1], and causes a
893+
/// panic when used in combination with [`to_string`], [`println!`] and [`format!`].
894+
///
895+
/// [1]: https://doc.rust-lang.org/stable/std/fmt/index.html#formatting-traits
896+
/// [`to_string`]: ToString::to_string
893897
#[cfg(any(feature = "alloc", feature = "std"))]
894898
#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
895899
#[inline]
896900
#[must_use]
901+
#[deprecated(
902+
since = "0.4.27",
903+
note = "Use DateTime::format_to_string() or DateTime::format_with() instead"
904+
)]
897905
pub fn format<'a>(&self, fmt: &'a str) -> DelayedFormat<StrftimeItems<'a>> {
906+
#[allow(deprecated)]
898907
self.format_with_items(StrftimeItems::new(fmt))
899908
}
900-
901-
/// Formats the combined date and time with the specified formatting items and locale.
902-
#[cfg(all(feature = "unstable-locales", any(feature = "alloc", feature = "std")))]
903-
#[inline]
904-
#[must_use]
905-
pub fn format_localized_with_items<'a, I, B>(
906-
&self,
907-
items: I,
908-
locale: Locale,
909-
) -> DelayedFormat<I>
910-
where
911-
I: Iterator<Item = B> + Clone,
912-
B: Borrow<Item<'a>>,
913-
{
914-
let local = self.naive_local();
915-
DelayedFormat::new_with_offset_and_locale(
916-
Some(local.date()),
917-
Some(local.time()),
918-
&self.offset,
919-
items,
920-
locale,
921-
)
922-
}
923-
924-
/// Formats the combined date and time per the specified format string and
925-
/// locale.
926-
///
927-
/// See the [`crate::format::strftime`] module on the supported escape
928-
/// sequences.
929-
#[cfg(all(feature = "unstable-locales", any(feature = "alloc", feature = "std")))]
930-
#[inline]
931-
#[must_use]
932-
pub fn format_localized<'a>(
933-
&self,
934-
fmt: &'a str,
935-
locale: Locale,
936-
) -> DelayedFormat<StrftimeItems<'a>> {
937-
self.format_localized_with_items(StrftimeItems::new_with_locale(fmt, locale), locale)
938-
}
939909
}
940910

941911
impl DateTime<Utc> {

‎src/naive/date.rs‎

Lines changed: 12 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1329,36 +1329,11 @@ impl NaiveDate {
13291329
}
13301330

13311331
/// Formats the date with the specified formatting items.
1332-
/// Otherwise it is the same as the ordinary `format` method.
1333-
///
1334-
/// The `Iterator` of items should be `Clone`able,
1335-
/// since the resulting `DelayedFormat` value may be formatted multiple times.
1336-
///
1337-
/// # Example
1338-
///
1339-
/// ```
1340-
/// use chrono::NaiveDate;
1341-
/// use chrono::format::strftime::StrftimeItems;
1342-
///
1343-
/// let fmt = StrftimeItems::new("%Y-%m-%d");
1344-
/// let d = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap();
1345-
/// assert_eq!(d.format_with_items(fmt.clone()).to_string(), "2015-09-05");
1346-
/// assert_eq!(d.format("%Y-%m-%d").to_string(), "2015-09-05");
1347-
/// ```
1348-
///
1349-
/// The resulting `DelayedFormat` can be formatted directly via the `Display` trait.
1350-
///
1351-
/// ```
1352-
/// # use chrono::NaiveDate;
1353-
/// # use chrono::format::strftime::StrftimeItems;
1354-
/// # let fmt = StrftimeItems::new("%Y-%m-%d").clone();
1355-
/// # let d = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap();
1356-
/// assert_eq!(format!("{}", d.format_with_items(fmt)), "2015-09-05");
1357-
/// ```
13581332
#[cfg(any(feature = "alloc", feature = "std"))]
13591333
#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
13601334
#[inline]
13611335
#[must_use]
1336+
#[deprecated(since = "0.4.27", note = "Use NaiveDate::format_with() instead")]
13621337
pub fn format_with_items<'a, I, B>(&self, items: I) -> DelayedFormat<I>
13631338
where
13641339
I: Iterator<Item = B> + Clone,
@@ -1368,42 +1343,27 @@ impl NaiveDate {
13681343
}
13691344

13701345
/// Formats the date with the specified format string.
1371-
/// See the [`format::strftime` module](../format/strftime/index.html)
1372-
/// on the supported escape sequences.
13731346
///
1374-
/// This returns a `DelayedFormat`,
1375-
/// which gets converted to a string only when actual formatting happens.
1376-
/// You may use the `to_string` method to get a `String`,
1377-
/// or just feed it into `print!` and other formatting macros.
1378-
/// (In this way it avoids the redundant memory allocation.)
1347+
/// # Deprecated
13791348
///
1380-
/// A wrong format string does *not* issue an error immediately.
1381-
/// Rather, converting or formatting the `DelayedFormat` fails.
1382-
/// You are recommended to immediately use `DelayedFormat` for this reason.
1383-
///
1384-
/// # Example
1385-
///
1386-
/// ```
1387-
/// use chrono::NaiveDate;
1349+
/// Use [`format_to_string`](#method.format_to_string) or [`format_with`](#method.format_with)
1350+
/// instead.
13881351
///
1389-
/// let d = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap();
1390-
/// assert_eq!(d.format("%Y-%m-%d").to_string(), "2015-09-05");
1391-
/// assert_eq!(d.format("%A, %-d %B, %C%y").to_string(), "Saturday, 5 September, 2015");
1392-
/// ```
1352+
/// # Errors/panics
13931353
///
1394-
/// The resulting `DelayedFormat` can be formatted directly via the `Display` trait.
1354+
/// The `Display` implementation of the returned `DelayedFormat` can return an error if the
1355+
/// format string is invalid. This goes against the [contract for `Display`][1], and causes a
1356+
/// panic when used in combination with [`to_string`], [`println!`] and [`format!`].
13951357
///
1396-
/// ```
1397-
/// # use chrono::NaiveDate;
1398-
/// # let d = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap();
1399-
/// assert_eq!(format!("{}", d.format("%Y-%m-%d")), "2015-09-05");
1400-
/// assert_eq!(format!("{}", d.format("%A, %-d %B, %C%y")), "Saturday, 5 September, 2015");
1401-
/// ```
1358+
/// [1]: https://doc.rust-lang.org/stable/std/fmt/index.html#formatting-traits
1359+
/// [`to_string`]: ToString::to_string
14021360
#[cfg(any(feature = "alloc", feature = "std"))]
14031361
#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
14041362
#[inline]
14051363
#[must_use]
1364+
#[deprecated(since = "0.4.27", note = "Use DateTime::format_to_string() instead")]
14061365
pub fn format<'a>(&self, fmt: &'a str) -> DelayedFormat<StrftimeItems<'a>> {
1366+
#[allow(deprecated)]
14071367
self.format_with_items(StrftimeItems::new(fmt))
14081368
}
14091369

‎src/naive/datetime/mod.rs‎

Lines changed: 13 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -912,36 +912,11 @@ impl NaiveDateTime {
912912
}
913913

914914
/// Formats the combined date and time with the specified formatting items.
915-
/// Otherwise it is the same as the ordinary [`format`](#method.format) method.
916-
///
917-
/// The `Iterator` of items should be `Clone`able,
918-
/// since the resulting `DelayedFormat` value may be formatted multiple times.
919-
///
920-
/// # Example
921-
///
922-
/// ```
923-
/// use chrono::NaiveDate;
924-
/// use chrono::format::strftime::StrftimeItems;
925-
///
926-
/// let fmt = StrftimeItems::new("%Y-%m-%d %H:%M:%S");
927-
/// let dt = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap().and_hms_opt(23, 56, 4).unwrap();
928-
/// assert_eq!(dt.format_with_items(fmt.clone()).to_string(), "2015-09-05 23:56:04");
929-
/// assert_eq!(dt.format("%Y-%m-%d %H:%M:%S").to_string(), "2015-09-05 23:56:04");
930-
/// ```
931-
///
932-
/// The resulting `DelayedFormat` can be formatted directly via the `Display` trait.
933-
///
934-
/// ```
935-
/// # use chrono::NaiveDate;
936-
/// # use chrono::format::strftime::StrftimeItems;
937-
/// # let fmt = StrftimeItems::new("%Y-%m-%d %H:%M:%S").clone();
938-
/// # let dt = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap().and_hms_opt(23, 56, 4).unwrap();
939-
/// assert_eq!(format!("{}", dt.format_with_items(fmt)), "2015-09-05 23:56:04");
940-
/// ```
941915
#[cfg(any(feature = "alloc", feature = "std"))]
942916
#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
943917
#[inline]
944918
#[must_use]
919+
#[deprecated(since = "0.4.27", note = "Use NaiveDateTime::format_with() instead")]
945920
pub fn format_with_items<'a, I, B>(&self, items: I) -> DelayedFormat<I>
946921
where
947922
I: Iterator<Item = B> + Clone,
@@ -950,43 +925,28 @@ impl NaiveDateTime {
950925
DelayedFormat::new(Some(self.date), Some(self.time), items)
951926
}
952927

953-
/// Formats the combined date and time with the specified format string.
954-
/// See the [`format::strftime` module](../format/strftime/index.html)
955-
/// on the supported escape sequences.
928+
/// Formats the date and time with the specified format string.
956929
///
957-
/// This returns a `DelayedFormat`,
958-
/// which gets converted to a string only when actual formatting happens.
959-
/// You may use the `to_string` method to get a `String`,
960-
/// or just feed it into `print!` and other formatting macros.
961-
/// (In this way it avoids the redundant memory allocation.)
930+
/// # Deprecated
962931
///
963-
/// A wrong format string does *not* issue an error immediately.
964-
/// Rather, converting or formatting the `DelayedFormat` fails.
965-
/// You are recommended to immediately use `DelayedFormat` for this reason.
932+
/// Use [`format_to_string`](#method.format_to_string) or [`format_with`](#method.format_with)
933+
/// instead.
966934
///
967-
/// # Example
935+
/// # Errors/panics
968936
///
969-
/// ```
970-
/// use chrono::NaiveDate;
937+
/// The `Display` implementation of the returned `DelayedFormat` can return an error if the
938+
/// format string is invalid. This goes against the [contract for `Display`][1], and causes a
939+
/// panic when used in combination with [`to_string`], [`println!`] and [`format!`].
971940
///
972-
/// let dt = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap().and_hms_opt(23, 56, 4).unwrap();
973-
/// assert_eq!(dt.format("%Y-%m-%d %H:%M:%S").to_string(), "2015-09-05 23:56:04");
974-
/// assert_eq!(dt.format("around %l %p on %b %-d").to_string(), "around 11 PM on Sep 5");
975-
/// ```
976-
///
977-
/// The resulting `DelayedFormat` can be formatted directly via the `Display` trait.
978-
///
979-
/// ```
980-
/// # use chrono::NaiveDate;
981-
/// # let dt = NaiveDate::from_ymd_opt(2015, 9, 5).unwrap().and_hms_opt(23, 56, 4).unwrap();
982-
/// assert_eq!(format!("{}", dt.format("%Y-%m-%d %H:%M:%S")), "2015-09-05 23:56:04");
983-
/// assert_eq!(format!("{}", dt.format("around %l %p on %b %-d")), "around 11 PM on Sep 5");
984-
/// ```
941+
/// [1]: https://doc.rust-lang.org/stable/std/fmt/index.html#formatting-traits
942+
/// [`to_string`]: ToString::to_string
985943
#[cfg(any(feature = "alloc", feature = "std"))]
986944
#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
987945
#[inline]
988946
#[must_use]
947+
#[deprecated(since = "0.4.27", note = "Use NaiveDateTime::format_to_string() instead")]
989948
pub fn format<'a>(&self, fmt: &'a str) -> DelayedFormat<StrftimeItems<'a>> {
949+
#[allow(deprecated)]
990950
self.format_with_items(StrftimeItems::new(fmt))
991951
}
992952

‎src/naive/time/mod.rs‎

Lines changed: 12 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -830,40 +830,11 @@ impl NaiveTime {
830830
}
831831

832832
/// Formats the time with the specified formatting items.
833-
/// Otherwise it is the same as the ordinary [`format`](#method.format) method.
834-
///
835-
/// The `Iterator` of items should be `Clone`able,
836-
/// since the resulting `DelayedFormat` value may be formatted multiple times.
837-
///
838-
/// # Example
839-
///
840-
/// ```
841-
/// use chrono::NaiveTime;
842-
/// use chrono::format::strftime::StrftimeItems;
843-
///
844-
/// let items = StrftimeItems::new("%H:%M:%S").parse()?;
845-
/// let fmt = NaiveTime::formatter(&items)?;
846-
/// let t = NaiveTime::from_hms_opt(23, 56, 4).unwrap();
847-
/// assert_eq!(t.format_with(&fmt).to_string(), "23:56:04");
848-
/// assert_eq!(t.format_to_string("%H:%M:%S")?, "23:56:04");
849-
/// # Ok::<(), chrono::ParseError>(())
850-
/// ```
851-
///
852-
/// The resulting `DelayedFormat` can be formatted directly via the `Display` trait.
853-
///
854-
/// ```
855-
/// # use chrono::NaiveTime;
856-
/// # use chrono::format::strftime::StrftimeItems;
857-
/// # let items = StrftimeItems::new("%H:%M:%S").parse()?;
858-
/// # let fmt = NaiveTime::formatter(&items)?;
859-
/// # let t = NaiveTime::from_hms_opt(23, 56, 4).unwrap();
860-
/// assert_eq!(format!("{}", t.format_with(&fmt)), "23:56:04");
861-
/// # Ok::<(), chrono::ParseError>(())
862-
/// ```
863833
#[cfg(any(feature = "alloc", feature = "std"))]
864834
#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
865835
#[inline]
866836
#[must_use]
837+
#[deprecated(since = "0.4.27", note = "Use NaiveTime::format_with() instead")]
867838
pub fn format_with_items<'a, I, B>(&self, items: I) -> DelayedFormat<I>
868839
where
869840
I: Iterator<Item = B> + Clone,
@@ -873,44 +844,27 @@ impl NaiveTime {
873844
}
874845

875846
/// Formats the time with the specified format string.
876-
/// See the [`format::strftime` module](../format/strftime/index.html)
877-
/// on the supported escape sequences.
878847
///
879-
/// This returns a `DelayedFormat`,
880-
/// which gets converted to a string only when actual formatting happens.
881-
/// You may use the `to_string` method to get a `String`,
882-
/// or just feed it into `print!` and other formatting macros.
883-
/// (In this way it avoids the redundant memory allocation.)
848+
/// # Deprecated
884849
///
885-
/// A wrong format string does *not* issue an error immediately.
886-
/// Rather, converting or formatting the `DelayedFormat` fails.
887-
/// You are recommended to immediately use `DelayedFormat` for this reason.
850+
/// Use [`format_to_string`](#method.format_to_string) or [`format_with`](#method.format_with)
851+
/// instead.
888852
///
889-
/// # Example
853+
/// # Errors/panics
890854
///
891-
/// ```
892-
/// use chrono::NaiveTime;
893-
///
894-
/// let t = NaiveTime::from_hms_nano_opt(23, 56, 4, 12_345_678).unwrap();
895-
/// assert_eq!(t.format("%H:%M:%S").to_string(), "23:56:04");
896-
/// assert_eq!(t.format("%H:%M:%S%.6f").to_string(), "23:56:04.012345");
897-
/// assert_eq!(t.format("%-I:%M %p").to_string(), "11:56 PM");
898-
/// ```
855+
/// The `Display` implementation of the returned `DelayedFormat` can return an error if the
856+
/// format string is invalid. This goes against the [contract for `Display`][1], and causes a
857+
/// panic when used in combination with [`to_string`], [`println!`] and [`format!`].
899858
///
900-
/// The resulting `DelayedFormat` can be formatted directly via the `Display` trait.
901-
///
902-
/// ```
903-
/// # use chrono::NaiveTime;
904-
/// # let t = NaiveTime::from_hms_nano_opt(23, 56, 4, 12_345_678).unwrap();
905-
/// assert_eq!(format!("{}", t.format("%H:%M:%S")), "23:56:04");
906-
/// assert_eq!(format!("{}", t.format("%H:%M:%S%.6f")), "23:56:04.012345");
907-
/// assert_eq!(format!("{}", t.format("%-I:%M %p")), "11:56 PM");
908-
/// ```
859+
/// [1]: https://doc.rust-lang.org/stable/std/fmt/index.html#formatting-traits
860+
/// [`to_string`]: ToString::to_string
909861
#[cfg(any(feature = "alloc", feature = "std"))]
910862
#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
911863
#[inline]
912864
#[must_use]
865+
#[deprecated(since = "0.4.27", note = "Use DateTime::format_to_string() instead")]
913866
pub fn format<'a>(&self, fmt: &'a str) -> DelayedFormat<StrftimeItems<'a>> {
867+
#[allow(deprecated)]
914868
self.format_with_items(StrftimeItems::new(fmt))
915869
}
916870

0 commit comments

Comments
 (0)