Add SkipEmptyValues option for Networks iteration

Add SkipEmptyValues() NetworksOption that skips networks whose data is
an empty map or empty array. This is useful for databases that store
empty maps or arrays for records without meaningful data, allowing
iteration over only records with actual content.

The implementation adds IsEmptyValueAt() method to ReflectionDecoder
for efficient empty value detection without modifying decoder state.
Includes comprehensive tests and examples using GeoIP2-Anonymous-IP
test database which contains 522 empty maps out of 529 networks.

Also improves linter configuration by disabling lll since golines
handles line length management, and configures errcheck to exclude
Reader.Close in tests.

Closes #172.

Author: oschwald

.golangci.yml

@@ -19,6 +19,7 @@ linters:
     - gosmopolitan
     - inamedparam
     - interfacebloat
+    - lll
     - mnd
     - nlreturn
     - noinlineerr
@@ -31,6 +32,9 @@ linters:
     - wsl
     - wsl_v5
   settings:
+    errcheck:
+      exclude-functions:
+        - (*github.com/oschwald/maxminddb-golang/v2.Reader).Close
     errorlint:
       errorf: true
       asserts: true

CHANGELOG.md

@@ -10,6 +10,10 @@
   databases.
 - Added validation for invalid prefixes in `NetworksWithin` to prevent
   unexpected behavior with malformed input.
+- Added `SkipEmptyValues()` option for `Networks` and `NetworksWithin` to skip
+  networks whose data is an empty map or empty array. This is useful for
+  databases that store empty maps or arrays for records without meaningful
+  data. GitHub #172.
 
 ## 2.0.0-beta.8 - 2025-07-15
 

example_test.go

