Fix extractTo overload ambiguity for single item indices

When calling `BitInputArchive::extractTo` with a single `std::uint32_t` index, particularly the literal `0`, overload resolution could be ambiguous. This occurred because `0` is convertible to both `BitIndicesView` and `std::function`-based callbacks. Adding explicit `std::uint32_t` overloads ensures correct resolution through standard conversions, improving usability.

Author: rikyoz

include/bit7z/bitinputarchive.hpp

@@ -255,6 +255,14 @@ class BitInputArchive {
          */
         void extractTo( const tstring& outDir, BitIndicesView indices = {} ) const;
 
+        /**
+         * @brief Extracts the item at the given index to the chosen directory.
+         *
+         * @param outDir  the output directory where the extracted file will be put.
+         * @param index   the index of the item to be extracted.
+         */
+        void extractTo( const tstring& outDir, std::uint32_t index ) const;
+
         /**
          * @brief Extracts to the output directory all the items whose paths match the given wildcard pattern.
          *
@@ -508,6 +516,14 @@ class BitInputArchive {
          */
         void extractTo( ItemBufferCallback callback, BitIndicesView indices = {} ) const;
 
+        /**
+         * @brief Extracts the item at the given index to the buffer provided by the given ItemBufferCallback.
+         *
+         * @param callback  the function providing the buffer.
+         * @param index     the index of the item to be extracted.
+         */
+        void extractTo( ItemBufferCallback callback, std::uint32_t index ) const;
+
         /**
          * @brief Extracts to the buffers provided by the given ItemBufferCallback
          *        all the items that satisfy the given filtering criteria.

src/bitinputarchive.cpp

@@ -562,6 +562,16 @@ void BitInputArchive::extractMatchingTo( const tstring& outDir, const tregex& re
 
 #endif
 
+/* Note: even though BitIndicesView is implicitly constructible from a single index, this overload is needed
+ * because plain zero indices (e.g., a literal 0) are also null pointer constants: without it, they would be
+ * ambiguously convertible to both BitIndicesView and the std::function-based callbacks of the sibling
+ * overloads. A std::uint32_t argument instead binds here via a standard conversion,
+ * which takes precedence over the user-defined ones. */
+void BitInputArchive::extractTo( const tstring& outDir, std::uint32_t index ) const {
+    // Note: the explicit BitIndicesView is needed to avoid recursing into this same overload.
+    extractTo( outDir, BitIndicesView{ index } );
+}
+
 void BitInputArchive::extractTo( const tstring& outDir, FilterCallback filterCallback ) const {
     const auto callback = bit7z::make_com< FileExtractCallback, ExtractCallback >(
         *this,
@@ -914,6 +924,16 @@ void BitInputArchive::extractTo( ItemBufferCallback callback, BitIndicesView ind
     extractArchive( extractCallback, ExtractMode::Extract, indices );
 }
 
+/* Note: even though BitIndicesView is implicitly constructible from a single index, this overload is needed
+ * because plain zero indices (e.g., a literal 0) are also null pointer constants: without it, they would be
+ * ambiguously convertible to both BitIndicesView and the FilterCallback of the sibling overload.
+ * A std::uint32_t argument instead binds here via a standard conversion,
+ * which takes precedence over the user-defined ones. */
+void BitInputArchive::extractTo( ItemBufferCallback callback, std::uint32_t index ) const {
+    // Note: the explicit BitIndicesView is needed to avoid recursing into this same overload.
+    extractTo( std::move( callback ), BitIndicesView{ index } );
+}
+
 void BitInputArchive::extractTo( ItemBufferCallback callback, FilterCallback filterCallback ) const {
     if ( !callback ) {
         throw BitException(

tests/src/test_bitinputarchive.cpp

@@ -2048,12 +2048,59 @@ TEMPLATE_TEST_CASE(
     }
 
     SECTION( "A valid index extracts correctly" ) {
-        /* Note: passing a plain 0 here would be ambiguous between the BitIndicesView
-         * and FilterCallback overloads, so we need to explicitly use a BitIndicesView. */
+        REQUIRE_NOTHROW( info.extractTo( bufferCallback, 0 ) );
+        REQUIRE( crc32( outBuffer ) == clouds.crc32 );
+    }
+}
+
+// NOLINTNEXTLINE(*-err58-cpp)
+TEST_CASE( "BitInputArchive: Single-index extractTo overloads resolve unambiguously for plain index values",
+           "[bitinputarchive]" ) {
+    const TestDirectory testDir{ fs::path{ test_archives_dir } / "extraction" / "single_file" };
+
+    const auto arcFileName = fs::path{ clouds.name }.concat( ".7z" );
+
+    tstring inputArchive;
+    getInputArchive( arcFileName, inputArchive );
+    const BitArchiveReader info( test::sevenzipLib(), inputArchive, BitFormat::SevenZip );
+
+    buffer_t outBuffer;
+    const auto bufferCallback = [ &outBuffer ]( const BitArchiveItem&, const tstring& ) -> buffer_t& {
+        return outBuffer;
+    };
+
+    SECTION( "Extracting via ItemBufferCallback using a plain index" ) {
+        /* Regression check: previously, a plain 0 was ambiguous between
+         * the BitIndicesView and FilterCallback overloads. */
+        REQUIRE_NOTHROW( info.extractTo( bufferCallback, 0 ) );
+        REQUIRE( crc32( outBuffer ) == clouds.crc32 );
+
+        /* Note: MSVC treats const-zero variables as null pointer constants,
+         * so this also used to be ambiguous. */
         const std::uint32_t index = 0;
-        REQUIRE_NOTHROW( info.extractTo( bufferCallback, BitIndicesView( index ) ) );
+        REQUIRE_NOTHROW( info.extractTo( bufferCallback, index ) );
         REQUIRE( crc32( outBuffer ) == clouds.crc32 );
     }
+
+    SECTION( "Extracting to a directory using a plain index" ) {
+        /* Regression check: previously, a plain 0 was ambiguous between the BitIndicesView,
+         * FilterCallback, RenameCallback, and LegacyRenameCallback overloads. */
+        const TempTestDirectory outputDir{ "test_bitinputarchive" };
+        INFO( "Test directory: " << outputDir )
+
+        REQUIRE_NOTHROW( info.extractTo( outputDir, 0 ) );
+        for ( const auto& expectedItem : singleFileContent().items ) {
+            REQUIRE_FILESYSTEM_ITEM( expectedItem );
+        }
+        REQUIRE( fs::is_empty( outputDir.path() ) );
+    }
+
+    SECTION( "An out-of-range plain index must be rejected with BitError::InvalidIndex" ) {
+        REQUIRE_THROWS_CODE( info.extractTo( bufferCallback, 999 ), BitError::InvalidIndex );
+
+        const TempTestDirectory outputDir{ "test_bitinputarchive" };
+        REQUIRE_THROWS_CODE( info.extractTo( outputDir, 999 ), BitError::InvalidIndex );
+    }
 }
 
 // NOLINTNEXTLINE(*-err58-cpp)