Handle the extract methods in Entry and File.

Add v3 versions and warning messages to the v2 versions. We need to do
these methods like this because the new versions are very different.

.rubocop_todo.yml

@@ -9,7 +9,7 @@
 # Offense count: 15
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 590
+  Max: 600
 
 # Offense count: 26
 Metrics/CyclomaticComplexity:

lib/zip/entry.rb

@@ -189,6 +189,8 @@ def next_header_offset #:nodoc:all
     # NB: The caller is responsible for making sure dest_path is safe, if it
     # is passed.
     def extract(dest_path = nil, &block)
+      Zip.warn_about_v3_api('Zip::Entry#extract')
+
       if dest_path.nil? && !name_safe?
         warn "WARNING: skipped '#{@name}' as unsafe."
         return self
@@ -203,6 +205,28 @@ def extract(dest_path = nil, &block)
       self
     end
 
+    # Extracts this entry to a file at `entry_path`, with
+    # `destination_directory` as the base location in the filesystem.
+    #
+    # NB: The caller is responsible for making sure `destination_directory` is
+    # safe, if it is passed.
+    def extract_v3(entry_path = @name, destination_directory: '.', &block)
+      dest_dir = ::File.absolute_path(destination_directory || '.')
+      extract_path = ::File.absolute_path(::File.join(dest_dir, entry_path))
+
+      unless extract_path.start_with?(dest_dir)
+        warn "WARNING: skipped extracting '#{@name}' to '#{extract_path}' as unsafe."
+        return self
+      end
+
+      block ||= proc { ::Zip.on_exists_proc }
+
+      raise "unknown file type #{inspect}" unless directory? || file? || symlink?
+
+      __send__(:"create_#{ftype}", extract_path, &block)
+      self
+    end
+
     def to_s
       @name
     end

lib/zip/file.rb

@@ -371,11 +371,25 @@ def replace(entry, src_path)
 
     # Extracts entry to file dest_path.
     def extract(entry, dest_path, &block)
+      Zip.warn_about_v3_api('Zip::File#extract')
+
       block ||= proc { ::Zip.on_exists_proc }
       found_entry = get_entry(entry)
       found_entry.extract(dest_path, &block)
     end
 
+    # Extracts `entry` to a file at `entry_path`, with `destination_directory`
+    # as the base location in the filesystem.
+    #
+    # NB: The caller is responsible for making sure `destination_directory` is
+    # safe, if it is passed.
+    def extract_v3(entry, entry_path = nil, destination_directory: '.', &block)
+      block ||= proc { ::Zip.on_exists_proc }
+      found_entry = get_entry(entry)
+      entry_path ||= found_entry.name
+      found_entry.extract_v3(entry_path, destination_directory: destination_directory, &block)
+    end
+
     # Commits changes that has been made since the previous commit to
     # the zip archive.
     def commit