Skip to main content

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}