dta 0.6.0

Pure Rust streaming reader and writer for Stata's DTA file format (every released version, 102-119), plus a parser and reader for Stata dictionary (.dct) files.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

use std::fs::File;
use std::io::{BufRead, BufReader};
use std::path::Path;

use super::dct_error::Result;
use super::dct_reader::DctReader;
use super::schema::Schema;

#[cfg(feature = "tokio")]
use super::async_dct_reader::AsyncDctReader;

/// Configuration for constructing a [`DctReader`] from a parsed
/// [`Schema`].
///
/// Created via [`DctReader::options`]. The schema is required at
/// construction; future configuration knobs will be added as chained
/// setters before a terminal method that produces the reader.
///
/// `DctReader::new` is intentionally crate-private so new options
/// can land later without breaking callers — always go through this
/// builder.
#[derive(Debug)]
pub struct DctReaderOptions {
    schema: Schema,
    record_warnings: bool,
}

impl DctReaderOptions {
    #[must_use]
    pub(super) fn new(schema: Schema) -> Self {
        Self {
            schema,
            record_warnings: true,
        }
    }

    /// Controls whether per-record warnings are accumulated.
    ///
    /// Defaults to `true`. Set to `false` when the caller doesn't
    /// inspect [`DctReader::warnings`](DctReader::warnings) — the
    /// reader skips warning construction entirely, leaving the
    /// internal buffer empty across reads.
    #[must_use]
    #[inline]
    pub fn record_warnings(mut self, enabled: bool) -> Self {
        self.record_warnings = enabled;
        self
    }

    /// Creates a [`DctReader`] wrapping the given buffered source.
    ///
    /// For best performance, wrap the source in a [`BufReader`]
    /// before passing it here.
    //noinspection RsSelfConvention
    #[must_use]
    #[inline]
    pub fn from_reader<R: BufRead>(self, reader: R) -> DctReader<R> {
        DctReader::new(self.schema, reader, self.record_warnings)
    }

    /// Creates a [`DctReader`] wrapping the file in a [`BufReader`].
    //noinspection RsSelfConvention
    #[must_use]
    #[inline]
    pub fn from_file(self, file: File) -> DctReader<BufReader<File>> {
        let reader = BufReader::new(file);
        self.from_reader(reader)
    }

    /// Opens the file at `path` and wraps it in a [`BufReader`].
    ///
    /// # Errors
    ///
    /// Returns an I/O error if the file cannot be opened.
    //noinspection RsSelfConvention
    pub fn from_path(self, path: impl AsRef<Path>) -> Result<DctReader<BufReader<File>>> {
        let file = File::open(path)?;
        let reader = self.from_file(file);
        Ok(reader)
    }

    /// Creates an [`AsyncDctReader`] wrapping the given async
    /// buffered source.
    ///
    /// For best performance, wrap the source in a
    /// [`tokio::io::BufReader`] before passing it here.
    //noinspection RsSelfConvention
    #[cfg(feature = "tokio")]
    #[must_use]
    #[inline]
    pub fn from_tokio_reader<R: tokio::io::AsyncBufRead + Unpin>(
        self,
        reader: R,
    ) -> AsyncDctReader<R> {
        AsyncDctReader::new(self.schema, reader, self.record_warnings)
    }

    /// Creates an [`AsyncDctReader`] wrapping the async file in a
    /// [`tokio::io::BufReader`].
    //noinspection RsSelfConvention
    #[cfg(feature = "tokio")]
    #[must_use]
    #[inline]
    pub fn from_tokio_file(
        self,
        file: tokio::fs::File,
    ) -> AsyncDctReader<tokio::io::BufReader<tokio::fs::File>> {
        let reader = tokio::io::BufReader::new(file);
        self.from_tokio_reader(reader)
    }

    /// Opens the file at `path` asynchronously and wraps it in a
    /// [`tokio::io::BufReader`].
    ///
    /// # Errors
    ///
    /// Returns an I/O error if the file cannot be opened.
    //noinspection RsSelfConvention
    #[cfg(feature = "tokio")]
    pub async fn from_tokio_path(
        self,
        path: impl AsRef<Path>,
    ) -> Result<AsyncDctReader<tokio::io::BufReader<tokio::fs::File>>> {
        let file = tokio::fs::File::open(path).await?;
        let reader = self.from_tokio_file(file);
        Ok(reader)
    }
}