Skip to main content

datasus_core/
lib.rs

1//! Reader for DATASUS `.dbc` files (and plain `.dbf`).
2//!
3//! A DBC file is a dBase III header followed by the record area compressed
4//! with the PKWare Data Compression Library.  This crate decompresses it
5//! ([`blast`]), recognises the container layout ([`decode`]) and parses the
6//! records into typed columns ([`Table`]).
7//!
8//! It is a port of the C reader of the [datasusr] R package and is meant to
9//! produce the same values for the same options.  It has no dependencies so
10//! it can be embedded anywhere (R packages, Python wheels, CLIs).
11//!
12//! ```no_run
13//! use datasus_core::{open, ReadOptions};
14//!
15//! let table = open("RDPE2401.dbc", &ReadOptions::default())?;
16//! println!("{} rows x {} columns", table.n_rows(), table.n_cols());
17//! let columns = table.collect();
18//! # Ok::<(), datasus_core::Error>(())
19//! ```
20//!
21//! [datasusr]: https://github.com/StrategicProjects/datasusr
22
23pub mod blast;
24mod container;
25mod dbf;
26
27use std::fmt;
28use std::path::Path;
29
30pub use container::{decode, decode_with_limit, Container, DbfData, DEFAULT_MAX_DECOMPRESSED};
31pub use dbf::{
32    repair_names, ColType, ColumnData, Cursor, Encoding, Field, ReadOptions, Sink, Table,
33};
34
35#[derive(Debug)]
36pub enum Error {
37    Io(std::io::Error),
38    /// PKWare DCL decompression failed; `code` is the `blast()` return code.
39    Blast { code: i32, record_area: bool },
40    /// The file would decompress to more than the allowed size.
41    TooLarge { max_bytes: u64 },
42    /// Decompression worked but the result is not a DBF file.
43    NotDbf,
44    /// The DBF header is invalid.
45    Header(String),
46}
47
48impl fmt::Display for Error {
49    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
50        match self {
51            Error::Io(e) => write!(f, "{e}"),
52            Error::Blast { code, record_area: true } => {
53                write!(f, "Failed to decompress DBC record area with blast(); code={code}")
54            }
55            Error::Blast { code, record_area: false } => {
56                write!(f, "Failed to decompress DBC with blast(); code={code}")
57            }
58            Error::TooLarge { max_bytes } => {
59                write!(f, "Decompressed data exceeds the limit of {max_bytes} bytes.")
60            }
61            Error::NotDbf => f.write_str(
62                "Decompression succeeded, but output does not look like a valid DBF file.",
63            ),
64            Error::Header(msg) => f.write_str(msg),
65        }
66    }
67}
68
69impl std::error::Error for Error {
70    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
71        match self {
72            Error::Io(e) => Some(e),
73            _ => None,
74        }
75    }
76}
77
78impl From<std::io::Error> for Error {
79    fn from(e: std::io::Error) -> Self {
80        Error::Io(e)
81    }
82}
83
84/// Read and decode a `.dbc`/`.dbf` file and plan how to read it.
85pub fn open(path: impl AsRef<Path>, opts: &ReadOptions) -> Result<Table, Error> {
86    from_bytes(std::fs::read(path)?, opts)
87}
88
89/// Same as [`open`], for a file already in memory.
90pub fn from_bytes(bytes: Vec<u8>, opts: &ReadOptions) -> Result<Table, Error> {
91    Table::new(decode(bytes)?, opts)
92}