arscode 0.2.0

Working with the German Amtlicher Regionalschlüssel (ARS): parse, validate and manipulate ARS codes.
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

//! ARS - Amtlicher Regionalschlüssel (German Regional Classification Key)
//!
//! This crate provides functionality for working with the **Amtlicher Regionalschlüssel (ARS)**,
//! a 12-digit hierarchical identification system used in Germany to uniquely classify administrative
//! regions from country level down to individual municipalities.
//!
//! # Background
//!
//! The ARS (originally called Regionalschlüssel or RS) was introduced in 1993/1994 as an extension
//! to the 8-digit Amtlicher Gemeindeschlüssel (AGS - Official Municipality Key). The ARS integrates
//! the AGS while adding four additional digits for encoding administrative associations (Gemeindeverbände).
//!
//! For detailed information, see:
//! [Amtlicher Gemeindeschlüssel - Regionalschlüssel (Wikipedia)](https://de.wikipedia.org/wiki/Amtlicher_Gemeindeschl%C3%BCssel#Regionalschl%C3%BCssel)
//!
//! # Structure
//!
//! The 12-digit ARS code is composed of the following components:
//!
//! ```text
//! ┌─ Positions 1-2:  Federal state (Bundesland)        [0-16]
//! │ ┌─ Position 3:   District (Regierungsbezirk)       [0-9]
//! │ │ ┌─ Positions 4-5:  County (Landkreis)            [0-99]
//! │ │ │ ┌─ Positions 6-7:  Admin Association V1        [0-99]
//! │ │ │ │ ┌─ Positions 8-9:  Admin Association V2      [0-99]
//! │ │ │ │ │ ┌─ Positions 10-12: Municipality (Gemeinde) [0-999]
//! │ │ │ │ │ │
//! 1 2 3 4 5 6 7 8 9 0 1 2
//! ```
//!
//! # Hierarchical Levels
//!
//! The ARS code represents a hierarchical administrative structure:
//!
//! - **0: Country** (Deutschland) - All zeros
//! - **1: State** (Bundesland) - Federal state only
//! - **2: District** (Regierungsbezirk) - Administrative district (where applicable)
//! - **3: County** (Landkreis) - County or independent city
//! - **4: Admin Association** (Verwaltungsgemeinschaft) - Municipal association
//! - **5: Municipality** (Gemeinde) - Individual municipality
//!
//! # Examples
//!
//! ```
//! use arscode::{ARSCode, ARSLevel, FederalState};
//!
//! // Create an ARS code for Hamburg (state level)
//! let hamburg = ARSCode::new(2, 0, 0, 0, 0, 0).unwrap();
//! assert_eq!(hamburg.level(), ARSLevel::STATE);
//! assert_eq!(FederalState::from(hamburg), FederalState::Hamburg);
//!
//! // Create an ARS code for a municipality
//! let municipality = ARSCode::new(5, 3, 15, 8, 4, 42).unwrap();
//! println!("{}", municipality); // Prints: 053158042042
//! assert_eq!(municipality.level(), ARSLevel::MUNICIPALITY);
//!
//! // Parse from string
//! let ars: ARSCode = "053150804042".try_into().unwrap();
//! assert_eq!(ars, municipality);
//!
//! // Navigate hierarchy
//! let parent = municipality.parent().unwrap(); // Administrative association
//! let grandparent = parent.parent().unwrap();   // County
//! ```
//!
//! # Federal States
//!
//! The 16 federal states are numbered 1-16 (0 represents Germany as a whole):
//!
//! 1. Schleswig-Holstein
//! 2. Hamburg
//! 3. Lower Saxony (Niedersachsen)
//! 4. Bremen
//! 5. North Rhine-Westphalia (Nordrhein-Westfalen)
//! 6. Hesse (Hessen)
//! 7. Rhineland-Palatinate (Rheinland-Pfalz)
//! 8. Baden-Württemberg
//! 9. Bavaria (Bayern)
//! 10. Saarland
//! 11. Berlin
//! 12. Brandenburg
//! 13. Mecklenburg-Vorpommern
//! 14. Saxony (Sachsen)
//! 15. Saxony-Anhalt (Sachsen-Anhalt)
//! 16. Thuringia (Thüringen)
//!
//! # Use Cases
//!
//! - Statistical analysis and reporting
//! - Administrative region identification
//! - Data aggregation across hierarchical levels
//! - Finding common administrative parents
//! - Validating region identifiers
//!
//! # Serde Support
//!
//! When the `serde` feature is enabled, `ARSCode` can be serialized and deserialized.
//!
//! # Localization
//!
//! The `lang_en` and `lang_de` features control the language of displayed names:
//! - `lang_en`: English names for federal states
//! - `lang_de`: German names for federal states (default)

mod arscode;
mod arslevel;
mod error;
mod state;

pub use arscode::ARSCode;
#[cfg(feature = "serde")]
pub use arscode::arscode_serde;
pub use arslevel::{ARSLevel, ARSLevelError};
pub use error::ARSCodeError;
pub use state::FederalState;