0.27.0

This release includes significant API changes. See UPGRADING.md
for migration guidance.

Breaking Changes

Lookup API

• lookup() now returns LookupResult instead of Option<T>. The new API
  enables lazy decoding - data is only deserialized when explicitly requested.
• lookup_prefix() has been removed. Use lookup(ip)?.network() instead.

Iteration API

• within() now requires a second WithinOptions parameter. Use
  Default::default() for the previous behavior.
• Within iterator now yields LookupResult instead of WithinItem<T>.

GeoIP2 Structs

• The names fields now use a Names struct instead of BTreeMap<&str, &str>.
  Access names directly via language fields (e.g., names.english).
• Nested struct fields (city, country, location, etc.) are now
  non-optional with Default, simplifying access patterns.
• Removed is_anonymous_proxy and is_satellite_provider from Traits.
  These fields are no longer present in MaxMind databases.

Error Types

• InvalidDatabase and Decoding variants now use structured fields instead
  of a single string. Pattern matching must be updated.
• New InvalidInput variant for user input errors (e.g., IPv6 lookup in
  IPv4-only database).

Memory Mapping

• Reader::open_mmap is now unsafe. The caller must ensure the database
  file is not modified or truncated while the Reader exists. This fixes a
  soundness issue. Reported by paolobarbolini. GitHub #86.

Added

• LookupResult type with lazy decoding support:
  • has_data() - Check if data exists for this IP
  • network() - Get the network containing the IP
  • offset() - Get data offset for caching/deduplication
  • decode() - Deserialize full record
  • decode_path() - Selectively decode specific fields by path
• PathElement enum and path! macro for navigating nested structures.
• WithinOptions to control network iteration behavior:
  • include_aliased_networks() - Include IPv4 via IPv6 aliases
  • include_networks_without_data() - Include networks without data records
  • skip_empty_values() - Skip empty maps/arrays
• networks() method for iterating over all networks in the database.
• verify() method for comprehensive database validation.
• Metadata::build_time() to convert build_epoch to SystemTime.
• PartialEq and Eq implementations for Metadata and WithinOptions.

Changed

• Error messages now include byte offsets when available.
• decode_path() errors include path context showing where navigation failed.
• Added recursion depth limit (512) matching libmaxminddb and Go reader.
• Serde deserializer improvements: size hints, is_human_readable() returns
  false, deserialize_ignored_any, and deserialize_enum support.
• MaxMindDbError is now #[non_exhaustive].

0.26.0

• BREAKING CHANGE: The lookup and lookup_prefix methods now return
  Ok(None) or Ok((None, prefix_len)) respectively when an IP address is
  valid but not found in the database (or has no associated data record),
  instead of returning an Err(MaxMindDbError::AddressNotFoundError).
  Code previously matching on AddressNotFoundError must be updated to
  handle the Ok(None) / Ok((None, prefix_len)) variants.
• BREAKING CHANGE: The MaxMindDBError enum has been renamed
  MaxMindDbError and variants have been renamed and refactored. For
  example, IoError is now Io, InvalidDatabaseError is now
  InvalidDatabase, DecodingError is now Decoding,
  InvalidNetworkError is now InvalidNetwork. The MapError variant has
  been replaced by Mmap (under the mmap feature flag). Code explicitly
  matching on the old variant names must be updated.
• BREAKING CHANGE: MaxMindDbError no longer implements PartialEq.
  This is because underlying error types like std::io::Error (now
  wrapped by the Io and Mmap variants) do not implement PartialEq.
  Code comparing errors directly using == or assert_eq! must be
  updated, typically by using matches! or by matching on the error
  kind and potentially its contents.
• Refactored MaxMindDbError handling using the thiserror crate.
  Variants like Io, Mmap, and InvalidNetwork now directly wrap
  the underlying error types (std::io::Error, ipnetwork::IpNetworkError).
• Errors wrapping underlying types (Io, Mmap, InvalidNetwork) now
  correctly implement std::error::Error::source(), allowing inspection
  of the original cause.
• The Display implementation for MaxMindDbError has been refined to
  generally show only the specific error details, often including the
  message from the source error, rather than prefixing with the variant
  name.
• lookup_prefix now returns the prefix length of the entry even when the
  value is not found.
• Fixed an internal bounds checking error when resolving data pointers.
  The previous logic could cause a panic on a corrupt database.

0.25.0

• Serde will now skip serialization of the GeoIP2 struct fields
  when Option is none. Pull request by Stefan Sundin. GitHub #79.
• Serialize and Clone were added to the Metadata struct. Pull
  request by Stefan Sundin. GitHub #80.
• Added feature to use simdutf8 as a faster alternative when
  unsafe-str-decode is too risky. Pull request by Jakub Onderka.
  GitHub #88.
• Minor internal refactoring and performance improvements.

0.24.0

• Added the is_anycast field to the Traits struct. Pull request
  by Skye. GitHub #73.

0.23.0

• Added lookup_prefix to return the prefix length for the network
  associated with the IP address. Pull request by Marek Vavruša.
  GitHub #26.

0.22.0

• A within method has been added to the reader to allow iterating
  over all records in the database. Pull request by Ross McFarland.
  Github #50.
• Database structs in maxminddb::geoip2 have been updated. Most
  noticeably, an Enterprise struct has been added and the model
  module has been replaced by city and country modules. Also,
  several missing fields have been added.
• Mmap is now re-exported for convenience. Pull request by zhuhaow.
  GitHub #54.
• Upgraded memmap2 dependency.