realm_db_reader/
error.rs

1use std::error::Error;
2
3use thiserror::Error;
4
5use crate::{Row, Value};
6
7/// Errors that occur while reading a Realm file, such as I/O errors or invalid
8/// file formats.
9#[derive(Debug, Error)]
10pub enum RealmFileError {
11    /// Error occurred while reading the file.
12    #[error("I/O error: {0}")]
13    Io(#[from] std::io::Error),
14
15    /// The Realm file is invalid, e.g. due to corrupted data.
16    #[error("Invalid Realm file detected: {reason}")]
17    InvalidRealmFile {
18        /// Reason for detecting the invalid file.
19        reason: String,
20    },
21
22    /// The Realm file uses a feature that is not supported by this version of
23    /// the library.
24    #[error("Unsupported Realm feature: {reason}")]
25    Unsupported {
26        /// Reason for the unsupported feature.
27        reason: String,
28    },
29}
30
31/// Errors that occur while reading a table, such as invalid column names or
32/// missing columns.
33#[derive(Debug, Error)]
34pub enum TableError {
35    /// A file error occurred. See [`RealmFileError`].
36    #[error("Realm file error: {0}")]
37    FileError(#[from] RealmFileError),
38
39    /// Tried to access a table that does not exist.
40    #[error("Table not found with name '{name}'")]
41    TableNotFound {
42        /// Name of the table that was not found.
43        name: String,
44    },
45
46    /// Tried to access a column that does not exist.
47    #[error("Column not found with name '{name}'")]
48    ColumnNotFound {
49        /// Name of the column that was not found.
50        name: String,
51    },
52
53    /// Tried to query a column (using
54    /// [`find_row_from_indexed_column`](crate::Table::find_row_from_indexed_column)
55    /// or
56    /// [`find_row_number_from_indexed_column`](crate::Table::find_row_number_from_indexed_column)),
57    /// but the column is not indexed.
58    #[error("Column '{name}' is not indexed")]
59    ColumnNotIndexed {
60        /// Name of the column that is not indexed.
61        name: String,
62    },
63}
64
65/// Errors related to value conversions, usually when converting to a model
66/// using [`realm_model`](crate::realm_model).
67#[derive(Debug, Error)]
68pub enum ValueError {
69    /// Expected a Table value, found something else. This can happen when
70    /// trying to convert a [`Value`] into a `Vec<T>`, if the data is not
71    /// structured as expected.
72    #[error("Expected a Table value, found {found:?}")]
73    ExpectedTable { found: Value },
74
75    /// Expected an array row, but found something else. This can happen when
76    /// trying to convert a [`Row`] into a target type. In Realm, if a model has
77    /// a field that's the equivalent of, e.g. `Vec<String>`, that is
78    /// represented as a subtable, where each row has a single column of type
79    /// `String`, with name [`field`](Self::ExpectedArrayRow::field). If this
80    /// error occurs, it means the row in the subtable does not have the
81    /// expected field.
82    #[error("Expected a row with field '{field}', found {found:?}")]
83    ExpectedArrayRow {
84        /// The name of the field that was expected.
85        field: &'static str,
86        /// The row that was found, which did not have the expected field.
87        found: Row<'static>,
88    },
89
90    /// Expected a different type. This could happen if your
91    /// [`realm_model`](crate::realm_model) definition is incorrect, and a
92    /// column has a different type than expected.
93    #[error("Unexpected type: expected {expected:?}, found {found:?}")]
94    UnexpectedType {
95        /// The expected type.
96        expected: &'static str,
97        /// The actual value.
98        found: Value,
99    },
100
101    /// Failed to convert a [`Row`] from a subtable into a `Vec<T>`, because the
102    /// underlying `T: TryFrom<Row>>` failed.
103    #[error("Failed to convert value in row to Vec<{element_type}>: {source}")]
104    VecConversionError {
105        /// The type of the elements in the vector.
106        element_type: &'static str,
107        /// The error that occurred during conversion.
108        source: Box<dyn Error>,
109    },
110
111    /// Missing field when converting a [`Row`] into a struct. This can happen
112    /// if your [`realm_model`](crate::realm_model) definition is incorrect, and
113    /// a column doesn't exist, or has a different name than expected.
114    #[error(
115        "Missing field '{field}' when converting row into '{target_type}' (remaining fields: '{remaining_fields:?}"
116    )]
117    MissingField {
118        /// The name of the missing field.
119        field: &'static str,
120        /// The type of the target struct.
121        target_type: &'static str,
122        /// The remaining fields in the row. Note that if the missing field is
123        /// not the first field, some fields may be missing from the overall
124        /// row, as they were already converted before the missing field was
125        /// encountered.
126        remaining_fields: Row<'static>,
127    },
128}
129
130/// Convenience type alias for `Result<T, RealmFileError>`.
131pub type RealmResult<T> = std::result::Result<T, RealmFileError>;
132
133/// Convenience type alias for `Result<T, TableError>`.
134pub type TableResult<T> = std::result::Result<T, TableError>;
135
136/// Convenience type alias for `Result<T, ValueError>`.
137pub type ValueResult<T> = std::result::Result<T, ValueError>;
realm_db_reader/error.rs

realm_db_reader/
error.rs
