realdentalcosts_data/lib.rs
1//! This crate embeds the 2026 United States dental cost index compiled by the
2//! [Real Dental Costs Data & Research Team](https://realdentalcosts.com/en/us-dental-cost-index/)
3//! — an estimated single dental-implant price, a restorative cost index, a cost-of-living
4//! index and a deprecated affordability score for the 50 states plus the District of
5//! Columbia — and exposes a small, zero-dependency Rust API to query it. The source CSV is
6//! embedded in the binary via `include_str!` and parsed on demand by a tiny internal parser.
7//!
8//! # Correction (version 0.1.1, October 2026)
9//!
10//! Version 0.1.0 described the implant series as observed prices. That was wrong. The
11//! `implant_avg_usd` column is an **editorial estimate, edition 2026.1, not collected
12//! prices**: the state ranking was validated against an independent price series (ASQ360,
13//! Spearman 0.945), the dollar levels were not verified. The values themselves are
14//! unchanged in this release. Details:
15//! [data corrections notice](https://realdentalcosts.com/en/data-corrections/).
16//!
17//! The `affordability_score` was retired from realdentalcosts.com in October 2026 because
18//! one of its components has no documented source. The field stays in [`StateRow`] so that
19//! existing code keeps compiling; do not use it for new work.
20//!
21//! # Where the numbers come from
22//!
23//! The `implant_avg_usd` column comes from the Real Dental Costs dataset archived under DOI
24//! [10.5281/zenodo.20531728](https://doi.org/10.5281/zenodo.20531728) (concept DOI). The
25//! `restorative_index` is a base-100 index derived from that same estimate; the dataset also
26//! carries a state `cost_of_living_index` (US average = 100). The full methodology and
27//! copy-paste citations are on the
28//! [methodology page](https://realdentalcosts.com/en/methodology/) and the
29//! [cite-this-data page](https://realdentalcosts.com/en/cite-this-data/).
30//!
31//! This is pricing and market-research data, **not** medical advice.
32//!
33//! # Going further
34//!
35//! This crate deliberately ships raw data with no simulation logic. The same dataset powers
36//! the interactive [US Dental Cost Index](https://realdentalcosts.com/en/us-dental-cost-index/)
37//! and the annual
38//! [State of US Dental Costs 2026 report](https://realdentalcosts.com/en/state-of-us-dental-costs-2026/)
39//! on realdentalcosts.com. The national average of the estimate in this edition is $4,507.
40//!
41//! # Example
42//!
43//! ```rust
44//! use realdentalcosts_data::{states, state, cheapest_states, priciest_states};
45//!
46//! // Alabama: lowest estimate for a single implant; California: highest.
47//! let al = state("AL").unwrap();
48//! assert_eq!(al.rank, 1);
49//! assert_eq!(al.implant_avg_usd, 3759);
50//!
51//! let ca = state("CA").unwrap();
52//! assert_eq!(ca.rank, 51);
53//! assert_eq!(ca.implant_avg_usd, 5733);
54//!
55//! // All 51 jurisdictions, and the ends of the ranking.
56//! assert_eq!(states().len(), 51);
57//! assert_eq!(cheapest_states(1)[0].state_code, "AL");
58//! assert_eq!(priciest_states(1)[0].state_code, "CA");
59//! ```
60
61/// One state-level row of the 2026 US dental cost index (50 states + DC).
62#[derive(Debug, Clone, PartialEq)]
63pub struct StateRow {
64 /// National rank by estimated implant price (1 = lowest, 51 = highest).
65 pub rank: u32,
66 /// Full state name, e.g. `"California"`.
67 pub state_name: &'static str,
68 /// Two-letter USPS code, e.g. `"CA"`.
69 pub state_code: &'static str,
70 /// Estimated price of a single dental implant in the state, US dollars: editorial
71 /// estimate, edition 2026.1, not collected prices (see the crate-level correction note).
72 pub implant_avg_usd: u32,
73 /// Restorative cost index, base 100 (derived from the implant estimate).
74 pub restorative_index: u32,
75 /// Cost-of-living index (US average = 100).
76 pub cost_of_living_index: f64,
77 /// Deprecated: affordability score, 0–100, retired from realdentalcosts.com in
78 /// October 2026 (one component has no documented source). Kept for compatibility only.
79 pub affordability_score: u32,
80}
81
82const STATE_CSV: &str = include_str!("../data/us-dental-cost-index-2026.csv");
83
84fn split_line(line: &'static str) -> Vec<&'static str> {
85 // The embedded CSV has no quoted, comma-bearing fields; a plain split is sufficient,
86 // but we keep a quote-aware parser for robustness.
87 let mut out = Vec::new();
88 let mut rest = line;
89 while !rest.is_empty() {
90 if let Some(stripped) = rest.strip_prefix('"') {
91 let end = stripped.find('"').unwrap_or(stripped.len());
92 out.push(&stripped[..end]);
93 rest = stripped[end..].trim_start_matches('"').trim_start_matches(',');
94 } else {
95 match rest.find(',') {
96 Some(i) => {
97 out.push(&rest[..i]);
98 rest = &rest[i + 1..];
99 }
100 None => {
101 out.push(rest);
102 rest = "";
103 }
104 }
105 }
106 }
107 out
108}
109
110/// All 51 state-level rows (50 states + DC), in CSV order (ascending implant price).
111pub fn states() -> Vec<StateRow> {
112 STATE_CSV
113 .lines()
114 .skip(1)
115 .filter(|l| !l.trim().is_empty())
116 .map(|l| {
117 let f = split_line(l);
118 StateRow {
119 rank: f[0].parse().unwrap(),
120 state_name: f[1],
121 state_code: f[2],
122 implant_avg_usd: f[3].parse().unwrap(),
123 restorative_index: f[4].parse().unwrap(),
124 cost_of_living_index: f[5].parse().unwrap(),
125 affordability_score: f[6].parse().unwrap(),
126 }
127 })
128 .collect()
129}
130
131/// Look up one state by its two-letter code (case-insensitive). `None` if unknown.
132pub fn state(code: &str) -> Option<StateRow> {
133 let code = code.to_ascii_uppercase();
134 states().into_iter().find(|s| s.state_code == code)
135}
136
137/// The `n` states with the lowest implant estimate, ascending (editorial estimate, not
138/// collected prices).
139pub fn cheapest_states(n: usize) -> Vec<StateRow> {
140 let mut all = states();
141 all.sort_by(|a, b| a.implant_avg_usd.cmp(&b.implant_avg_usd));
142 all.truncate(n);
143 all
144}
145
146/// The `n` states with the highest implant estimate, descending (editorial estimate, not
147/// collected prices).
148pub fn priciest_states(n: usize) -> Vec<StateRow> {
149 let mut all = states();
150 all.sort_by(|a, b| b.implant_avg_usd.cmp(&a.implant_avg_usd));
151 all.truncate(n);
152 all
153}
154
155/// The `n` states with the highest affordability score, descending.
156#[deprecated(
157 since = "0.1.1",
158 note = "the affordability score was retired in October 2026: one component has no documented source"
159)]
160pub fn most_affordable_states(n: usize) -> Vec<StateRow> {
161 let mut all = states();
162 all.sort_by(|a, b| b.affordability_score.cmp(&a.affordability_score));
163 all.truncate(n);
164 all
165}
166
167#[cfg(test)]
168mod tests {
169 use super::*;
170
171 #[test]
172 fn fifty_one_jurisdictions() {
173 assert_eq!(states().len(), 51);
174 }
175
176 #[test]
177 fn alabama_floor_california_ceiling() {
178 let al = state("al").unwrap();
179 assert_eq!(al.rank, 1);
180 assert_eq!(al.implant_avg_usd, 3759);
181 assert_eq!(al.restorative_index, 83);
182
183 let ca = state("CA").unwrap();
184 assert_eq!(ca.rank, 51);
185 assert_eq!(ca.implant_avg_usd, 5733);
186 assert_eq!(ca.cost_of_living_index, 137.6);
187
188 assert_eq!(cheapest_states(1)[0].state_code, "AL");
189 assert_eq!(priciest_states(1)[0].state_code, "CA");
190 }
191
192 #[test]
193 #[allow(deprecated)]
194 fn ranking_is_monotonic() {
195 let all = states();
196 for w in all.windows(2) {
197 assert!(w[0].implant_avg_usd <= w[1].implant_avg_usd);
198 }
199 assert!(most_affordable_states(1)[0].affordability_score >= 70);
200 }
201}