Add test for ordinal schematic sheet paths.

eeschema/sch_sheet_path.cpp

@@ -1456,3 +1456,19 @@ bool SCH_SHEET_LIST::ContainsSheet( const SCH_SHEET* aSheet ) const
 
     return false;
 }
+
+
+std::optional<SCH_SHEET_PATH> SCH_SHEET_LIST::GetOrdinalPath( const SCH_SCREEN* aScreen ) const
+{
+    // Sheet paths with sheets that do not have a screen object are not valid.
+    if( !aScreen )
+        return std::nullopt;
+
+    for( const SCH_SHEET_PATH& path: *this )
+    {
+        if( path.LastScreen() == aScreen )
+            return std::optional<SCH_SHEET_PATH>( path );
+    }
+
+    return std::nullopt;
+}

eeschema/sch_sheet_path.h

@@ -696,6 +696,17 @@ public:
 
     bool ContainsSheet( const SCH_SHEET* aSheet ) const;
 
+    /**
+     * Return the ordinal sheet path of \a aScreen.
+     *
+     * @warning In order for this method to work correctly, the sheet list must be sorted by page
+     *          number.
+     *
+     * @return an optional #SCH_SHEET_PATH for the ordinal path of \a aScreen or an empty value
+     *         if \a aScreen has no ordinal sheet path in the list.
+     */
+    std::optional<SCH_SHEET_PATH> GetOrdinalPath( const SCH_SCREEN* aScreen ) const;
+
 private:
     SCH_SHEET_PATH  m_currentSheetPath;
 };

qa/tests/eeschema/test_sch_sheet_path.cpp

@@ -28,10 +28,14 @@
 
 #include <qa_utils/uuid_test_utils.h>
 #include <qa_utils/wx_utils/unit_test_utils.h>
+#include "eeschema_test_utils.h"
 
 // Code under test
 #include <sch_sheet_path.h>
 
+#include <wildcards_and_files_ext.h>
+#include <eeschema_helpers.h>
+#include <sch_screen.h>
 #include <sch_sheet.h>
 
 #include <sstream>
@@ -129,6 +133,35 @@ BOOST_AUTO_TEST_CASE( Compare )
 }
 
 
+BOOST_AUTO_TEST_CASE( SheetListGetOrdinalPath )
+{
+    // The "complex_hierarchy" test project has a root sheet with two sheets that reference the
+    // same file.
+    std::unique_ptr<SCHEMATIC> schematic;
+    wxFileName fn( KI_TEST::GetEeschemaTestDataDir() + wxS( "netlists/complex_hierarchy" ),
+                   wxS( "complex_hierarchy" ), FILEEXT::ProjectFileExtension );
+
+    schematic.reset( EESCHEMA_HELPERS::LoadSchematic( fn.GetFullPath(), false, false, nullptr ) );
+
+    SCH_SHEET_LIST hierarchy = schematic->Hierarchy();
+    BOOST_CHECK_EQUAL( hierarchy.size(), 3 );
+
+    // A null pointer should always result in an empty return value.
+    BOOST_CHECK( !hierarchy.GetOrdinalPath( nullptr ) );
+
+    // The root sheet is a single instance.  It's always ordinal.
+    BOOST_CHECK( hierarchy.GetOrdinalPath( schematic->RootScreen() ).value() == hierarchy.at( 0 ) );
+
+    // The shared schematic with the lowest page number is the ordinal sheet path.
+    SCH_SHEET* sheet = hierarchy.at( 1 ).Last();
+    BOOST_CHECK( hierarchy.GetOrdinalPath( sheet->GetScreen() ).value() == hierarchy.at( 1 ) );
+
+    // The shared sheet with a higher page number is not the ordinal sheet path.
+    sheet = hierarchy.at( 2 ).Last();
+    BOOST_CHECK( hierarchy.GetOrdinalPath( sheet->GetScreen() ).value() == hierarchy.at( 1 ) );
+}
+
+
 /**
  * Test sheet path page number properties.
  */