deep_time/error.rs
1//! [`DtErrKind`] and main error type [`DtErr`].
2//! [`DtErr`] is a type alias to [`AnErr`].
3
4use crate::AnErr;
5
6/// Failure category inside [`DtErr`](crate::DtErr) — parse errors, out-of-range
7/// values, missing features, and similar cases.
8///
9/// Almost every function in this crate that can fail returns a
10/// [`DtErr`](crate::DtErr). That error is made of two parts:
11///
12/// 1. A **kind** — one of the variants of this enum (what went wrong).
13/// 2. A short **reason** string — optional extra detail (up to 15 bytes).
14///
15/// Those two pieces live inside [`AnErr`](crate::AnErr). [`DtErr`](crate::DtErr)
16/// is simply `AnErr<DtErrKind, 15>` — the whole error is 16 bytes.
17///
18/// Create one with the [`an_err!`](crate::an_err) macro, and read the kind
19/// back with [`.kind()`](crate::AnErr::kind):
20///
21/// ```
22/// use deep_time::{DtErr, DtErrKind, an_err};
23///
24/// let err: DtErr = an_err!(DtErrKind::YearOutOfRange, "year={}", 10_000);
25/// assert_eq!(err.kind(), DtErrKind::YearOutOfRange);
26/// ```
27///
28/// When printed, an error looks like `YearOutOfRange` or
29/// `YearOutOfRange: year=10000`.
30///
31/// This enum is marked `#[non_exhaustive]`, so new variants may be added in
32/// later releases. Always keep a catch-all arm (`_ => ...`) when matching.
33#[non_exhaustive]
34#[repr(u8)]
35#[derive(Debug, Clone, Copy, PartialEq, Eq)]
36#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
37#[cfg_attr(feature = "tsify", derive(tsify::Tsify))]
38#[cfg_attr(feature = "defmt", derive(defmt::Format))]
39pub enum DtErrKind {
40 /// Input ended before a complete token or value was parsed.
41 UnexpectedEnd,
42 /// A format `%` directive was cut off before its letter.
43 TruncatedDirective,
44 /// Unrecognized format directive or parse item.
45 UnknownItem,
46 /// Required Cargo feature is not enabled.
47 MissingFeature,
48 /// A reference time or the `std` feature is required for this operation.
49 MissingRefTimeOrStd,
50 /// Input must begin with a specific prefix or pattern.
51 MustStartWith,
52 /// Format item or value type is not supported in this context.
53 UnsupportedItem,
54 /// A required literal character in the format did not match input.
55 MismatchedLiteral,
56 /// Expected a duration unit (e.g. `s`, `ms`, `day`).
57 ExpectedUnit,
58 /// Expected a numeric value.
59 ExpectedValue,
60 /// Expected a year field.
61 ExpectedYear,
62 /// Expected a century field.
63 ExpectedCentury,
64 /// Expected a month field.
65 ExpectedMonth,
66 /// Expected a day-of-month field.
67 ExpectedDay,
68 /// Expected a day-of-year field.
69 ExpectedDayOfYear,
70 /// Expected an hour field.
71 ExpectedHour,
72 /// Expected a minute field.
73 ExpectedMinute,
74 /// Expected a second field.
75 ExpectedSecond,
76 /// Expected a fractional-seconds field.
77 ExpectedFractional,
78 /// Expected a Unix or epoch timestamp field.
79 ExpectedTimestamp,
80 /// Expected a week-number field.
81 ExpectedWeekNumber,
82 /// Expected a weekday-number field.
83 ExpectedWeekdayNumber,
84 /// Expected one or more decimal digits.
85 ExpectedDigits,
86 /// Expected a Monday-based weekday number.
87 ExpectedMonWeekday,
88 /// Expected a Sunday-based weekday number.
89 ExpectedSunWeekday,
90 /// Expected a Monday-based week number.
91 ExpectedMonWeek,
92 /// Expected a Sunday-based week number.
93 ExpectedSunWeek,
94 /// Monday-based weekday number is outside 1–7.
95 MonWeekdayOutOfRange,
96 /// Sunday-based weekday number is outside 0–6 (or 1–7).
97 SunWeekdayOutOfRange,
98 /// Invalid binary/wire code or format identifier.
99 InvalidCodeId,
100 /// Sequence is not strictly increasing (e.g. leap-second table).
101 NonMonotonic,
102 /// CCSDS or binary T-field is shorter than required.
103 TFieldTooShort,
104 /// CCSDS or binary P-field is shorter than required.
105 PFieldTooShort,
106 /// Sub-millisecond fractional part is invalid.
107 InvalidSubmillisecond,
108 /// Weekday name could not be recognized.
109 InvalidWeekdayName,
110 /// Month name could not be recognized.
111 InvalidMonthName,
112 /// AM/PM (meridiem) indicator is invalid.
113 InvalidMeridiem,
114 /// Time scale name or code is invalid.
115 InvalidScale,
116 /// Calendar date is not a valid civil date.
117 InvalidDate,
118 /// Time-of-day is not a valid civil time.
119 InvalidTime,
120 /// Year value is invalid for the operation.
121 InvalidYear,
122 /// Month value is invalid (not 1–12, or unusable in context).
123 InvalidMonth,
124 /// Day-of-month is invalid for the given month/year.
125 InvalidDay,
126 /// Day-of-year is invalid (not 1–365/366).
127 InvalidDayOfYear,
128 /// ISO week-year is invalid.
129 InvalidIsoWeekYear,
130 /// ISO week number is invalid.
131 InvalidIsoWeek,
132 /// Sunday-based week number is invalid.
133 InvalidSunWeek,
134 /// Monday-based week number is invalid.
135 InvalidMonWeek,
136 /// Hour is invalid for the civil time representation.
137 InvalidHour,
138 /// Minute is invalid (typically not 0–59).
139 InvalidMinute,
140 /// Second is invalid (including leap-second rules where applicable).
141 InvalidSecond,
142 /// Fractional seconds field is invalid.
143 InvalidFractional,
144 /// Timestamp value is invalid or could not be interpreted.
145 InvalidTimestamp,
146 /// Name (e.g. language or locale) is invalid.
147 InvalidName,
148 /// Time zone identifier could not be resolved.
149 InvalidTimeZone,
150 /// UTC offset is missing a required `+` or `-` sign.
151 OffsetMissingSign,
152 /// Hour component of a UTC offset is invalid.
153 InvalidOffsetHour,
154 /// Minute component of a UTC offset is invalid.
155 InvalidOffsetMinute,
156 /// Second component of a UTC offset is invalid.
157 InvalidOffsetSecond,
158 /// UTC offset colon separators are malformed.
159 InvalidOffsetColons,
160 /// UTC offset string or value is invalid overall.
161 InvalidOffset,
162 /// Numeric token could not be parsed.
163 InvalidNumber,
164 /// Format or parse item is invalid in this context.
165 InvalidItem,
166 /// Byte sequence is not valid for the expected encoding.
167 InvalidBytes,
168 /// Input syntax is invalid.
169 InvalidSyntax,
170 /// A value lies outside the allowed range for this operation.
171 OutOfRange,
172 /// Month is outside the valid range.
173 MonthOutOfRange,
174 /// Day is outside the valid range.
175 DayOutOfRange,
176 /// Day-of-year is outside the valid range.
177 DayOfYearOutOfRange,
178 /// Hour is outside the valid range.
179 HourOutOfRange,
180 /// Minute is outside the valid range.
181 MinuteOutOfRange,
182 /// Second is outside the valid range.
183 SecondOutOfRange,
184 /// Week number is outside the valid range.
185 WeekOutOfRange,
186 /// ISO week number is outside the valid range.
187 IsoWeekOutOfRange,
188 /// Year is outside the valid range.
189 YearOutOfRange,
190 /// Fractional part is outside the valid range.
191 FracOutOfRange,
192 /// Modified Julian Date is outside the valid range.
193 MjdOutOfRange,
194 /// Input has unexpected characters after a complete value.
195 TrailingCharacters,
196 /// Parse or conversion stopped before a complete value was formed.
197 Incomplete,
198 /// Input is invalid for a reason not covered by a more specific kind.
199 InvalidInput,
200 /// Buffer or field length is invalid.
201 InvalidLen,
202 /// Internal invariant failed (should not occur in normal use).
203 InternalErr,
204 /// Conversion between representations or crates failed.
205 ConversionFail,
206 /// I/O error while reading or writing data (e.g. EOP file).
207 IOErr,
208 /// Input is empty where a value was required.
209 Empty,
210}
211
212/// Wrapper around [`AnErr`].
213///
214/// A [`DtErr`] object is 20 bytes.
215pub type DtErr = AnErr<DtErrKind, 16>;