Add the ability to decode a single path

This is more ergonomic than creating a struct for a single value and
the performance is better as well due to less reflection:

BenchmarkDecodeCountryCodeWithStruct-8   	 1347441	       882.4 ns/op	       1 B/op	       0 allocs/op
BenchmarkDecodePathCountryCode-8         	 2708011	       445.1 ns/op	       1 B/op	       0 allocs/op

Author: oschwald

decoder.go

@@ -89,6 +89,82 @@ func (d *decoder) decodeToDeserializer(
 	return d.decodeFromTypeToDeserializer(typeNum, size, newOffset, dser, depth+1)
 }
 
+func (d *decoder) decodePath(
+	offset uint,
+	path []any,
+	result reflect.Value,
+) error {
+PATH:
+	for i, v := range path {
+		var (
+			typeNum dataType
+			size    uint
+			err     error
+		)
+		typeNum, size, offset, err = d.decodeCtrlData(offset)
+		if err != nil {
+			return err
+		}
+
+		if typeNum == _Pointer {
+			pointer, _, err := d.decodePointer(size, offset)
+			if err != nil {
+				return err
+			}
+
+			typeNum, size, offset, err = d.decodeCtrlData(pointer)
+			if err != nil {
+				return err
+			}
+		}
+
+		switch v := v.(type) {
+		case string:
+			// We are expecting a map
+			if typeNum != _Map {
+				// XXX - use type names in errors.
+				return fmt.Errorf("expected a map for %s but found %d", v, typeNum)
+			}
+			for i := uint(0); i < size; i++ {
+				var key []byte
+				key, offset, err = d.decodeKey(offset)
+				if err != nil {
+					return err
+				}
+				if string(key) == v {
+					continue PATH
+				}
+				offset, err = d.nextValueOffset(offset, 1)
+				if err != nil {
+					return err
+				}
+			}
+			// Not found. Maybe return a boolean?
+			return nil
+		case int:
+			// We are expecting an array
+			if typeNum != _Slice {
+				// XXX - use type names in errors.
+				return fmt.Errorf("expected a slice for %d but found %d", v, typeNum)
+			}
+			if size < uint(v) {
+				// Slice is smaller than index, not found
+				return nil
+			}
+			// TODO: support negative indexes? Seems useful for subdivisions in
+			// particular.
+			offset, err = d.nextValueOffset(offset, uint(v))
+			if err != nil {
+				return err
+			}
+		default:
+			return fmt.Errorf("unexpected type for %d value in path, %v: %T", i, v, v)
+		}
+	}
+	_, err := d.decode(offset, result, len(path))
+	return err
+}
+
 func (d *decoder) decodeCtrlData(offset uint) (dataType, uint, uint, error) {
 	newOffset := offset + 1
 	if offset >= uint(len(d.buffer)) {

reader_test.go

@@ -316,6 +316,30 @@ func TestDecoder(t *testing.T) {
 	require.NoError(t, reader.Close())
 }
 
+func TestDecodePath(t *testing.T) {
+	reader, err := Open(testFile("MaxMind-DB-test-decoder.mmdb"))
+	require.NoError(t, err)
+
+	result := reader.Lookup(netip.MustParseAddr("::1.1.1.0"))
+	require.NoError(t, result.Err())
+
+	var u16 uint16
+
+	require.NoError(t, result.DecodePath(&u16, "uint16"))
+
+	assert.Equal(t, uint16(100), u16)
+
+	var u uint
+	require.NoError(t, result.DecodePath(&u, "array", 0))
+	assert.Equal(t, uint(1), u)
+
+	require.NoError(t, result.DecodePath(&u, "array", 2))
+	assert.Equal(t, uint(3), u)
+
+	require.NoError(t, result.DecodePath(&u, "map", "mapX", "arrayX", 1))
+	assert.Equal(t, uint(8), u)
+}
+
 type TestInterface interface {
 	method() bool
 }
@@ -902,7 +926,7 @@ func BenchmarkCityLookupNetwork(b *testing.B) {
 	require.NoError(b, db.Close(), "error on close")
 }
 
-func BenchmarkCountryCode(b *testing.B) {
+func BenchmarkDecodeCountryCodeWithStruct(b *testing.B) {
 	db, err := Open("GeoLite2-City.mmdb")
 	require.NoError(b, err)
 
@@ -927,6 +951,27 @@ func BenchmarkCountryCode(b *testing.B) {
 	require.NoError(b, db.Close(), "error on close")
 }
 
+func BenchmarkDecodePathCountryCode(b *testing.B) {
+	db, err := Open("GeoLite2-City.mmdb")
+	require.NoError(b, err)
+
+	path := []any{"country", "iso_code"}
+
+	//nolint:gosec // this is a test
+	r := rand.New(rand.NewSource(0))
+	var result string
+
+	s := make(net.IP, 4)
+	for i := 0; i < b.N; i++ {
+		ip := randomIPv4Address(r, s)
+		err = db.Lookup(ip).DecodePath(&result, path...)
+		if err != nil {
+			b.Error(err)
+		}
+	}
+	require.NoError(b, db.Close(), "error on close")
+}
+
 func randomIPv4Address(r *rand.Rand, ip []byte) netip.Addr {
 	num := r.Uint32()
 	ip[0] = byte(num >> 24)

result.go

@@ -46,6 +46,51 @@ func (r Result) Decode(v any) error {
 	return err
 }
 
+// DecodePath unmarshals a value from data section into v, following the
+// specified path.
+//
+// The v parameter should be a pointer to the value where the decoded data
+// will be stored. If v is nil or not a pointer, an error is returned. If the
+// data in the database record cannot be stored in v because of type
+// differences, an UnmarshalTypeError is returned.
+//
+// The path is a variadic list of keys (strings) and/or indices (ints) that
+// describe the nested structure to traverse in the data to reach the desired
+// value.
+//
+// For maps, string path elements are used as keys.
+// For arrays, int path elements are used as indices.
+//
+// If the path is empty, the entire data structure is decoded into v.
+//
+// Returns an error if:
+//   - the path is invalid
+//   - the data cannot be decoded into the type of v
+//   - v is not a pointer or the database record cannot be stored in v due to
+//     type mismatch
+//   - the Result does not contain valid data
+//
+// Example usage:
+//
+//	var city string
+//	err := result.DecodePath(&city, "location", "city", "names", "en")
+//
+//	var geonameID int
+//	err := result.DecodePath(&geonameID, "subdivisions", 0, "geoname_id")
+func (r Result) DecodePath(v any, path ...any) error {
+	if r.err != nil {
+		return r.err
+	}
+	if r.offset == notFound {
+		return nil
+	}
+	rv := reflect.ValueOf(v)
+	if rv.Kind() != reflect.Ptr || rv.IsNil() {
+		return errors.New("result param must be a pointer")
+	}
+	return r.decoder.decodePath(r.offset, path, rv)
+}
+
 // Err provides a way to check whether there was an error during the lookup
 // without clling Result.Decode. If there was an error, it will also be
 // returned from Result.Decode.