Debian Codegraph @

third_party/rust/time/src/formatting/mod.rs

raw
1 //! Formatting for various types.
2
3 pub(crate) mod formattable;
4 mod iso8601;
5 use core::num::NonZeroU8;
6 use std::io;
7
8 use num_conv::prelude::*;
9
10 pub use self::formattable::Formattable;
11 use crate::convert::*;
12 use crate::ext::DigitCount;
13 use crate::format_description::{modifier, Component};
14 use crate::{error, Date, OffsetDateTime, Time, UtcOffset};
15
16 #[allow(clippy::missing_docs_in_private_items)]
17 const MONTH_NAMES: [&[u8]; 12] = [
18 b"January",
19 b"February",
20 b"March",
21 b"April",
22 b"May",
23 b"June",
24 b"July",
25 b"August",
26 b"September",
27 b"October",
28 b"November",
29 b"December",
30 ];
31
32 #[allow(clippy::missing_docs_in_private_items)]
33 const WEEKDAY_NAMES: [&[u8]; 7] = [
34 b"Monday",
35 b"Tuesday",
36 b"Wednesday",
37 b"Thursday",
38 b"Friday",
39 b"Saturday",
40 b"Sunday",
41 ];
42
43 /// Write all bytes to the output, returning the number of bytes written.
44 pub(crate) fn write(output: &mut impl io::Write, bytes: &[u8]) -> io::Result<usize> {
45 output.write_all(bytes)?;
46 Ok(bytes.len())
47 }
48
49 /// If `pred` is true, write all bytes to the output, returning the number of bytes written.
50 pub(crate) fn write_if(output: &mut impl io::Write, pred: bool, bytes: &[u8]) -> io::Result<usize> {
51 if pred { write(output, bytes) } else { Ok(0) }
52 }
53
54 /// If `pred` is true, write `true_bytes` to the output. Otherwise, write `false_bytes`.
55 pub(crate) fn write_if_else(
56 output: &mut impl io::Write,
57 pred: bool,
58 true_bytes: &[u8],
59 false_bytes: &[u8],
60 ) -> io::Result<usize> {
61 write(output, if pred { true_bytes } else { false_bytes })
62 }
63
64 /// Write the floating point number to the output, returning the number of bytes written.
65 ///
66 /// This method accepts the number of digits before and after the decimal. The value will be padded
67 /// with zeroes to the left if necessary.
68 pub(crate) fn format_float(
69 output: &mut impl io::Write,
70 value: f64,
71 digits_before_decimal: u8,
72 digits_after_decimal: Option<NonZeroU8>,
73 ) -> io::Result<usize> {
74 match digits_after_decimal {
75 Some(digits_after_decimal) => {
76 let digits_after_decimal = digits_after_decimal.get().extend();
77 let width = digits_before_decimal.extend::<usize>() + 1 + digits_after_decimal;
78 write!(output, "{value:0>width$.digits_after_decimal$}")?;
79 Ok(width)
80 }
81 None => {
82 let value = value.trunc() as u64;
83 let width = digits_before_decimal.extend();
84 write!(output, "{value:0>width$}")?;
85 Ok(width)
86 }
87 }
88 }
89
90 /// Format a number with the provided padding and width.
91 ///
92 /// The sign must be written by the caller.
93 pub(crate) fn format_number<const WIDTH: u8>(
94 output: &mut impl io::Write,
95 value: impl itoa::Integer + DigitCount + Copy,
96 padding: modifier::Padding,
97 ) -> Result<usize, io::Error> {
98 match padding {
99 modifier::Padding::Space => format_number_pad_space::<WIDTH>(output, value),
100 modifier::Padding::Zero => format_number_pad_zero::<WIDTH>(output, value),
101 modifier::Padding::None => format_number_pad_none(output, value),
102 }
103 }
104
105 /// Format a number with the provided width and spaces as padding.
106 ///
107 /// The sign must be written by the caller.
108 pub(crate) fn format_number_pad_space<const WIDTH: u8>(
109 output: &mut impl io::Write,
110 value: impl itoa::Integer + DigitCount + Copy,
111 ) -> Result<usize, io::Error> {
112 let mut bytes = 0;
113 for _ in 0..(WIDTH.saturating_sub(value.num_digits())) {
114 bytes += write(output, b" ")?;
115 }
116 bytes += write(output, itoa::Buffer::new().format(value).as_bytes())?;
117 Ok(bytes)
118 }
119
120 /// Format a number with the provided width and zeros as padding.
121 ///
122 /// The sign must be written by the caller.
123 pub(crate) fn format_number_pad_zero<const WIDTH: u8>(
124 output: &mut impl io::Write,
125 value: impl itoa::Integer + DigitCount + Copy,
126 ) -> Result<usize, io::Error> {
127 let mut bytes = 0;
128 for _ in 0..(WIDTH.saturating_sub(value.num_digits())) {
129 bytes += write(output, b"0")?;
130 }
131 bytes += write(output, itoa::Buffer::new().format(value).as_bytes())?;
132 Ok(bytes)
133 }
134
135 /// Format a number with no padding.
136 ///
137 /// If the sign is mandatory, the sign must be written by the caller.
138 pub(crate) fn format_number_pad_none(
139 output: &mut impl io::Write,
140 value: impl itoa::Integer + Copy,
141 ) -> Result<usize, io::Error> {
142 write(output, itoa::Buffer::new().format(value).as_bytes())
143 }
144
145 /// Format the provided component into the designated output. An `Err` will be returned if the
146 /// component requires information that it does not provide or if the value cannot be output to the
147 /// stream.
148 pub(crate) fn format_component(
149 output: &mut impl io::Write,
150 component: Component,
151 date: Option<Date>,
152 time: Option<Time>,
153 offset: Option<UtcOffset>,
154 ) -> Result<usize, error::Format> {
155 use Component::*;
156 Ok(match (component, date, time, offset) {
157 (Day(modifier), Some(date), ..) => fmt_day(output, date, modifier)?,
158 (Month(modifier), Some(date), ..) => fmt_month(output, date, modifier)?,
159 (Ordinal(modifier), Some(date), ..) => fmt_ordinal(output, date, modifier)?,
160 (Weekday(modifier), Some(date), ..) => fmt_weekday(output, date, modifier)?,
161 (WeekNumber(modifier), Some(date), ..) => fmt_week_number(output, date, modifier)?,
162 (Year(modifier), Some(date), ..) => fmt_year(output, date, modifier)?,
163 (Hour(modifier), _, Some(time), _) => fmt_hour(output, time, modifier)?,
164 (Minute(modifier), _, Some(time), _) => fmt_minute(output, time, modifier)?,
165 (Period(modifier), _, Some(time), _) => fmt_period(output, time, modifier)?,
166 (Second(modifier), _, Some(time), _) => fmt_second(output, time, modifier)?,
167 (Subsecond(modifier), _, Some(time), _) => fmt_subsecond(output, time, modifier)?,
168 (OffsetHour(modifier), .., Some(offset)) => fmt_offset_hour(output, offset, modifier)?,
169 (OffsetMinute(modifier), .., Some(offset)) => fmt_offset_minute(output, offset, modifier)?,
170 (OffsetSecond(modifier), .., Some(offset)) => fmt_offset_second(output, offset, modifier)?,
171 (Ignore(_), ..) => 0,
172 (UnixTimestamp(modifier), Some(date), Some(time), Some(offset)) => {
173 fmt_unix_timestamp(output, date, time, offset, modifier)?
174 }
175 (End(modifier::End {}), ..) => 0,
176
177 // This is functionally the same as a wildcard arm, but it will cause an error if a new
178 // component is added. This is to avoid a bug where a new component, the code compiles, and
179 // formatting fails.
180 // Allow unreachable patterns because some branches may be fully matched above.
181 #[allow(unreachable_patterns)]
182 (
183 Day(_) | Month(_) | Ordinal(_) | Weekday(_) | WeekNumber(_) | Year(_) | Hour(_)
184 | Minute(_) | Period(_) | Second(_) | Subsecond(_) | OffsetHour(_) | OffsetMinute(_)
185 | OffsetSecond(_) | Ignore(_) | UnixTimestamp(_) | End(_),
186 ..,
187 ) => return Err(error::Format::InsufficientTypeInformation),
188 })
189 }
190
191 // region: date formatters
192 /// Format the day into the designated output.
193 fn fmt_day(
194 output: &mut impl io::Write,
195 date: Date,
196 modifier::Day { padding }: modifier::Day,
197 ) -> Result<usize, io::Error> {
198 format_number::<2>(output, date.day(), padding)
199 }
200
201 /// Format the month into the designated output.
202 fn fmt_month(
203 output: &mut impl io::Write,
204 date: Date,
205 modifier::Month {
206 padding,
207 repr,
208 case_sensitive: _, // no effect on formatting
209 }: modifier::Month,
210 ) -> Result<usize, io::Error> {
211 match repr {
212 modifier::MonthRepr::Numerical => {
213 format_number::<2>(output, u8::from(date.month()), padding)
214 }
215 modifier::MonthRepr::Long => write(
216 output,
217 MONTH_NAMES[u8::from(date.month()).extend::<usize>() - 1],
218 ),
219 modifier::MonthRepr::Short => write(
220 output,
221 &MONTH_NAMES[u8::from(date.month()).extend::<usize>() - 1][..3],
222 ),
223 }
224 }
225
226 /// Format the ordinal into the designated output.
227 fn fmt_ordinal(
228 output: &mut impl io::Write,
229 date: Date,
230 modifier::Ordinal { padding }: modifier::Ordinal,
231 ) -> Result<usize, io::Error> {
232 format_number::<3>(output, date.ordinal(), padding)
233 }
234
235 /// Format the weekday into the designated output.
236 fn fmt_weekday(
237 output: &mut impl io::Write,
238 date: Date,
239 modifier::Weekday {
240 repr,
241 one_indexed,
242 case_sensitive: _, // no effect on formatting
243 }: modifier::Weekday,
244 ) -> Result<usize, io::Error> {
245 match repr {
246 modifier::WeekdayRepr::Short => write(
247 output,
248 &WEEKDAY_NAMES[date.weekday().number_days_from_monday().extend::<usize>()][..3],
249 ),
250 modifier::WeekdayRepr::Long => write(
251 output,
252 WEEKDAY_NAMES[date.weekday().number_days_from_monday().extend::<usize>()],
253 ),
254 modifier::WeekdayRepr::Sunday => format_number::<1>(
255 output,
256 date.weekday().number_days_from_sunday() + u8::from(one_indexed),
257 modifier::Padding::None,
258 ),
259 modifier::WeekdayRepr::Monday => format_number::<1>(
260 output,
261 date.weekday().number_days_from_monday() + u8::from(one_indexed),
262 modifier::Padding::None,
263 ),
264 }
265 }
266
267 /// Format the week number into the designated output.
268 fn fmt_week_number(
269 output: &mut impl io::Write,
270 date: Date,
271 modifier::WeekNumber { padding, repr }: modifier::WeekNumber,
272 ) -> Result<usize, io::Error> {
273 format_number::<2>(
274 output,
275 match repr {
276 modifier::WeekNumberRepr::Iso => date.iso_week(),
277 modifier::WeekNumberRepr::Sunday => date.sunday_based_week(),
278 modifier::WeekNumberRepr::Monday => date.monday_based_week(),
279 },
280 padding,
281 )
282 }
283
284 /// Format the year into the designated output.
285 fn fmt_year(
286 output: &mut impl io::Write,
287 date: Date,
288 modifier::Year {
289 padding,
290 repr,
291 iso_week_based,
292 sign_is_mandatory,
293 }: modifier::Year,
294 ) -> Result<usize, io::Error> {
295 let full_year = if iso_week_based {
296 date.iso_year_week().0
297 } else {
298 date.year()
299 };
300 let value = match repr {
301 modifier::YearRepr::Full => full_year,
302 modifier::YearRepr::LastTwo => (full_year % 100).abs(),
303 };
304 let format_number = match repr {
305 #[cfg(feature = "large-dates")]
306 modifier::YearRepr::Full if value.abs() >= 100_000 => format_number::<6>,
307 #[cfg(feature = "large-dates")]
308 modifier::YearRepr::Full if value.abs() >= 10_000 => format_number::<5>,
309 modifier::YearRepr::Full => format_number::<4>,
310 modifier::YearRepr::LastTwo => format_number::<2>,
311 };
312 let mut bytes = 0;
313 if repr != modifier::YearRepr::LastTwo {
314 if full_year < 0 {
315 bytes += write(output, b"-")?;
316 } else if sign_is_mandatory || cfg!(feature = "large-dates") && full_year >= 10_000 {
317 bytes += write(output, b"+")?;
318 }
319 }
320 bytes += format_number(output, value.unsigned_abs(), padding)?;
321 Ok(bytes)
322 }
323 // endregion date formatters
324
325 // region: time formatters
326 /// Format the hour into the designated output.
327 fn fmt_hour(
328 output: &mut impl io::Write,
329 time: Time,
330 modifier::Hour {
331 padding,
332 is_12_hour_clock,
333 }: modifier::Hour,
334 ) -> Result<usize, io::Error> {
335 let value = match (time.hour(), is_12_hour_clock) {
336 (hour, false) => hour,
337 (0 | 12, true) => 12,
338 (hour, true) if hour < 12 => hour,
339 (hour, true) => hour - 12,
340 };
341 format_number::<2>(output, value, padding)
342 }
343
344 /// Format the minute into the designated output.
345 fn fmt_minute(
346 output: &mut impl io::Write,
347 time: Time,
348 modifier::Minute { padding }: modifier::Minute,
349 ) -> Result<usize, io::Error> {
350 format_number::<2>(output, time.minute(), padding)
351 }
352
353 /// Format the period into the designated output.
354 fn fmt_period(
355 output: &mut impl io::Write,
356 time: Time,
357 modifier::Period {
358 is_uppercase,
359 case_sensitive: _, // no effect on formatting
360 }: modifier::Period,
361 ) -> Result<usize, io::Error> {
362 match (time.hour() >= 12, is_uppercase) {
363 (false, false) => write(output, b"am"),
364 (false, true) => write(output, b"AM"),
365 (true, false) => write(output, b"pm"),
366 (true, true) => write(output, b"PM"),
367 }
368 }
369
370 /// Format the second into the designated output.
371 fn fmt_second(
372 output: &mut impl io::Write,
373 time: Time,
374 modifier::Second { padding }: modifier::Second,
375 ) -> Result<usize, io::Error> {
376 format_number::<2>(output, time.second(), padding)
377 }
378
379 /// Format the subsecond into the designated output.
380 fn fmt_subsecond<W: io::Write>(
381 output: &mut W,
382 time: Time,
383 modifier::Subsecond { digits }: modifier::Subsecond,
384 ) -> Result<usize, io::Error> {
385 use modifier::SubsecondDigits::*;
386 let nanos = time.nanosecond();
387
388 if digits == Nine || (digits == OneOrMore && nanos % 10 != 0) {
389 format_number_pad_zero::<9>(output, nanos)
390 } else if digits == Eight || (digits == OneOrMore && (nanos / 10) % 10 != 0) {
391 format_number_pad_zero::<8>(output, nanos / 10)
392 } else if digits == Seven || (digits == OneOrMore && (nanos / 100) % 10 != 0) {
393 format_number_pad_zero::<7>(output, nanos / 100)
394 } else if digits == Six || (digits == OneOrMore && (nanos / 1_000) % 10 != 0) {
395 format_number_pad_zero::<6>(output, nanos / 1_000)
396 } else if digits == Five || (digits == OneOrMore && (nanos / 10_000) % 10 != 0) {
397 format_number_pad_zero::<5>(output, nanos / 10_000)
398 } else if digits == Four || (digits == OneOrMore && (nanos / 100_000) % 10 != 0) {
399 format_number_pad_zero::<4>(output, nanos / 100_000)
400 } else if digits == Three || (digits == OneOrMore && (nanos / 1_000_000) % 10 != 0) {
401 format_number_pad_zero::<3>(output, nanos / 1_000_000)
402 } else if digits == Two || (digits == OneOrMore && (nanos / 10_000_000) % 10 != 0) {
403 format_number_pad_zero::<2>(output, nanos / 10_000_000)
404 } else {
405 format_number_pad_zero::<1>(output, nanos / 100_000_000)
406 }
407 }
408 // endregion time formatters
409
410 // region: offset formatters
411 /// Format the offset hour into the designated output.
412 fn fmt_offset_hour(
413 output: &mut impl io::Write,
414 offset: UtcOffset,
415 modifier::OffsetHour {
416 padding,
417 sign_is_mandatory,
418 }: modifier::OffsetHour,
419 ) -> Result<usize, io::Error> {
420 let mut bytes = 0;
421 if offset.is_negative() {
422 bytes += write(output, b"-")?;
423 } else if sign_is_mandatory {
424 bytes += write(output, b"+")?;
425 }
426 bytes += format_number::<2>(output, offset.whole_hours().unsigned_abs(), padding)?;
427 Ok(bytes)
428 }
429
430 /// Format the offset minute into the designated output.
431 fn fmt_offset_minute(
432 output: &mut impl io::Write,
433 offset: UtcOffset,
434 modifier::OffsetMinute { padding }: modifier::OffsetMinute,
435 ) -> Result<usize, io::Error> {
436 format_number::<2>(output, offset.minutes_past_hour().unsigned_abs(), padding)
437 }
438
439 /// Format the offset second into the designated output.
440 fn fmt_offset_second(
441 output: &mut impl io::Write,
442 offset: UtcOffset,
443 modifier::OffsetSecond { padding }: modifier::OffsetSecond,
444 ) -> Result<usize, io::Error> {
445 format_number::<2>(output, offset.seconds_past_minute().unsigned_abs(), padding)
446 }
447 // endregion offset formatters
448
449 /// Format the Unix timestamp into the designated output.
450 fn fmt_unix_timestamp(
451 output: &mut impl io::Write,
452 date: Date,
453 time: Time,
454 offset: UtcOffset,
455 modifier::UnixTimestamp {
456 precision,
457 sign_is_mandatory,
458 }: modifier::UnixTimestamp,
459 ) -> Result<usize, io::Error> {
460 let date_time = OffsetDateTime::new_in_offset(date, time, offset).to_offset(UtcOffset::UTC);
461
462 if date_time < OffsetDateTime::UNIX_EPOCH {
463 write(output, b"-")?;
464 } else if sign_is_mandatory {
465 write(output, b"+")?;
466 }
467
468 match precision {
469 modifier::UnixTimestampPrecision::Second => {
470 format_number_pad_none(output, date_time.unix_timestamp().unsigned_abs())
471 }
472 modifier::UnixTimestampPrecision::Millisecond => format_number_pad_none(
473 output,
474 (date_time.unix_timestamp_nanos()
475 / Nanosecond::per(Millisecond).cast_signed().extend::<i128>())
476 .unsigned_abs(),
477 ),
478 modifier::UnixTimestampPrecision::Microsecond => format_number_pad_none(
479 output,
480 (date_time.unix_timestamp_nanos()
481 / Nanosecond::per(Microsecond).cast_signed().extend::<i128>())
482 .unsigned_abs(),
483 ),
484 modifier::UnixTimestampPrecision::Nanosecond => {
485 format_number_pad_none(output, date_time.unix_timestamp_nanos().unsigned_abs())
486 }
487 }
488 }