1use serde::de::DeserializeOwned;
2
3use crate::endpoints;
4use crate::types::TEN_YEARS_MS;
5use crate::{
6 AShareCode, BalanceSheetsData, CashFlowStatementsData, Client, Error, FinancialIndicatorsData,
7 FinancialPeriod, FinancialReport, IncomeStatementsData, Response, UnixMillis, ValidationError,
8};
9
10#[derive(Debug, Clone, Copy, PartialEq, Eq)]
12pub struct FinancialRange(FinancialRangeKind);
13
14#[derive(Debug, Clone, Copy, PartialEq, Eq)]
15enum FinancialRangeKind {
16 Recent { limit: u8 },
17 Between { start: UnixMillis, end: UnixMillis },
18}
19
20impl FinancialRange {
21 pub const fn recent(limit: u8) -> Result<Self, ValidationError> {
22 if limit == 0 || limit > 20 {
23 return Err(ValidationError::new("limit", "must be in the range 1..=20"));
24 }
25 Ok(Self(FinancialRangeKind::Recent { limit }))
26 }
27
28 pub fn between(start: i64, end: i64) -> Result<Self, ValidationError> {
29 let start = UnixMillis::new(start)?;
30 let end = UnixMillis::new(end)?;
31 if end.get() < start.get() {
32 return Err(ValidationError::new(
33 "end",
34 "must not be earlier than start",
35 ));
36 }
37 if end.get() - start.get() > TEN_YEARS_MS {
38 return Err(ValidationError::new(
39 "end",
40 "requested time window exceeds ten years",
41 ));
42 }
43 Ok(Self(FinancialRangeKind::Between { start, end }))
44 }
45}
46
47impl Client {
48 #[doc = concat!(
52 "```no_run\n",
53 include_str!("../../examples/financials_income_statements.rs"),
54 "\n```"
55 )]
56 pub async fn financials_income_statements(
57 &self,
58 thscode: impl AsRef<str> + Send,
59 period: FinancialPeriod,
60 range: FinancialRange,
61 ) -> Result<Response<IncomeStatementsData>, Error> {
62 self.financial_statements(endpoints::INCOME_STATEMENTS, thscode, period, range)
63 .await
64 }
65
66 #[doc = concat!(
70 "```no_run\n",
71 include_str!("../../examples/financials_balance_sheets.rs"),
72 "\n```"
73 )]
74 pub async fn financials_balance_sheets(
75 &self,
76 thscode: impl AsRef<str> + Send,
77 period: FinancialPeriod,
78 range: FinancialRange,
79 ) -> Result<Response<BalanceSheetsData>, Error> {
80 self.financial_statements(endpoints::BALANCE_SHEETS, thscode, period, range)
81 .await
82 }
83
84 #[doc = concat!(
88 "```no_run\n",
89 include_str!("../../examples/financials_cash_flow_statements.rs"),
90 "\n```"
91 )]
92 pub async fn financials_cash_flow_statements(
93 &self,
94 thscode: impl AsRef<str> + Send,
95 period: FinancialPeriod,
96 range: FinancialRange,
97 ) -> Result<Response<CashFlowStatementsData>, Error> {
98 self.financial_statements(endpoints::CASH_FLOW_STATEMENTS, thscode, period, range)
99 .await
100 }
101
102 async fn financial_statements<T: DeserializeOwned>(
103 &self,
104 path: &str,
105 thscode: impl AsRef<str> + Send,
106 period: FinancialPeriod,
107 range: FinancialRange,
108 ) -> Result<Response<T>, Error> {
109 let thscode = AShareCode::new(thscode)?;
110 let mut query = vec![
111 ("thscode", thscode.into_string()),
112 ("period", period.to_string()),
113 ];
114 match range.0 {
115 FinancialRangeKind::Recent { limit } => {
116 query.push(("limit", limit.to_string()));
117 }
118 FinancialRangeKind::Between { start, end } => {
119 query.push(("start", start.to_string()));
120 query.push(("end", end.to_string()));
121 }
122 }
123 self.get(path, &query).await
124 }
125
126 #[doc = concat!(
130 "```no_run\n",
131 include_str!("../../examples/financials_indicators.rs"),
132 "\n```"
133 )]
134 pub async fn financials_indicators(
135 &self,
136 thscode: impl AsRef<str> + Send,
137 report: impl AsRef<str> + Send,
138 ) -> Result<Response<FinancialIndicatorsData>, Error> {
139 let thscode = AShareCode::new(thscode)?;
140 let report = FinancialReport::parse(report.as_ref())?;
141 let query = [("thscode", thscode.as_str()), ("report", report.as_str())];
142 self.get(endpoints::FINANCIAL_INDICATORS, &query).await
143 }
144}
145
146#[cfg(test)]
147mod tests {
148 use super::FinancialRange;
149
150 #[test]
151 fn financial_range_rejects_invalid_limits_and_reversed_windows() {
152 assert!(FinancialRange::recent(1).is_ok());
153 assert!(FinancialRange::recent(20).is_ok());
154 assert!(FinancialRange::recent(0).is_err());
155 assert!(FinancialRange::recent(21).is_err());
156
157 assert!(FinancialRange::between(1_700_000_000_000, 1_600_000_000_000).is_err());
158 }
159
160 #[test]
161 fn financial_range_rejects_windows_over_ten_years_at_construction() {
162 assert!(FinancialRange::between(1_000_000_000_000, 1_315_576_000_001).is_err());
163 }
164}