Added wrapper class for Metadatum& references

These can be invalidated, just like iterators can be, so need a wrapper
to enable protection from segfaults.

Author: jim-easterbrook

src/interface/exif.i

@@ -27,6 +27,7 @@
 %include "shared/buffers.i"
 %include "shared/containers.i"
 %include "shared/data_iterator.i"
+%include "shared/metadatum_reference.i"
 %include "shared/keep_reference.i"
 %include "shared/windows.i"
 
@@ -52,10 +53,12 @@ KEEP_REFERENCE_EX(Exiv2::ExifThumb*, args)
 
 INPUT_BUFFER_RO(const Exiv2::byte* buf, BUFLEN_T size)
 
-EXTEND_METADATUM(Exiv2::Exifdatum)
+EXTEND_METADATUM(Exifdatum)
 
 DATA_ITERATOR(ExifData, Exifdatum)
 
+METADATUM_REFERENCE(Exifdatum)
+
 // Get the current (or default if not set) type id of a datum
 %fragment("get_type_id"{Exiv2::Exifdatum}, "header") {
 static Exiv2::TypeId get_type_id(Exiv2::Exifdatum* datum) {

src/interface/iptc.i

@@ -26,6 +26,7 @@
 %include "shared/preamble.i"
 %include "shared/containers.i"
 %include "shared/data_iterator.i"
+%include "shared/metadatum_reference.i"
 
 %include "stdint.i"
 %include "std_string.i"
@@ -38,10 +39,12 @@ IMPORT_ENUM(TypeId)
 // Catch all C++ exceptions
 EXCEPTION()
 
-EXTEND_METADATUM(Exiv2::Iptcdatum)
+EXTEND_METADATUM(Iptcdatum)
 
 DATA_ITERATOR(IptcData, Iptcdatum)
 
+METADATUM_REFERENCE(Iptcdatum)
+
 // Get the current (or default if not set) type id of a datum
 %fragment("get_type_id"{Exiv2::Iptcdatum}, "header") {
 static Exiv2::TypeId get_type_id(Exiv2::Iptcdatum* datum) {

src/interface/metadatum.i

@@ -57,17 +57,19 @@ EXTEND_KEY(Exiv2::Key);
 // Macro for Metadatum subclasses
 %define EXTEND_METADATUM(datum_type)
 // Ignore overloaded default parameter version
-%ignore datum_type::write(std::ostream &) const;
+%ignore Exiv2::datum_type::write(std::ostream &) const;
 // Keep a reference to Metadatum when calling value()
 KEEP_REFERENCE(const Exiv2::Value&)
 // Keep a reference to any object that returns a reference to a datum.
-KEEP_REFERENCE(datum_type&)
+KEEP_REFERENCE(Exiv2::datum_type&)
 // Set the datum's value from a Python object. The datum's current or default
 // type is used to create an Exiv2::Value object (via Python) from the Python
 // object.
-%fragment("set_value_from_py"{datum_type}, "header",
-          fragment="get_type_object", fragment="get_type_id"{datum_type}) {
-static PyObject* set_value_from_py(datum_type* datum, PyObject* py_value) {
+%fragment("set_value_from_py"{Exiv2::datum_type}, "header",
+          fragment="get_type_object",
+          fragment="get_type_id"{Exiv2::datum_type}) {
+static PyObject* set_value_from_py(Exiv2::datum_type* datum,
+                                   PyObject* py_value) {
     swig_type_info* ty_info = get_type_object(get_type_id(datum));
     SwigPyClientData *cl_data = (SwigPyClientData*)ty_info->clientdata;
     // Call type object to invoke constructor
@@ -89,7 +91,7 @@ static PyObject* set_value_from_py(datum_type* datum, PyObject* py_value) {
     return SWIG_Py_Void();
 };
 }
-%extend datum_type {
+%extend Exiv2::datum_type {
     // Extend Metadatum to allow getting value as a specific type.
     Exiv2::Value::SMART_PTR getValue(Exiv2::TypeId as_type) {
         // deprecated since 2023-12-07
@@ -104,7 +106,7 @@ static PyObject* set_value_from_py(datum_type* datum, PyObject* py_value) {
     // Set the value from a Python object. The datum's current or default
     // type is used to create an Exiv2::Value object (via Python) from the
     // Python object.
-    %fragment("set_value_from_py"{datum_type});
+    %fragment("set_value_from_py"{Exiv2::datum_type});
     PyObject* setValue(PyObject* py_value) {
         return set_value_from_py($self, py_value);
     }
@@ -120,8 +122,8 @@ static PyObject* set_value_from_py(datum_type* datum, PyObject* py_value) {
     std::string toString(BUFLEN_T i) const { return self->toString(i); }
 }
 // Deprecate some methods since 2025-08-25
-DEPRECATE_FUNCTION(datum_type::copy, true)
-DEPRECATE_FUNCTION(datum_type::write, true)
+DEPRECATE_FUNCTION(Exiv2::datum_type::copy, true)
+DEPRECATE_FUNCTION(Exiv2::datum_type::write, true)
 %enddef // EXTEND_METADATUM
 
 // Deprecate some base class methods since 2025-08-25

src/interface/shared/metadatum_reference.i

@@ -0,0 +1,104 @@
+/* python-exiv2 - Python interface to libexiv2
+ * http://github.com/jim-easterbrook/python-exiv2
+ * Copyright (C) 2025  Jim Easterbrook  jim@jim-easterbrook.me.uk
+ *
+ * This file is part of python-exiv2.
+ *
+ * python-exiv2 is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * python-exiv2 is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with python-exiv2.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+
+// Macro to wrap metadatum references so they can be invalidated
+%define METADATUM_REFERENCE(datum_type)
+%feature("python:slot", "tp_str", functype="reprfunc")
+    datum_type##_pointer::__str__;
+%noexception datum_type##_pointer::operator==;
+%noexception datum_type##_pointer::operator!=;
+%noexception Exiv2::datum_type::operator==;
+%noexception Exiv2::datum_type::operator!=;
+%ignore datum_type##_pointer::##datum_type##_pointer;
+%ignore datum_type##_pointer::size;
+%ignore datum_type##_pointer::operator*;
+%ignore datum_type##_pointer::_invalidate;
+%feature("docstring") datum_type##_pointer "
+Python wrapper for an :class:`" #datum_type "` reference. It has most of
+the methods of :class:`" #datum_type "` allowing easy access to the
+data it points to."
+%inline %{
+class datum_type##_pointer {
+private:
+    Exiv2::datum_type* ptr;
+    bool invalidated;
+public:
+    datum_type##_pointer(Exiv2::datum_type* ptr) {
+        this->ptr = ptr;
+        invalidated = false;
+    }
+    // Dereference operator gives Python access to all datum methods
+    Exiv2::datum_type* operator->() const {
+        if (invalidated)
+            throw std::runtime_error("datum_type pointer is invalid");
+        return ptr;
+    }
+    Exiv2::datum_type* operator*() const { return ptr; }
+    bool operator==(const Exiv2::datum_type &other) const {
+        return &other == ptr;
+    }
+    bool operator!=(const Exiv2::datum_type &other) const {
+        return &other != ptr;
+    }
+    std::string __str__() {
+        if (invalidated)
+            return "invalid pointer";
+        return "pointer<" + ptr->key() + ": " + ptr->print() + ">";
+    }
+    // Invalidate pointer unilaterally
+    void _invalidate() { invalidated = true; }
+    // Invalidate pointer if what it points to has been deleted
+    bool _invalidate(Exiv2::datum_type* deleted) {
+        if (deleted == ptr)
+            invalidated = true;
+        return invalidated;
+    }
+    // Provide size() C++ method for buffer size check
+    size_t size() {
+        if (invalidated)
+            return 0;
+        return ptr->size();
+    }
+};
+%}
+%extend Exiv2::datum_type {
+    bool operator==(const Exiv2::datum_type &other) const {
+        return &other == self;
+    }
+    bool operator!=(const Exiv2::datum_type &other) const {
+        return &other != self;
+    }
+}
+%typemap(in) const Exiv2::datum_type& {
+    datum_type##_pointer* tmp = NULL;
+    if (SWIG_IsOK(SWIG_ConvertPtr(
+            $input, (void**)&tmp, $descriptor(datum_type##_pointer*), 0)))
+        $1 = **tmp;
+    else {
+        $typemap(in, Exiv2::datum_type&)
+    }
+}
+%typemap(out) Exiv2::datum_type& {
+    $result = SWIG_NewPointerObj(
+        SWIG_as_voidptr(new datum_type##_pointer($1)),
+        $descriptor(datum_type##_pointer*), SWIG_POINTER_OWN);
+}
+%enddef // METADATUM_REFERENCE

src/interface/xmp.i

@@ -26,6 +26,7 @@
 %include "shared/preamble.i"
 %include "shared/containers.i"
 %include "shared/data_iterator.i"
+%include "shared/metadatum_reference.i"
 
 %include "stdint.i"
 %include "std_string.i"
@@ -38,10 +39,12 @@ IMPORT_ENUM(TypeId)
 // Catch all C++ exceptions
 EXCEPTION()
 
-EXTEND_METADATUM(Exiv2::Xmpdatum)
+EXTEND_METADATUM(Xmpdatum)
 
 DATA_ITERATOR(XmpData, Xmpdatum)
 
+METADATUM_REFERENCE(Xmpdatum)
+
 // Get the current (or default if not set) type id of a datum
 %fragment("get_type_id"{Exiv2::Xmpdatum}, "header") {
 static Exiv2::TypeId get_type_id(Exiv2::Xmpdatum* datum) {