Skip to main content

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 {}