@@ -15,7 +15,7 @@ func ExampleReader_Lookup_struct() {
 	if err != nil {
 		log.Fatal(err)
 	}
-	defer db.Close() //nolint:errcheck // error doesn't matter
+	defer db.Close()
 
 	addr := netip.MustParseAddr("81.2.69.142")
 
@@ -40,7 +40,7 @@ func ExampleReader_Lookup_interface() {
 	if err != nil {
 		log.Fatal(err)
 	}
-	defer db.Close() //nolint:errcheck // error doesn't matter
+	defer db.Close()
 
 	addr := netip.MustParseAddr("81.2.69.142")
 
@@ -50,7 +50,6 @@ func ExampleReader_Lookup_interface() {
 		log.Panic(err)
 	}
 	fmt.Printf("%v", record)
-	//nolint:lll
 	// Output:
 	// map[city:map[geoname_id:2643743 names:map[de:London en:London es:Londres fr:Londres ja:ロンドン pt-BR:Londres ru:Лондон]] continent:map[code:EU geoname_id:6255148 names:map[de:Europa en:Europe es:Europa fr:Europe ja:ヨーロッパ pt-BR:Europa ru:Европа zh-CN:欧洲]] country:map[geoname_id:2635167 iso_code:GB names:map[de:Vereinigtes Königreich en:United Kingdom es:Reino Unido fr:Royaume-Uni ja:イギリス pt-BR:Reino Unido ru:Великобритания zh-CN:英国]] location:map[accuracy_radius:10 latitude:51.5142 longitude:-0.0931 time_zone:Europe/London] registered_country:map[geoname_id:6252001 iso_code:US names:map[de:USA en:United States es:Estados Unidos fr:États-Unis ja:アメリカ合衆国 pt-BR:Estados Unidos ru:США zh-CN:美国]] subdivisions:[map[geoname_id:6269131 iso_code:ENG names:map[en:England es:Inglaterra fr:Angleterre pt-BR:Inglaterra]]]]
 }
@@ -62,7 +61,7 @@ func ExampleReader_Networks() {
 	if err != nil {
 		log.Fatal(err)
 	}
-	defer db.Close() //nolint:errcheck // error doesn't matter
+	defer db.Close()
 
 	for result := range db.Networks() {
 		record := struct {
@@ -108,7 +107,7 @@ func ExampleReader_Verify() {
 	if err != nil {
 		log.Fatal(err)
 	}
-	defer db.Close() //nolint:errcheck // error doesn't matter
+	defer db.Close()
 
 	// Verify database integrity
 	if err := db.Verify(); err != nil {
@@ -142,7 +141,7 @@ func ExampleReader_NetworksWithin() {
 	if err != nil {
 		log.Fatal(err)
 	}
-	defer db.Close() //nolint:errcheck // error doesn't matter
+	defer db.Close()
 
 	prefix, err := netip.ParsePrefix("1.0.0.0/8")
 	if err != nil {
@@ -172,6 +171,80 @@ func ExampleReader_NetworksWithin() {
 	// 1.0.128.0/17: Cable/DSL
 }
 
+// This example demonstrates how to use SkipEmptyValues to iterate only over
+// networks that have actual data, skipping those with empty maps or arrays.
+func ExampleSkipEmptyValues() {
+	db, err := maxminddb.Open("test-data/test-data/GeoIP2-Anonymous-IP-Test.mmdb")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer db.Close()
+
+	// Without SkipEmptyValues, you get all networks including empty ones
+	fmt.Println("All networks:")
+	count := 0
+	for result := range db.Networks() {
+		if result.Err() != nil {
+			log.Panic(result.Err())
+		}
+		count++
+		if count > 10 {
+			fmt.Printf("... (%d more networks, many with empty data)\n", 529-count)
+			break
+		}
+
+		var record map[string]any
+		err := result.Decode(&record)
+		if err != nil {
+			log.Panic(err)
+		}
+
+		if len(record) == 0 {
+			fmt.Printf("%s: (empty)\n", result.Prefix())
+		} else {
+			fmt.Printf("%s: %v\n", result.Prefix(), record)
+		}
+	}
+
+	fmt.Println("\nOnly networks with data:")
+	// With SkipEmptyValues, you only get networks with actual data
+	for result := range db.Networks(maxminddb.SkipEmptyValues()) {
+		if result.Err() != nil {
+			log.Panic(result.Err())
+		}
+
+		var record map[string]any
+		err := result.Decode(&record)
+		if err != nil {
+			log.Panic(result.Err())
+		}
+		fmt.Printf("%s: %v\n", result.Prefix(), record)
+	}
+
+	// Output:
+	// All networks:
+	// 1.0.0.0/15: (empty)
+	// 1.2.0.0/16: map[is_anonymous:true is_anonymous_vpn:true]
+	// 1.3.0.0/16: (empty)
+	// 1.4.0.0/14: (empty)
+	// 1.8.0.0/13: (empty)
+	// 1.16.0.0/12: (empty)
+	// 1.32.0.0/11: (empty)
+	// 1.64.0.0/11: (empty)
+	// 1.96.0.0/12: (empty)
+	// 1.112.0.0/13: (empty)
+	// ... (518 more networks, many with empty data)
+	//
+	// Only networks with data:
+	// 1.2.0.0/16: map[is_anonymous:true is_anonymous_vpn:true]
+	// 1.124.213.1/32: map[is_anonymous:true is_anonymous_vpn:true is_tor_exit_node:true]
+	// 65.0.0.0/13: map[is_anonymous:true is_tor_exit_node:true]
+	// 71.160.223.0/24: map[is_anonymous:true is_hosting_provider:true]
+	// 81.2.69.0/24: map[is_anonymous:true is_anonymous_vpn:true is_hosting_provider:true is_public_proxy:true is_residential_proxy:true is_tor_exit_node:true]
+	// 186.30.236.0/24: map[is_anonymous:true is_public_proxy:true]
+	// abcd:1000::/112: map[is_anonymous:true is_public_proxy:true]
+}
+
 // CustomCity represents a simplified city record with custom unmarshaling.
 // This demonstrates the Unmarshaler interface for custom decoding.
 type CustomCity struct {
@@ -252,7 +325,7 @@ func ExampleUnmarshaler() {
 	if err != nil {
 		log.Fatal(err)
 	}
-	defer db.Close() //nolint:errcheck // error doesn't matter
+	defer db.Close()
 
 	addr := netip.MustParseAddr("81.2.69.142")
 

internal/decoder/reflection.go

@@ -30,6 +30,29 @@ func New(buffer []byte) ReflectionDecoder {
 	}
 }
 
+// IsEmptyValueAt checks if the value at the given offset is an empty map or array.
+// Returns true if the value is a map or array with size 0.
+func (d *ReflectionDecoder) IsEmptyValueAt(offset uint) (bool, error) {
+	dataOffset := offset
+	for {
+		kindNum, size, newOffset, err := d.decodeCtrlData(dataOffset)
+		if err != nil {
+			return false, err
+		}
+
+		if kindNum == KindPointer {
+			dataOffset, _, err = d.decodePointer(size, newOffset)
+			if err != nil {
+				return false, err
+			}
+			continue
+		}
+
+		// Check if it's a map or array with size 0
+		return (kindNum == KindMap || kindNum == KindSlice) && size == 0, nil
+	}
+}
+
 // Decode decodes the data value at offset and stores it in the value
 // pointed at by v.
 func (d *ReflectionDecoder) Decode(offset uint, v any) error {

traverse.go

@@ -19,6 +19,7 @@ type netNode struct {
 type networkOptions struct {
 	includeAliasedNetworks bool
 	includeEmptyNetworks   bool
+	skipEmptyValues        bool
 }
 
 var (
@@ -46,6 +47,16 @@ func IncludeNetworksWithoutData() NetworksOption {
 	}
 }
 
+// SkipEmptyValues is an option for Networks and NetworksWithin that makes
+// them skip networks whose data is an empty map or empty array. This is
+// useful for databases that store empty maps or arrays for records without
+// meaningful data, allowing iteration over only records with actual content.
+func SkipEmptyValues() NetworksOption {
+	return func(networks *networkOptions) {
+		networks.skipEmptyValues = true
+	}
+}
+
 // Networks returns an iterator that can be used to traverse the networks in
 // the database.
 //
@@ -169,6 +180,17 @@ func (r *Reader) NetworksWithin(prefix netip.Prefix, options ...NetworksOption)
 
 				if node.pointer > r.Metadata.NodeCount {
 					offset, err := r.resolveDataPointer(node.pointer)
+
+					// Check if we should skip empty values (only if no error)
+					if err == nil && n.skipEmptyValues {
+						var isEmpty bool
+						isEmpty, err = r.decoder.IsEmptyValueAt(uint(offset))
+						if err == nil && isEmpty {
+							// Skip this empty value
+							break
+						}
+					}
+
 					ok := yield(Result{
 						decoder:   r.decoder,
 						ip:        mappedIP(node.ip),