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

//! **This software is experimental and might change a lot in future**
//!
//! This is a Rust implementation of a parser for GV100AD data sets. These data
//! sets contain information about the structure, population, area of german
//! municipalities.
//!
//! The data sets can be obtained at: https://www.destatis.de/DE/Themen/Laender-Regionen/Regionales/Gemeindeverzeichnis/_inhalt.html
//!
//! The parser was tested with this data set: https://www.destatis.de/DE/Themen/Laender-Regionen/Regionales/Gemeindeverzeichnis/Administrativ/Archiv/GV100ADQ/GV100AD3004.html
//!
//! The ZIP files contain a text file `GV100AD_DDMMYY.txt` that contains the
//! data set, and a PDF file describing the format.
//!
//! # Example
//!
//! This example lists all municipalities of the state *Saarland* with
//! population:
//!
//! ```rust
//! use gv100ad::{
//!     model::{
//!         gemeinde::GemeindeDaten,
//!         kreis::KreisDaten,
//!         land::{LandDaten, LandSchluessel},
//!     },
//!     Database,
//! };
//!
//! // Open the database. Refer to the `README.md` file for the source of the datasets.
//! let db = Database::from_path("GV100AD3004/GV100AD_300421.txt").unwrap();
//!
//! // Parse a key for the state of Saarland
//! let schluessel = "10".parse::<LandSchluessel>().unwrap();
//!
//! // Get the record for the state of Saarland
//! let land = db.get::<_, LandDaten>(schluessel).unwrap();
//! println!("{}:", land.name);
//!
//! // Iterate over the districts (Kreise) in Saarland
//! for kreis in db.children::<_, KreisDaten>(schluessel) {
//!     println!("  {}:", kreis.name);
//!
//!     // Iterate over the municipalities (Gemeinde) in the district (Kreis)
//!     for gemeinde in db.children::<_, GemeindeDaten>(kreis.schluessel) {
//!         println!(
//!             "    {}: {} residents",
//!             gemeinde.name, gemeinde.population_total
//!         );
//!     }
//! }
//!
//! // Get the sum of the population of all municipalities in Saarland
//! let total_population: u64 = db.children::<_, GemeindeDaten>(schluessel)
//!     .map(|gemeinde| gemeinde.population_total)
//!     .sum();
//! println!("Total population of {}: {}", land.name, total_population);
//! ```
//!
//! ## Language
//!
//! The primary language used for the software is English, thus most of
//! documentation and code is in English. Nevertheless a lot of terms are
//! inherently German, and a lot of identifiers in the software use these terms.
//! Here are a few translations:
//!
//!  * Land: State (also called Bundesland)
//!  * Regierungsbezirk: Government district
//!  * Kreis: District
//!  * Gemeinde: Municipality (more literally "community")
//!  * Verband: Association
//!  * Schluessel: Key
//!  * Textkennzeichen: Textual (it's actually a number) identifier for type of
//!    Kreis, Gemeindeverband or Gemeinde.
//!  * Daten: data, in context e.g. "Landdaten" means "state data" or "state
//!    record".
//!
//!  If you think a translation is incorrect or missing, please open an issue.

pub mod db;
pub mod error;
pub mod model;
pub mod parser;

pub use db::Database;
pub use parser::Parser;