axion_data/
error.rs

1use crate::dtype::DataType;
2use std::fmt::{self, Display};
3use std::error::Error;
4
5/// Axion 操作中可能发生的错误类型
6/// 
7/// 涵盖了数据处理、类型转换、IO 操作等各种场景下可能出现的错误情况。
8/// 提供了详细的错误信息以便于调试和错误处理。
9#[derive(Debug)]
10pub enum AxionError {
11    /// DataFrame 列长度不一致错误
12    /// 
13    /// 当尝试创建 DataFrame 时，如果不同列的长度不匹配会触发此错误
14    MismatchedLengths { 
15        /// 期望的长度
16        expected: usize, 
17        /// 实际发现的长度
18        found: usize, 
19        /// 相关的列名或操作名
20        name: String 
21    },
22    
23    /// 重复列名错误
24    /// 
25    /// 当尝试创建包含重复列名的 DataFrame 时触发
26    DuplicateColumnName(String),
27    
28    /// 列不存在错误
29    /// 
30    /// 当按名称或索引选择列时，指定的列不存在
31    ColumnNotFound(String),
32    
33    /// 类型错误
34    /// 
35    /// 当尝试对列执行操作但类型不匹配时触发
36    TypeError { 
37        /// 期望的类型描述
38        expected: String, 
39        /// 实际发现的类型
40        found: DataType, 
41        /// 相关的列名
42        name: String 
43    },
44    
45    /// 类型不匹配错误
46    /// 
47    /// 当尝试向下转型列时，类型不匹配
48    TypeMismatch { 
49        /// 期望的数据类型
50        expected: DataType, 
51        /// 实际发现的数据类型
52        found: DataType, 
53        /// 相关的列名
54        name: String 
55    },
56    
57    /// 未提供列错误
58    /// 
59    /// 当尝试创建 DataFrame 时没有提供任何列
60    NoColumnsProvided,
61    
62    /// 类型转换错误
63    CastError(CastError),
64    
65    /// Join 操作键列类型错误
66    JoinKeyTypeError {
67        /// 哪一侧的表（"left" 或 "right"）
68        side: String,
69        /// 键列名称
70        name: String,
71        /// 期望的数据类型
72        expected: DataType,
73        /// 实际发现的数据类型
74        found: DataType,
75    },
76    
77    /// 索引越界错误
78    /// 
79    /// 当访问的索引超出有效范围时触发
80    IndexOutOfBounds(usize, usize), // (访问的索引, 集合长度)
81    
82    /// 索引超出范围错误（别名，用于向后兼容）
83    IndexOutOfRange(usize, usize), // (访问的索引, 集合长度)
84    
85    /// 计算错误
86    /// 
87    /// 在数学计算过程中发生的错误（如除零）
88    ComputeError(String),
89    
90    /// 不支持的操作错误
91    /// 
92    /// 当在不支持的类型上执行特定操作时触发
93    UnsupportedOperation(String),
94    
95    /// 无效参数错误
96    /// 
97    /// 当提供的参数不符合要求时触发
98    InvalidArgument(String),
99    
100    /// 内部错误
101    /// 
102    /// 表示意外的内部状态或逻辑错误，通常表示代码中存在 bug
103    InternalError(String),
104    
105    /// CSV 处理错误
106    /// 
107    /// 在读取或写入 CSV 文件时发生的错误
108    CsvError(String),
109    
110    /// IO 错误
111    /// 
112    /// 文件输入输出相关的错误
113    IoError(String),
114    
115    /// 其他未分类错误
116    Other(String),
117}
118
119/// Series 类型转换错误
120/// 
121/// 当 Series 之间进行类型转换失败时产生的错误。
122#[derive(Debug)]
123pub struct CastError(pub String);
124
125impl Display for CastError {
126    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
127        write!(f, "Cast error: {}", self.0)
128    }
129}
130
131impl Error for CastError {}
132
133impl Display for AxionError {
134    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
135        match self {
136            AxionError::MismatchedLengths { expected, found, name } => write!(
137                f,
138                "列长度不匹配: 列 '{}' 期望长度 {}，但发现长度 {}",
139                name, expected, found
140            ),
141            AxionError::DuplicateColumnName(name) => {
142                write!(f, "发现重复的列名: '{}'", name)
143            }
144            AxionError::ColumnNotFound(name) => write!(f, "未找到列: '{}'", name),
145            AxionError::TypeError { expected, found, name } => write!(
146                f,
147                "列 '{}' 类型错误: 期望 {}，发现 {:?}",
148                name, expected, found
149            ),
150            AxionError::TypeMismatch { expected, found, name } => write!(
151                f,
152                "列 '{}' 类型不匹配: 期望 {:?}，发现 {:?}",
153                name, expected, found
154            ),
155            AxionError::NoColumnsProvided => write!(f, "创建 DataFrame 时未提供任何列"),
156            AxionError::CastError(err) => write!(f, "{}", err),
157            AxionError::JoinKeyTypeError { side, name, expected, found } => write!(
158                f,
159                "{} 表的连接键列 '{}' 类型无效: 期望 {:?}，发现 {:?}",
160                side, name, expected, found
161            ),
162            AxionError::IndexOutOfBounds(index, len) => write!(
163                f,
164                "索引越界: 集合长度为 {}，但访问索引为 {}",
165                len, index
166            ),
167            AxionError::IndexOutOfRange(index, len) => write!(
168                f,
169                "索引超出范围: 集合长度为 {}，但访问索引为 {}",
170                len, index
171            ),
172            AxionError::ComputeError(msg) => write!(f, "计算错误: {}", msg),
173            AxionError::UnsupportedOperation(msg) => write!(f, "不支持的操作: {}", msg),
174            AxionError::InvalidArgument(msg) => write!(f, "无效参数: {}", msg),
175            AxionError::InternalError(msg) => write!(f, "内部错误: {}，请报告此问题", msg),
176            AxionError::CsvError(msg) => write!(f, "CSV 错误: {}", msg),
177            AxionError::IoError(msg) => write!(f, "IO 错误: {}", msg),
178            AxionError::Other(msg) => write!(f, "Axion 错误: {}", msg),
179        }
180    }
181}
182
183impl Error for AxionError {
184    fn source(&self) -> Option<&(dyn Error + 'static)> {
185        match self {
186            AxionError::CastError(err) => Some(err),
187            _ => None,
188        }
189    }
190}
191
192/// Axion 库中常用的 Result 类型别名
193/// 
194/// 简化错误处理代码，统一使用 `AxionResult<T>` 而不是完整的 `Result<T, AxionError>`。
195/// 
196/// # 示例
197/// 
198/// ```rust
199/// fn process_data() -> AxionResult<DataFrame> {
200///     // 处理逻辑
201///     Ok(dataframe)
202/// }
203/// ```
204pub type AxionResult<T> = std::result::Result<T, AxionError>;
205
206impl From<csv::Error> for AxionError {
207    fn from(err: csv::Error) -> Self {
208        AxionError::CsvError(format!("CSV 处理错误: {}", err))
209    }
210}
211
212impl From<std::string::FromUtf8Error> for AxionError {
213    fn from(err: std::string::FromUtf8Error) -> Self {
214        AxionError::IoError(format!("UTF-8 转换错误: {}", err))
215    }
216}
217
218impl From<std::io::Error> for AxionError {
219    fn from(err: std::io::Error) -> Self {
220        AxionError::IoError(err.to_string())
221    }
222}
axion_data/error.rs

axion_data/
error.rs
