[api] Provide a mean to know whether QgsVectorLayerUtils' guessFriend…

…lyIdentifierField function picked a friendly identifier
qgis · Oct 19, 2021 · 7cc5533 · 7cc5533
1 parent a329b88
commit 7cc5533
Show file tree

Hide file tree

Showing 4 changed files with 93 additions and 3 deletions.
diff --git a/python/core/auto_generated/vector/qgsvectorlayerutils.sip.in b/python/core/auto_generated/vector/qgsvectorlayerutils.sip.in
@@ -347,16 +347,46 @@ feature depending on the join's "upsert on edit" capabilities.
 .. versionadded:: 3.14
 %End
 
+
+    static QString guessFriendlyIdentifierField( const QgsFields &fields, bool *foundFriendly /Out/ = 0 ) /PyName=guessFriendlyIdentifierFieldV2/;
+%Docstring
+Given a set of fields, attempts to pick the "most useful" field
+for user-friendly identification of features.
+
+For instance, if a field called "name" is present, this will be returned.
+
+Assumes that the user has organized the data with the more "interesting" field
+names first. As such, "name" would be selected before "oldname", "othername", etc.
+
+If no friendly identifier is found, the function will fallback to the
+first available.
+
+:param fields: list of fields to pick a friendly identifier from
+
+:return: - field name
+         - foundFriendly: set to ``True`` if the returned field name is a friendly identifier
+
+.. versionadded:: 3.22
+%End
+
+
     static QString guessFriendlyIdentifierField( const QgsFields &fields );
 %Docstring
-Given a set of ``fields``, attempts to pick the "most useful" field
+Given a set of fields, attempts to pick the "most useful" field
 for user-friendly identification of features.
 
 For instance, if a field called "name" is present, this will be returned.
 
 Assumes that the user has organized the data with the more "interesting" field
 names first. As such, "name" would be selected before "oldname", "othername", etc.
 
+If no friendly identifier is found, the function will fallback to the
+first available.
+
+:param fields: list of fields to pick a friendly identifier from
+
+:return: field name
+
 .. versionadded:: 3.18
 %End
 

diff --git a/src/core/vector/qgsvectorlayerutils.cpp b/src/core/vector/qgsvectorlayerutils.cpp
@@ -1125,8 +1125,11 @@ bool QgsVectorLayerUtils::impactsCascadeFeatures( const QgsVectorLayer *layer, c
   return !context.layers().isEmpty();
 }
 
-QString QgsVectorLayerUtils::guessFriendlyIdentifierField( const QgsFields &fields )
+QString QgsVectorLayerUtils::guessFriendlyIdentifierField( const QgsFields &fields, bool *foundFriendly )
 {
+  if ( foundFriendly )
+    *foundFriendly = false;
+
   if ( fields.isEmpty() )
     return QString();
 
@@ -1197,6 +1200,8 @@ QString QgsVectorLayerUtils::guessFriendlyIdentifierField( const QgsFields &fiel
   const QString candidateName = bestCandidateName.isEmpty() ? bestCandidateNameWithAntiCandidate : bestCandidateName;
   if ( !candidateName.isEmpty() )
   {
+    if ( foundFriendly )
+      *foundFriendly = true;
     return candidateName;
   }
   else

diff --git a/src/core/vector/qgsvectorlayerutils.h b/src/core/vector/qgsvectorlayerutils.h
@@ -373,18 +373,70 @@ class CORE_EXPORT QgsVectorLayerUtils
      */
     static bool impactsCascadeFeatures( const QgsVectorLayer *layer, const QgsFeatureIds &fids, const QgsProject *project, QgsDuplicateFeatureContext &context SIP_OUT, QgsVectorLayerUtils::CascadedFeatureFlags flags = QgsVectorLayerUtils::CascadedFeatureFlags() );
 
+#ifndef SIP_RUN
+
+    /**
+     * Given a set of fields, attempts to pick the "most useful" field
+     * for user-friendly identification of features.
+     *
+     * For instance, if a field called "name" is present, this will be returned.
+     *
+     * Assumes that the user has organized the data with the more "interesting" field
+     * names first. As such, "name" would be selected before "oldname", "othername", etc.
+     *
+     * If no friendly identifier is found, the function will fallback to the
+     * first available.
+     *
+     * An optional boolean parameter can be used to determine whether the returned
+     * field name is a friendly identifier or not.
+     *
+     * \param fields list of fields to pick a friendly identifier from
+     * \param foundFriendly set to TRUE if the returned field name is a friendly identifier (since QGIS 3.22)
+     * \returns field name
+     * \since QGIS 3.18
+     */
+#else
+
     /**
-     * Given a set of \a fields, attempts to pick the "most useful" field
+     * Given a set of fields, attempts to pick the "most useful" field
      * for user-friendly identification of features.
      *
      * For instance, if a field called "name" is present, this will be returned.
      *
      * Assumes that the user has organized the data with the more "interesting" field
      * names first. As such, "name" would be selected before "oldname", "othername", etc.
      *
+     * If no friendly identifier is found, the function will fallback to the
+     * first available.
+     *
+     * \param fields list of fields to pick a friendly identifier from
+     * \param foundFriendly set to TRUE if the returned field name is a friendly identifier
+     * \returns field name
+     * \since QGIS 3.22
+     */
+#endif
+    static QString guessFriendlyIdentifierField( const QgsFields &fields, bool *foundFriendly SIP_OUT = nullptr ) SIP_PYNAME( guessFriendlyIdentifierFieldV2 );
+
+#ifdef SIP_RUN
+
+    /**
+     * Given a set of fields, attempts to pick the "most useful" field
+     * for user-friendly identification of features.
+     *
+     * For instance, if a field called "name" is present, this will be returned.
+     *
+     * Assumes that the user has organized the data with the more "interesting" field
+     * names first. As such, "name" would be selected before "oldname", "othername", etc.
+     *
+     * If no friendly identifier is found, the function will fallback to the
+     * first available.
+     *
+     * \param fields list of fields to pick a friendly identifier from
+     * \returns field name
      * \since QGIS 3.18
      */
     static QString guessFriendlyIdentifierField( const QgsFields &fields );
+#endif
 
 };
 

diff --git a/tests/src/python/test_qgsvectorlayerutils.py b/tests/src/python/test_qgsvectorlayerutils.py
@@ -790,12 +790,15 @@ def testGuessFriendlyIdentifierField(self):
 
         fields.append(QgsField('id', QVariant.Int))
         self.assertEqual(QgsVectorLayerUtils.guessFriendlyIdentifierField(fields), 'id')
+        self.assertEqual(QgsVectorLayerUtils.guessFriendlyIdentifierFieldV2(fields), ('id', False))
 
         fields.append(QgsField('name', QVariant.String))
         self.assertEqual(QgsVectorLayerUtils.guessFriendlyIdentifierField(fields), 'name')
+        self.assertEqual(QgsVectorLayerUtils.guessFriendlyIdentifierFieldV2(fields), ('name', True))
 
         fields.append(QgsField('title', QVariant.String))
         self.assertEqual(QgsVectorLayerUtils.guessFriendlyIdentifierField(fields), 'name')
+        self.assertEqual(QgsVectorLayerUtils.guessFriendlyIdentifierFieldV2(fields), ('name', True))
 
         # regardless of actual field order, we prefer "name" over "title"
         fields = QgsFields()