libmaxminddb_rs/
lib.rs

1#![forbid(unsafe_op_in_unsafe_fn)]
2#![warn(missing_docs)]
3//! Read and write MaxMind DB (MMDB) v2 files in Rust.
4//!
5//! The crate implements the binary format independently. [`Reader`] opens an
6//! owned file, a borrowed byte slice, or an explicitly unsafe memory mapping;
7//! [`Writer`] builds MMDB files from IP networks and values. Search-tree
8//! traversal, data decoding, metadata, and serialization live in separate
9//! modules. The public entry points are re-exported at the crate root.
10//!
11//! Add `libmaxminddb-rs = "0.1"` to the `[dependencies]` section of `Cargo.toml`.
12//! See the repository README for benchmark methodology and complete examples.
13//!
14//! # Read a record
15//!
16//! ```rust
17//! # #[cfg(all(feature = "reader", feature = "writer"))]
18//! # mod example {
19//! use libmaxminddb_rs::{Error, MetadataBuilder, Reader, Value, Writer};
20//! use std::net::IpAddr;
21//! use std::collections::BTreeMap;
22//!
23//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
24//! let metadata = MetadataBuilder::new().ip_version(4).build()?;
25//! let mut writer = Writer::with_metadata(metadata);
26//! writer.insert_value("198.51.100.0/24".parse()?,
27//!     Value::Map(BTreeMap::from([("asn".into(), Value::Uint32(64512))])))?;
28//! let bytes = writer.finish()?;
29//! let reader = Reader::from_bytes(&bytes)?;
30//! let ip: IpAddr = "198.51.100.7".parse()?;
31//! let value = reader.lookup_value(ip)?;
32//! assert_eq!(value.get("asn").is_some(), true);
33//! assert!(matches!(reader.lookup_value("203.0.113.7".parse()?), Err(Error::NotFound)));
34//! # Ok(())
35//! # }
36//! # }
37//! ```
38//!
39//! [`Reader::lookup_borrowed`] decodes directly into `#[derive(MmdbDecode)]`
40//! types. `&str` and `&[u8]` fields borrow the underlying MMDB bytes; maps and
41//! arrays materialized as [`ValueRef`] allocate their container vectors.
42//! `lookup_borrowed_map` can project a large record into a small result. A miss
43//! returns [`Error::NotFound`] from result-based methods, while
44//! [`Reader::lookup_borrowed_opt`] returns `None` for both misses and decode
45//! failures.
46//!
47//! # Cargo features
48//!
49//! - `reader`: search and decode MMDB files, including mmap support.
50//! - `writer`: serialize networks and values, with configurable merge behavior.
51//! - `derive`: derive [`MmdbDecode`], [`MmdbEncode`], and [`MmdbRecord`].
52//! - `simd`: enable architecture-specific ASCII scanning where available.
53//!
54//! The reader always builds its cache-aligned fast tree and accelerator tables
55//! during open for every valid record size. This adds to open time and memory
56//! use, while keeping index construction out of the lookup path.
57//!
58//! All four features are enabled by default. A reader-only build can use
59//! `default-features = false, features = ["reader"]`. Memory-mapped files
60//! must not be changed or truncated while borrowed by a reader; opening one
61//! therefore requires an explicit `unsafe` call.
62
63extern crate self as libmaxminddb_rs;
64
65mod error;
66mod metadata;
67mod network;
68mod traits;
69mod value;
70
71mod decoder;
72#[cfg(feature = "writer")]
73mod encoder;
74#[cfg(feature = "reader")]
75pub mod reader;
76#[cfg(feature = "writer")]
77pub mod writer;
78
79pub use error::{Error, Result};
80pub use metadata::{Metadata, MetadataBuilder};
81pub use network::IpNetwork;
82pub use traits::{DecodeField, EncodeField, MmdbDecode, MmdbEncode, MmdbRecord};
83pub use value::{Value, ValueRef};
84
85#[cfg(feature = "reader")]
86pub use reader::Reader;
87#[cfg(feature = "writer")]
88pub use writer::{MergeStrategy, Writer};
89
90#[cfg(feature = "derive")]
91pub use libmaxminddb_rs_derive::{MmdbDecode, MmdbEncode, MmdbRecord};
92
93/// Items referenced by code generated with `#[derive(MmdbDecode)]`.
94///
95/// Not part of the stable API: names and signatures may change in any release.
96#[doc(hidden)]
97pub mod __private {
98    pub use crate::decoder::{Container, RawDecoder};
99}
libmaxminddb_rs/lib.rs

libmaxminddb_rs/
lib.rs
