db_collation/error.rs
1// Copyright 2026 db-collation contributors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Error type for [`crate::Collation`] construction and use.
16
17use core::fmt;
18
19use crate::spec::VersionId;
20
21/// Convenience alias for [`Result`](core::result::Result) with [`Error`].
22pub type Result<T> = core::result::Result<T, Error>;
23
24/// Errors produced when building or using a collation.
25///
26/// The dominant variant is [`Error::Unsupported`]: this crate refuses to guess.
27#[derive(Debug, Clone, PartialEq, Eq)]
28#[non_exhaustive]
29pub enum Error {
30 /// The configuration is not one this crate models exactly.
31 ///
32 /// The caller must fall back to comparing on the source database.
33 Unsupported {
34 /// The provider or engine that was requested.
35 engine: &'static str,
36 /// The collation name or locale that was requested.
37 collation: String,
38 /// Why it is unsupported.
39 reason: &'static str,
40 },
41
42 /// The supplied version metadata does not match the local collation data.
43 ///
44 /// Falling back to the source database is the correct response.
45 VersionMismatch {
46 /// Version the caller says the source is using.
47 source: VersionId,
48 /// Version this build of the library would use.
49 local: VersionId,
50 },
51
52 /// The configuration was recognised but a required backend feature is
53 /// disabled at compile time.
54 FeatureDisabled {
55 /// The cargo feature that would enable it.
56 feature: &'static str,
57 },
58
59 /// The collation is modelled, but a *specific input* exceeds a documented
60 /// limit of the source backend, so the comparison cannot be reproduced
61 /// exactly (e.g. Oracle truncates its UCA sort key past 2000 bytes).
62 ///
63 /// Unlike [`Error::Unsupported`], the configuration itself is supported;
64 /// only this input must fall back to comparing on the source. This is a
65 /// per-input outcome, not a construction failure.
66 InputLimit {
67 /// The provider or engine that was requested.
68 engine: &'static str,
69 /// Why the input cannot be compared.
70 reason: &'static str,
71 },
72}
73
74impl Error {
75 /// Construct an [`Error::Unsupported`].
76 pub(crate) fn unsupported(
77 engine: &'static str,
78 collation: impl Into<String>,
79 reason: &'static str,
80 ) -> Self {
81 Self::Unsupported {
82 engine,
83 collation: collation.into(),
84 reason,
85 }
86 }
87
88 /// Construct an [`Error::InputLimit`].
89 #[cfg(feature = "oracle-uca")]
90 pub(crate) fn input_limit(engine: &'static str, reason: &'static str) -> Self {
91 Self::InputLimit { engine, reason }
92 }
93
94 /// Returns `true` if the caller should fall back to the source database.
95 #[must_use]
96 pub const fn is_fallback_required(&self) -> bool {
97 matches!(
98 self,
99 Self::Unsupported { .. }
100 | Self::VersionMismatch { .. }
101 | Self::FeatureDisabled { .. }
102 | Self::InputLimit { .. }
103 )
104 }
105}
106
107impl fmt::Display for Error {
108 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
109 match self {
110 Self::Unsupported {
111 engine,
112 collation,
113 reason,
114 } => write!(
115 f,
116 "unsupported {engine} collation \"{collation}\": {reason}; compare on the source instead"
117 ),
118 Self::VersionMismatch { source, local } => write!(
119 f,
120 "collation data version mismatch: source {source}, local {local}; compare on the source instead"
121 ),
122 Self::FeatureDisabled { feature } => {
123 write!(
124 f,
125 "backend disabled at compile time; enable feature {feature:?}"
126 )
127 }
128 Self::InputLimit { engine, reason } => write!(
129 f,
130 "{engine} collation cannot compare this input: {reason}; compare on the source instead"
131 ),
132 }
133 }
134}
135
136impl core::error::Error for Error {}