Document pointer pattern for path existence checking

Add documentation and tests showing how to use pointer types with
DecodePath to check if a path exists rather than relying on zero values.
This follows standard Go patterns for optional values.

Author: oschwald

reader_test.go

@@ -367,6 +367,16 @@ func TestDecodePath(t *testing.T) {
 	var ne uint
 	require.NoError(t, result.DecodePath(&ne, "does-not-exist", 1))
 	assert.Equal(t, uint(0), ne)
+
+	// Test pointer pattern for path existence checking
+	var existingStringPtr *string
+	require.NoError(t, result.DecodePath(&existingStringPtr, "utf8_string"))
+	assert.NotNil(t, existingStringPtr, "existing path should decode to non-nil pointer")
+	assert.Equal(t, "unicode! ☯ - ♫", *existingStringPtr)
+
+	var nonExistentStringPtr *string
+	require.NoError(t, result.DecodePath(&nonExistentStringPtr, "does-not-exist"))
+	assert.Nil(t, nonExistentStringPtr, "non-existent path should decode to nil pointer")
 }
 
 type TestInterface interface {

result.go

@@ -59,6 +59,20 @@ func (r Result) Decode(v any) error {
 //
 // If the path is empty, the entire data structure is decoded into v.
 //
+// To check if a path exists (rather than relying on zero values), decode
+// into a pointer and check if it remains nil:
+//
+//	var city *string
+//	err := result.DecodePath(&city, "city", "names", "en")
+//	if err != nil {
+//		// Handle error
+//	}
+//	if city == nil {
+//		// Path not found
+//	} else {
+//		// Path exists, city contains the value
+//	}
+//
 // Returns an error if:
 //   - the path is invalid
 //   - the data cannot be decoded into the type of v
@@ -69,7 +83,7 @@ func (r Result) Decode(v any) error {
 // Example usage:
 //
 //	var city string
-//	err := result.DecodePath(&city, "location", "city", "names", "en")
+//	err := result.DecodePath(&city, "city", "names", "en")
 //
 //	var geonameID int
 //	err := result.DecodePath(&geonameID, "subdivisions", 0, "geoname_id")