ixa_fips/lib.rs
1//! # FIPS Geographic Region Code Library
2//!
3//! FIPS geographic region codes are used to represent hierarchical geographic regions from the state level down to the
4//! "block" level. They are augmented in some synthetic population datasets with additional ID numbers for households,
5//! workplaces, and schools. This library provides types to represent FIPS geographic region codes (and "code fragments"),
6//! efficient representations, and utilities to convert to and from textual representations ([`crate::parser`]).
7//!
8//! The [`crate::aspr`] module provides types for representing records from the ASPR synthetic population dataset, and the
9//! [`crate::aspr::parser`] submodule provides parsers for textual representations of ASPR records.
10//!
11//! The `aspr_archive` feature (enabled by default) enables the [`crate::aspr::archive`] module, which provides a reader
12//! for ASPR synthetic population data files, including files that are within a zip archive.
13
14#![allow(dead_code)]
15
16mod errors;
17pub mod fips_code;
18pub mod parser;
19pub mod states;
20
21pub use errors::FIPSError;
22pub use fips_code::{ExpandedFIPSCode, FIPSCode};
23pub use states::USState;
24
25// Convenience constants
26const FOUR_BIT_MASK: u8 = 15; // 2^4-1
27const SEVEN_BIT_MASK: u8 = 127; // 2^7-1
28const NINE_BIT_MASK: u16 = 511; // 2^9-1
29const TEN_BIT_MASK: u16 = 1023; // 2^10-1
30const FOURTEEN_BIT_MASK: u16 = 16_383; // 2^14-1
31const TWENTY_BIT_MASK: u32 = 1_048_575; // 2^20-1
32
33// Offsets of the bit fields in the encoded FIPS code
34const STATE_OFFSET: usize = 57;
35const COUNTY_OFFSET: usize = 47;
36const TRACT_OFFSET: usize = 27;
37const CATEGORY_OFFSET: usize = 23;
38const ID_OFFSET: usize = 9;
39// const DATA_OFFSET: usize = 0;
40
41// Numeric types used for code fragments. By convention, zero values are reserved for "no data."
42
43/// The numeric type used for the state code fragment; `u8`
44pub type StateCode = u8;
45/// The numeric type used for the county code fragment; `u16`
46pub type CountyCode = u16;
47/// The numeric type used for the tract code fragment; `u32`
48pub type TractCode = u32;
49/// The numeric type used for the setting category code fragment; `u8`
50pub type SettingCategoryCode = u8;
51/// The numeric type used for the id code fragment; `u16`
52pub type IdCode = u16;
53/// The numeric type used for the data code fragment; `u16`
54pub type DataCode = u16;